From 2925dce614f6091850ddcf2cb2bc63cc56f7336a Mon Sep 17 00:00:00 2001 From: Peter Barnes Date: Thu, 12 Sep 2024 22:25:09 +0000 Subject: [PATCH] doc: enable single TypeId output from p-i-d (fixes #140) --- utils/print-introspected-doxygen.cc | 146 ++++++++++++++++++---------- 1 file changed, 97 insertions(+), 49 deletions(-) diff --git a/utils/print-introspected-doxygen.cc b/utils/print-introspected-doxygen.cc index 61962340b..d268e0ffe 100644 --- a/utils/print-introspected-doxygen.cc +++ b/utils/print-introspected-doxygen.cc @@ -223,7 +223,7 @@ SetMarkup() templateArgument = "\\tparam "; variable = "\\var "; } -} // SetMarkup () +} // SetMarkup() /*************************************************************** * Aggregation and configuration paths @@ -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 @@ -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; } } @@ -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 @@ -580,7 +581,7 @@ GetTypicalAggregations() return info; -} // GetTypicalAggregations () +} // GetTypicalAggregations() /// Map from TypeId name to tid typedef std::map NameMap; @@ -637,7 +638,7 @@ GetNameMap() } return nameMap; -} // GetNameMap () +} // GetNameMap() /*************************************************************** * Docs for a single TypeId @@ -673,7 +674,7 @@ PrintConfigPaths(std::ostream& os, const TypeId tid) } os << listStop << std::endl; } -} // PrintConfigPaths () +} // PrintConfigPaths() /** * Print direct Attributes for this TypeId. @@ -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, @@ -821,7 +822,7 @@ PrintAttributes(std::ostream& os, const TypeId tid) tmp = tmp.GetParent(); } // Attributes -} // PrintAttributes () +} // PrintAttributes() /** * Print direct Trace sources for this TypeId. @@ -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, @@ -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. @@ -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 @@ -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 @@ -991,7 +1007,7 @@ PrintAllTypeIds(std::ostream& os) os << listStop << std::endl; os << commentStop << std::endl; -} // PrintAllTypeIds () +} // PrintAllTypeIds() /** * Print the list of all Attributes. @@ -1043,7 +1059,7 @@ PrintAllAttributes(std::ostream& os) } os << commentStop << std::endl; -} // PrintAllAttributes () +} // PrintAllAttributes() /** * Print the list of all global variables. @@ -1071,7 +1087,7 @@ PrintAllGlobals(std::ostream& os) os << listStop << std::endl; os << commentStop << std::endl; -} // PrintAllGlobals () +} // PrintAllGlobals() /** * Print the list of all LogComponents. @@ -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. @@ -1184,7 +1200,7 @@ PrintAllTraceSources(std::ostream& os) } os << commentStop << std::endl; -} // PrintAllTraceSources () +} // PrintAllTraceSources() /*************************************************************** * Docs for Attribute classes @@ -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. @@ -1260,24 +1276,23 @@ PrintAttributeValueWithName(std::ostream& os, << argument << "[in] value The " << name << " value to use.\n"; os << commentStop; - // Value::Get () const - os << commentStart << functionStart << type << qualClass << "::Get () const\n" + // Value::Get() const + os << commentStart << functionStart << type << qualClass << "::Get() const\n" << returns << "The " << name << " value.\n" << commentStop; - // Value::GetAccessor (T & value) const - os << commentStart << functionStart << "bool" << qualClass - << "::GetAccessor (T & value) const\n" + // 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; - // Value::Set (const name & value) + // 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" @@ -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. @@ -1307,7 +1322,7 @@ PrintMakeAccessors(std::ostream& os, const std::string& name) std::string make = "ns3::Make" + name + "Accessor "; // \ingroup attribute_Value - // MakeAccessor (T1 a1) + // MakeAccessor(T1 a1) os << commentStart << sectAttr << functionStart << "ns3::Ptr " << make << "(T1 a1)\n" << copyDoc << "ns3::MakeAccessorHelper(T1)\n" @@ -1315,13 +1330,13 @@ PrintMakeAccessors(std::ostream& os, const std::string& name) << commentStop; // \ingroup attribute_Value - // MakeAccessor (T1 a1) + // MakeAccessor(T1 a1) os << commentStart << sectAttr << functionStart << "ns3::Ptr " << 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. @@ -1349,13 +1364,13 @@ PrintMakeChecker(std::ostream& os, const std::string& name, const std::string& h os << commentStop; // \ingroup attribute_Value - // MakeChecker () + // MakeChecker() os << commentStart << sectAttr << functionStart << "ns3::Ptr " << make << "()\n" << returns << "The AttributeChecker.\n" << seeAlso << "AttributeChecker\n" << commentStop; -} // PrintMakeChecker () +} // PrintMakeChecker() /**Descriptor for an AttributeValue. */ struct AttributeDescriptor @@ -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. @@ -1451,7 +1466,7 @@ PrintAttributeImplementations(std::ostream& os) PrintMakeAccessors(os, "ObjectMap"); PrintMakeChecker(os, "ObjectMap", "object-map.h"); -} // PrintAttributeImplementations () +} // PrintAttributeImplementations() /*************************************************************** * Main @@ -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