F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: enable single TypeId output from p-i-d (fixes #140)

Browse Source
This commit is contained in:
Peter Barnes
2024-09-12 22:25:09 +00:00
parent c89f33e882
commit 2925dce614
1 changed files with 97 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

146
utils/print-introspected-doxygen.cc
View File

@@ -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<std::string, int32_t> 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;
// <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"
@@ -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_<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"
@@ -1315,13 +1330,13 @@ PrintMakeAccessors(std::ostream& os, const std::string& name)
<< 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.
@@ -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
@@ -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