doc: (fixes #1214) Add html anchors for details sections

utils/print-introspected-doxygen.cc

@@ -44,27 +44,33 @@ bool outputText = false;
  * Markup tokens.
  * @{
  */
-std::string anchor;        ///< hyperlink anchor
+std::string anchor;             ///< hyperlink anchor
-std::string argument;      ///< function argument
+std::string argument;           ///< function argument
-std::string boldStart;     ///< start of bold span
+std::string boldStart;          ///< start of bold span
-std::string boldStop;      ///< end of bold span
+std::string boldStop;           ///< end of bold span
-std::string breakBoth;     ///< linebreak
+std::string boldWithIdStart;    ///< start of bold with id
-std::string breakHtmlOnly; ///< linebreak for html output only
+std::string boldWithIdMid;      ///< middle of bold span with id
-std::string breakTextOnly; ///< linebreak for text output only
+std::string boldWithIdStop;     ///< end of bold span with id
-std::string brief;         ///< brief tag
+std::string breakBoth;          ///< linebreak
-std::string classStart;    ///< start of a class
+std::string breakHtmlOnly;      ///< linebreak for html output only
-std::string classStop;     ///< end of a class
+std::string breakTextOnly;      ///< linebreak for text output only
-std::string codeWord;      ///< format next word as source code
+std::string brief;              ///< brief tag
-std::string commentStart;  ///< start of code comment
+std::string classStart;         ///< start of a class
-std::string commentStop;   ///< end of code comment
+std::string classStop;          ///< end of a class
-std::string copyDoc;       ///< copy (or refer) to docs elsewhere
+std::string codeWord;           ///< format next word as source code
-std::string file;          ///< file
+std::string commentStart;       ///< start of code comment
-std::string flagSpanStart; ///< start of Attribute flag value
+std::string commentStop;        ///< end of code comment
-std::string flagSpanStop;  ///< end of Attribute flag value
+std::string copyDoc;            ///< copy (or refer) to docs elsewhere
-std::string functionStart; ///< start of a method/function
+std::string file;               ///< file
-std::string functionStop;  ///< end of a method/function
+std::string flagSpanStart;      ///< start of Attribute flag value
-std::string headingStart;  ///< start of section heading (h3)
+std::string flagSpanStop;       ///< end of Attribute flag value
-std::string headingStop;   ///< end of section heading (h3)
+std::string functionStart;      ///< start of a method/function
+std::string functionStop;       ///< end of a method/function
+std::string headingStart;       ///< start of section heading (h3)
+std::string headingStop;        ///< end of section heading (h3)
+std::string headingWithIdStart; ///< start of section heading with id (h3)
+std::string headingWithIdMid;   ///< middle of section heading with id (h3)
+std::string headingWithIdStop;  ///< end of section heading with id (h3)
 // Linking:  [The link text displayed](\ref TheTarget)
 std::string hrefStart;        ///< start of a link
 std::string hrefMid;          ///< middle part of a link
@@ -81,6 +87,9 @@ std::string referenceNo;      ///< block automatic references
 std::string returns;          ///< the return value
 std::string sectionStart;     ///< start of a section or group
 std::string seeAlso;          ///< Reference to other docs
+std::string spanWithIdStart;  ///< start of span with id
+std::string spanWithIdMid;    ///< middle of span with id
+std::string spanWithIdStop;   ///< end of span with id
 std::string subSectionStart;  ///< start a new subsection
 std::string templArgDeduced;  ///< template argument deduced from function
 std::string templArgExplicit; ///< template argument required
@@ -124,6 +133,54 @@ SortedTraceSourceInfo(const TypeId tid)
     return index;
 }
 
+/**
+ * Generate bold (b) HTML markup with id if not generating text only.
+ * @param id The element id
+ * @param displayText The text to display
+ * @return The bold markup with id or just displayText if outputText is true
+ */
+std::string
+BoldWithId(const std::string id, const std::string displayText)
+{
+    if (outputText)
+    {
+        return displayText + " ";
+    }
+    return boldWithIdStart + id + boldWithIdMid + displayText + boldWithIdStop + " ";
+}
+
+/**
+ * Generate heading (h3) markup with id if not generating text only.
+ * @param id The element id
+ * @param displayText The text to display
+ * @return The heading markup with id or just displayText if outputText is true
+ */
+std::string
+HeadingWithId(const std::string id, const std::string displayText)
+{
+    if (outputText)
+    {
+        return displayText + " ";
+    }
+    return headingWithIdStart + id + headingWithIdMid + displayText + headingWithIdStop;
+}
+
+/**
+ * Generate span (span) HTML markup with id if not generating text only.
+ * @param id The element id
+ * @param displayText The text to display
+ * @return The span markup with id or just displayText if outputText is true
+ */
+std::string
+SpanWithId(const std::string id, const std::string displayText)
+{
+    if (outputText)
+    {
+        return displayText + " ";
+    }
+    return spanWithIdStart + id + spanWithIdMid + displayText + spanWithIdStop + " ";
+}
+
 } // unnamed namespace
 
 /**
@@ -139,6 +196,9 @@ SetMarkup()
         argument = "  Arg: ";
         boldStart = "";
         boldStop = "";
+        boldWithIdStart = "";
+        boldWithIdMid = "";
+        boldWithIdStop = "";
         breakBoth = "\n";
         breakHtmlOnly = "";
         breakTextOnly = "\n";
@@ -156,6 +216,9 @@ SetMarkup()
         functionStop = "\n\n";
         headingStart = "";
         headingStop = "";
+        headingWithIdStart = "";
+        headingWithIdMid = "";
+        headingWithIdStop = "";
         // Linking:  The link text displayed (see TheTarget)
         hrefStart = "";
         hrefMid = " (see ";
@@ -172,6 +235,9 @@ SetMarkup()
         returns = "  Returns: ";
         sectionStart = "Section:  ";
         seeAlso = "  See: ";
+        spanWithIdStart = "";
+        spanWithIdMid = "";
+        spanWithIdStop = "";
         subSectionStart = "Subsection ";
         templArgDeduced = "[deduced]  ";
         templArgExplicit = "[explicit] ";
@@ -184,6 +250,9 @@ SetMarkup()
         argument = "\\param ";
         boldStart = "<b>";
         boldStop = "</b>";
+        boldWithIdStart = "<b id=\"";
+        boldWithIdMid = "\">";
+        boldWithIdStop = "</b>";
         breakBoth = "<br>";
         breakHtmlOnly = "<br>";
         breakTextOnly = "";
@@ -201,6 +270,9 @@ SetMarkup()
         functionStop = "";
         headingStart = "<h3>";
         headingStop = "</h3>";
+        headingWithIdStart = "<h3 id=\"";
+        headingWithIdMid = "\">";
+        headingWithIdStop = "</h3>";
         // Linking:  [The link text displayed](\ref TheTarget)
         hrefStart = "[";
         hrefMid = "](\\ref ";
@@ -217,6 +289,9 @@ SetMarkup()
         returns = "\\returns ";
         sectionStart = "\\ingroup ";
         seeAlso = "\\see ";
+        spanWithIdStart = "<span id=\"";
+        spanWithIdMid = "\">";
+        spanWithIdStop = "</span>";
         subSectionStart = "\\addtogroup ";
         templArgDeduced = "\\deduced ";
         templArgExplicit = "\\explicit ";
@@ -717,11 +792,12 @@ PrintConfigPaths(std::ostream& os, const TypeId tid)
     // Config --------------
     if (paths.empty())
     {
-        os << "Introspection did not find any typical Config paths." << breakBoth << std::endl;
+        os << SpanWithId("config-paths", "Introspection did not find any typical Config paths")
+           << breakBoth << std::endl;
     }
     else
     {
-        os << headingStart << "Config Paths" << headingStop << std::endl;
+        os << HeadingWithId("config-paths", "Config Paths") << std::endl;
         os << std::endl;
         os << tid.GetName() << " is accessible through the following paths"
            << " with Config::Set and Config::Connect:" << std::endl;
@@ -862,11 +938,12 @@ PrintAttributes(std::ostream& os, const TypeId tid)
     NS_LOG_FUNCTION(tid);
     if (tid.GetAttributeN() == 0)
     {
-        os << "No Attributes are defined for this type." << breakBoth << std::endl;
+        os << SpanWithId("attributes", "No Attributes are defined for this type") << breakBoth
+           << std::endl;
     }
     else
     {
-        os << headingStart << "Attributes" << headingStop << std::endl;
+        os << HeadingWithId("attributes", "Attributes") << std::endl;
         PrintAttributesTid(os, tid);
     }
 
@@ -935,11 +1012,12 @@ PrintTraceSources(std::ostream& os, const TypeId tid)
     NS_LOG_FUNCTION(tid);
     if (tid.GetTraceSourceN() == 0)
     {
-        os << "No TraceSources are defined for this type." << breakBoth << std::endl;
+        os << SpanWithId("trace-sources", "No TraceSources are defined for this type") << breakBoth
+           << std::endl;
     }
     else
     {
-        os << headingStart << "TraceSources" << headingStop << std::endl;
+        os << HeadingWithId("trace-sources", "TraceSources") << std::endl;
         PrintTraceSourcesTid(os, tid);
     }
 
@@ -972,8 +1050,8 @@ PrintSize(std::ostream& os, const TypeId tid)
 
     std::size_t arch = (sizeof(void*) * CHAR_BIT);
 
-    os << boldStart << "Size" << boldStop << " of this type is " << tid.GetSize() << " bytes (on a "
+    os << BoldWithId("size", "Size") << "of this type is " << tid.GetSize() << " bytes (on a "
-       << arch << "-bit architecture)." << std::endl;
+       << arch << "-bit architecture)." << breakBoth << std::endl;
 } // PrintSize()
 
 /**
@@ -998,9 +1076,13 @@ PrintTypeIdBlock(std::ostream& os, const TypeId tid)
     PrintAttributes(os, tid);
     PrintTraceSources(os, tid);
 
-    if (!tid.GetGroupName().empty())
+    if (tid.GetGroupName().empty())
     {
-        os << boldStart << "Group:" << boldStop << " " << tid.GetGroupName() << "\n" << std::endl;
+        os << SpanWithId("group", name + " does not belong to a group") << breakBoth << std::endl;
+    }
+    else
+    {
+        os << BoldWithId("group", "Group:") << tid.GetGroupName() << breakBoth << std::endl;
     }
 
     PrintSize(os, tid);