Skip to content

Commit

Permalink
doc: enable single TypeId output from p-i-d (fixes #140)
Browse files Browse the repository at this point in the history
  • Loading branch information
Peter Barnes committed Sep 12, 2024
1 parent c89f33e commit 2925dce
Showing 1 changed file with 97 additions and 49 deletions.
146 changes: 97 additions & 49 deletions utils/print-introspected-doxygen.cc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -223,7 +223,7 @@ SetMarkup()
templateArgument = "\\tparam ";
variable = "\\var ";
}
} // SetMarkup ()
} // SetMarkup()

/***************************************************************
* Aggregation and configuration paths
Expand All @@ -249,9 +249,10 @@ class StaticInformation
*/
void Gather(TypeId tid);
/**
* Print output in "a -> b" form on std::cout
* Print output in "a -> b" form on the stream.
* \param [in,out] os The output stream.
*/
void Print() const;
void Print(std::ostream& os) const;

/**
* \return the configuration paths for tid
Expand Down Expand Up @@ -337,12 +338,12 @@ StaticInformation::RecordAggregationInfo(std::string a, std::string b)
}

void
StaticInformation::Print() const
StaticInformation::Print(std::ostream& os) const
{
NS_LOG_FUNCTION(this);
for (const auto& item : m_output)
{
std::cout << item.first.GetName() << " -> " << item.second << std::endl;
os << item.first.GetName() << " -> " << item.second << std::endl;
}
}

Expand Down Expand Up @@ -517,7 +518,7 @@ StaticInformation::DoGather(TypeId tid)
m_currentPath.pop_back();
}
}
} // StaticInformation::DoGather ()
} // StaticInformation::DoGather()

/// Register aggregation relationships that are not automatically
/// detected by this introspection program. Statements added here
Expand Down Expand Up @@ -580,7 +581,7 @@ GetTypicalAggregations()

return info;

} // GetTypicalAggregations ()
} // GetTypicalAggregations()

/// Map from TypeId name to tid
typedef std::map<std::string, int32_t> NameMap;
Expand Down Expand Up @@ -637,7 +638,7 @@ GetNameMap()
}

return nameMap;
} // GetNameMap ()
} // GetNameMap()

/***************************************************************
* Docs for a single TypeId
Expand Down Expand Up @@ -673,7 +674,7 @@ PrintConfigPaths(std::ostream& os, const TypeId tid)
}
os << listStop << std::endl;
}
} // PrintConfigPaths ()
} // PrintConfigPaths()

/**
* Print direct Attributes for this TypeId.
Expand Down Expand Up @@ -782,7 +783,7 @@ PrintAttributesTid(std::ostream& os, const TypeId tid)
os << indentHtmlOnly << listStop << std::endl;
}
os << listStop << std::endl;
} // PrintAttributesTid ()
} // PrintAttributesTid()

/**
* Print the Attributes block for tid,
Expand Down Expand Up @@ -821,7 +822,7 @@ PrintAttributes(std::ostream& os, const TypeId tid)
tmp = tmp.GetParent();

} // Attributes
} // PrintAttributes ()
} // PrintAttributes()

/**
* Print direct Trace sources for this TypeId.
Expand Down Expand Up @@ -851,7 +852,7 @@ PrintTraceSourcesTid(std::ostream& os, const TypeId tid)
os << listLineStop << std::endl;
}
os << listStop << std::endl;
} // PrintTraceSourcesTid ()
} // PrintTraceSourcesTid()

/**
* Print the Trace sources block for tid,
Expand Down Expand Up @@ -890,7 +891,7 @@ PrintTraceSources(std::ostream& os, const TypeId tid)
tmp = tmp.GetParent();
}

} // PrintTraceSources ()
} // PrintTraceSources()

/**
* Print the size of the type represented by this tid.
Expand All @@ -908,7 +909,34 @@ PrintSize(std::ostream& os, const TypeId tid)

os << boldStart << "Size" << boldStop << " of this type is " << tid.GetSize() << " bytes (on a "
<< arch << "-bit architecture)." << std::endl;
} // PrintSize ()
} // PrintSize()

/**
* Print the doxy block for a single TypeId
*
* \param [in,out] os The output stream.
* \param [in] tid the TypeId
*/
void
PrintTypeIdBlock(std::ostream& os, const TypeId tid)
{
NS_LOG_FUNCTION(tid);

std::string name = tid.GetName();

os << commentStart << std::endl;

os << classStart << name << std::endl;
os << std::endl;

PrintConfigPaths(os, tid);
PrintAttributes(os, tid);
PrintTraceSources(os, tid);
PrintSize(os, tid);

os << commentStop << std::endl;

} // PrintTypeIdBlock()

/**
* Print the doxy block for each TypeId
Expand All @@ -933,22 +961,10 @@ PrintTypeIdBlocks(std::ostream& os)
}
// Get the class's index out of the map;
TypeId tid = TypeId::GetRegistered(item.second);
std::string name = tid.GetName();

std::cout << commentStart << std::endl;

std::cout << classStart << name << std::endl;
std::cout << std::endl;

PrintConfigPaths(std::cout, tid);
PrintAttributes(std::cout, tid);
PrintTraceSources(std::cout, tid);
PrintSize(std::cout, tid);

std::cout << commentStop << std::endl;
PrintTypeIdBlock(os, tid);
} // for class documentation

} // PrintTypeIdBlocks
} // PrintTypeIdBlocks()

/***************************************************************
* Lists of All things
Expand Down Expand Up @@ -991,7 +1007,7 @@ PrintAllTypeIds(std::ostream& os)
os << listStop << std::endl;
os << commentStop << std::endl;

} // PrintAllTypeIds ()
} // PrintAllTypeIds()

/**
* Print the list of all Attributes.
Expand Down Expand Up @@ -1043,7 +1059,7 @@ PrintAllAttributes(std::ostream& os)
}
os << commentStop << std::endl;

} // PrintAllAttributes ()
} // PrintAllAttributes()

/**
* Print the list of all global variables.
Expand Down Expand Up @@ -1071,7 +1087,7 @@ PrintAllGlobals(std::ostream& os)
os << listStop << std::endl;
os << commentStop << std::endl;

} // PrintAllGlobals ()
} // PrintAllGlobals()

/**
* Print the list of all LogComponents.
Expand Down Expand Up @@ -1130,7 +1146,7 @@ PrintAllLogComponents(std::ostream& os)
}
os << std::right << std::endl;
os << commentStop << std::endl;
} // PrintAllLogComponents ()
} // PrintAllLogComponents()

/**
* Print the list of all Trace sources.
Expand Down Expand Up @@ -1184,7 +1200,7 @@ PrintAllTraceSources(std::ostream& os)
}
os << commentStop << std::endl;

} // PrintAllTraceSources ()
} // PrintAllTraceSources()

/***************************************************************
* Docs for Attribute classes
Expand Down Expand Up @@ -1220,7 +1236,7 @@ PrintAttributeValueSection(std::ostream& os, const std::string& name, const bool
}
os << commentStop;

} // PrintAttributeValueSection ()
} // PrintAttributeValueSection()

/**
* Print the AttributeValue documentation for a class.
Expand Down Expand Up @@ -1260,24 +1276,23 @@ PrintAttributeValueWithName(std::ostream& os,
<< argument << "[in] value The " << name << " value to use.\n";
os << commentStop;

// <name>Value::Get () const
os << commentStart << functionStart << type << qualClass << "::Get () const\n"
// <name>Value::Get() const
os << commentStart << functionStart << type << qualClass << "::Get() const\n"
<< returns << "The " << name << " value.\n"
<< commentStop;

// <name>Value::GetAccessor (T & value) const
os << commentStart << functionStart << "bool" << qualClass
<< "::GetAccessor (T & value) const\n"
// <name>Value::GetAccessor(T & value) const
os << commentStart << functionStart << "bool" << qualClass << "::GetAccessor(T & value) const\n"
<< "Access the " << name << " value as type " << codeWord << "T.\n"
<< templateArgument << "T " << templArgExplicit << "The type to cast to.\n"
<< argument << "[out] value The " << name << " value, as type " << codeWord << "T.\n"
<< returns << "true.\n"
<< commentStop;

// <name>Value::Set (const name & value)
// <name>Value::Set(const name & value)
if (type != "Callback") // Yuck
{
os << commentStart << functionStart << "void" << qualClass << "::Set (const " << type
os << commentStart << functionStart << "void" << qualClass << "::Set(const " << type
<< " & value)\n"
<< "Set the value.\n"
<< argument << "[in] value The value to adopt.\n"
Expand All @@ -1289,7 +1304,7 @@ PrintAttributeValueWithName(std::ostream& os,
<< "The stored " << name << " instance.\n"
<< commentStop << std::endl;

} // PrintAttributeValueWithName ()
} // PrintAttributeValueWithName()

/**
* Print the AttributeValue MakeAccessor documentation for a class.
Expand All @@ -1307,21 +1322,21 @@ PrintMakeAccessors(std::ostream& os, const std::string& name)
std::string make = "ns3::Make" + name + "Accessor ";

// \ingroup attribute_<name>Value
// Make<name>Accessor (T1 a1)
// Make<name>Accessor(T1 a1)
os << commentStart << sectAttr << functionStart << "ns3::Ptr<const ns3::AttributeAccessor> "
<< make << "(T1 a1)\n"
<< copyDoc << "ns3::MakeAccessorHelper(T1)\n"
<< seeAlso << "AttributeAccessor\n"
<< commentStop;

// \ingroup attribute_<name>Value
// Make<name>Accessor (T1 a1)
// Make<name>Accessor(T1 a1)
os << commentStart << sectAttr << functionStart << "ns3::Ptr<const ns3::AttributeAccessor> "
<< make << "(T1 a1, T2 a2)\n"
<< copyDoc << "ns3::MakeAccessorHelper(T1,T2)\n"
<< seeAlso << "AttributeAccessor\n"
<< commentStop;
} // PrintMakeAccessors ()
} // PrintMakeAccessors()

/**
* Print the AttributeValue MakeChecker documentation for a class.
Expand Down Expand Up @@ -1349,13 +1364,13 @@ PrintMakeChecker(std::ostream& os, const std::string& name, const std::string& h
os << commentStop;

// \ingroup attribute_<name>Value
// Make<name>Checker ()
// Make<name>Checker()
os << commentStart << sectAttr << functionStart << "ns3::Ptr<const ns3::AttributeChecker> "
<< make << "()\n"
<< returns << "The AttributeChecker.\n"
<< seeAlso << "AttributeChecker\n"
<< commentStop;
} // PrintMakeChecker ()
} // PrintMakeChecker()

/**Descriptor for an AttributeValue. */
struct AttributeDescriptor
Expand All @@ -1382,7 +1397,7 @@ PrintAttributeHelper(std::ostream& os, const AttributeDescriptor& attr)
PrintAttributeValueWithName(os, attr.m_name, attr.m_type, attr.m_header);
PrintMakeAccessors(os, attr.m_name);
PrintMakeChecker(os, attr.m_name, attr.m_header);
} // PrintAttributeHelper ()
} // PrintAttributeHelper()

/**
* Print documentation for Attribute implementations.
Expand Down Expand Up @@ -1451,7 +1466,7 @@ PrintAttributeImplementations(std::ostream& os)
PrintMakeAccessors(os, "ObjectMap");
PrintMakeChecker(os, "ObjectMap", "object-map.h");

} // PrintAttributeImplementations ()
} // PrintAttributeImplementations()

/***************************************************************
* Main
Expand All @@ -1462,12 +1477,45 @@ main(int argc, char* argv[])
{
NS_LOG_FUNCTION_NOARGS();

std::string typeId;

CommandLine cmd(__FILE__);
cmd.Usage("Generate documentation for all ns-3 registered types, "
"trace sources, attributes and global variables.");
cmd.AddValue("output-text", "format output as plain text", outputText);
cmd.AddValue("TypeId", "Print docs for just the given TypeId", typeId);
cmd.Parse(argc, argv);

if (!typeId.empty())
{
outputText = true;
SetMarkup();

TypeId tid;

bool validTypeId = TypeId::LookupByNameFailSafe(typeId, &tid);
if (!validTypeId)
{
auto fqTypeId = "ns3::" + typeId;
validTypeId = TypeId::LookupByNameFailSafe(fqTypeId, &tid);
if (validTypeId)
{
std::cout << "\nFound fully qualified name " << fqTypeId << "\n\n";
}
}
if (validTypeId)
{
PrintTypeIdBlock(std::cout, tid);
return 0;
}
else
{
std::cerr << "Invalid TypeId name: " << typeId << "\n" << std::endl;
std::cerr << cmd;
exit(1);
}
}

SetMarkup();

// Create a Node, to force linking and instantiation of our TypeIds
Expand Down

0 comments on commit 2925dce

Please sign in to comment.