Main: Doxygen fixes. bugref:10442

git-svn-id: https://www.virtualbox.org/svn/vbox/trunk@99726 cfe28804-0f27-0410-a406-dd0f0b0b656f

3 files changed, 93 insertions, 10 deletions

diff --git a/src/VBox/Main/Doxyfile.Main b/src/VBox/Main/Doxyfile.Main
index 6547bd6d9e8..a771d8d8c31 100644
--- a/src/VBox/Main/Doxyfile.Main
+++ b/src/VBox/Main/Doxyfile.Main
@@ -2467,3 +2467,5 @@ GENERATE_LEGEND        = YES
 # This tag requires that the tag HAVE_DOT is set to YES.
 
 DOT_CLEANUP            = YES
+
+MARKDOWN_SUPPORT=NO
diff --git a/src/VBox/Main/Makefile.kmk b/src/VBox/Main/Makefile.kmk
index 0f9b1855265..d52ef4f7fc8 100644
--- a/src/VBox/Main/Makefile.kmk
+++ b/src/VBox/Main/Makefile.kmk
@@ -286,15 +286,25 @@ OTHER_CLEAN += $(VBOX_XIDL_FILE) $(VBOX_XIDL_FILE).ts
 VBOX_MAIN_DOC_DIR = $(VBOX_PATH_SDK)/docs
 BLDDIRS += $(VBOX_MAIN_DOC_DIR)
 
+$(PATH_TARGET)/VirtualBox.idl: \
+		$(VBOX_XIDL_FILE_SRC) \
+		$(VBOX_PATH_MAIN_SRC)/idl/doxygen.xsl \
+		| $(PATH_TARGET)/
+	$(call MSG_TOOL,xsltproc,,$<,$@)
+	$(QUIET)$(VBOX_XSLTPROC) --path ".:$(PATH_ROOT)/doc/manual" \
+		-o "$@.tmp" $(VBOX_PATH_MAIN_SRC)/idl/doxygen.xsl $(VBOX_XIDL_FILE_SRC)
+	$(QUIET)$(SED) \
+		-e 's,@SLASH-ASTERISK@,<b></b>*,g' \
+		-e 's,@ASTERISK-SLASH@,*<b></b>,g' \
+		--output "$@" "$@.tmp"
+
 $(PATH_TARGET)/docs.Main: \
 		$(VBOX_PATH_MAIN_SRC)/Doxyfile.Main \
-		$(VBOX_PATH_MAIN_SRC)/idl/doxygen.xsl \
+		$(PATH_TARGET)/VirtualBox.idl \
 		$(VBOX_XIDL_FILE_SRC) \
-		| $(PATH_TARGET)/ \
-		$(VBOX_MAIN_DOC_DIR)/
-	$(call MSG_TOOL,xsltproc,doxygen input,$<,$@)
-	$(QUIET)$(RM) -f $(wildcard $(VBOX_MAIN_DOC_DIR)/html/*) $(PATH_TARGET)/docs.Main
-	$(QUIET)$(VBOX_XSLTPROC) --path ".:$(PATH_ROOT)/doc/manual" -o $(PATH_TARGET)/VirtualBox.idl $(VBOX_PATH_MAIN_SRC)/idl/doxygen.xsl $(VBOX_XIDL_FILE_SRC)
+		| $(VBOX_MAIN_DOC_DIR)/
+	$(call MSG_TOOL,doxygen,,$<,$@)
+	$(QUIET)$(RM) -f -- $(wildcard $(VBOX_MAIN_DOC_DIR)/html/*) $(PATH_TARGET)/docs.Main
 	$(QUIET)$(REDIRECT) -E 'DOCDIR=$(VBOX_MAIN_DOC_DIR)' -E 'PATH_TARGET=$(PATH_TARGET)' \
 		-- $(VBOX_DOXYGEN) $(VBOX_PATH_MAIN_SRC)/Doxyfile.Main
 	$(QUIET)$(TEST) -s "$(PATH_TARGET)/Main.err" -- $(ECHO_EXT) ">>>>>>>>>>>>>>>>>>>> Main.err: >>>>>>>>>>>>>>>>>>>>>>>>"
diff --git a/src/VBox/Main/idl/doxygen.xsl b/src/VBox/Main/idl/doxygen.xsl
index 4f96e9216f3..50d05169eff 100644
--- a/src/VBox/Main/idl/doxygen.xsl
+++ b/src/VBox/Main/idl/doxygen.xsl
@@ -39,7 +39,9 @@
 
 <xsl:import href="string.xsl"/>
 
-<xsl:output method="html" indent="yes"/>
+<!-- Don't indent the output, as it's not exactly html but IDL.
+     (doxygen 1.9.6 gets confused by <dl> indent.) -->
+<xsl:output method="html" indent="no"/>
 
 <xsl:strip-space elements="*"/>
 
@@ -58,6 +60,73 @@
 </xsl:template-->
 
 <!--
+  Replace /* and */ sequences in the text so they won't confuse doxygen with
+  comment nesting (see IPerformanceCollector).  Doxygen doesn't have any escape
+  sequence for '/' nor for '*', and xsltproc is in html mode so we cannot easily
+  output dummy elements.  So, we replace the '*' with '@SLASH-ASTERISK@' and
+  '@ASTERISK-SLASH@' and run sed afterwards to change them to sequences with
+  a dummy 'b' element in-between the characters (&#42; does not work).
+
+  TODO: Find better fix for this.
+
+  ~~Also, strip leading whitespace from the first child of a 'desc' element so
+  that doxygen 1.9.6 doesn't confuse the text for a tt or pre block (older
+  versions (1.8.13) didn't used to do this).~~ - fixed by MARKDOWN_SUPPORT=NO.
+  -->
+<xsl:template match="desc//text()" name="default-text-processing">
+  <xsl:param name="text" select="."/>
+
+  <!-- xsl:variable name="stripped">
+    <xsl:choose>
+      <xsl:when test="parent::desc and position() = 1">
+        <xsl:call-template name="strip-left">
+          <xsl:with-param name="text" select="$text"/>
+        </xsl:call-template>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:value-of select="$text"/>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:variable -->
+
+  <xsl:variable name="subst1">
+    <xsl:call-template name="str:subst">
+      <!-- xsl:with-param name="text" select="$stripped" / -->
+      <xsl:with-param name="text" select="$text" />
+      <xsl:with-param name="replace" select="'/*'" />
+      <xsl:with-param name="with" select="'/@SLASH-ASTERISK@'"/>
+    </xsl:call-template>
+  </xsl:variable>
+  <xsl:variable name="subst2">
+    <xsl:call-template name="str:subst">
+      <xsl:with-param name="text" select="$subst1" />
+      <xsl:with-param name="replace" select="'*/'" />
+      <xsl:with-param name="with" select="'@ASTERISK-SLASH@/'" />
+    </xsl:call-template>
+  </xsl:variable>
+
+  <!-- xsl:value-of select="concat('-dbg-',position(),'-gbd-')"/ -->
+  <xsl:value-of select="$subst2"/>
+</xsl:template>
+
+<!-- Strips leading spaces from $text.  Helper for default-text-processing.  -->
+<xsl:template name="strip-left">
+  <xsl:param name="text"/>
+  <xsl:choose>
+    <xsl:when test="string-length($text) > 0 and (substring($text, 1, 1) = ' ' or substring($text, 1, 1) = '&#x0A;' or substring($text, 1, 1) = '&#x0D;')">
+      <xsl:call-template name="strip-left">
+        <xsl:with-param name="text" select="substring($text, 2)"/>
+      </xsl:call-template>
+    </xsl:when>
+
+    <xsl:otherwise>
+      <xsl:value-of select="$text"/>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
+
+<!--
  *  all elements that are not explicitly matched are considered to be html tags
  *  and copied w/o modifications
 -->
@@ -79,7 +148,9 @@
       <xsl:with-param name="with" select="'\::'" />
     </xsl:call-template>
   </xsl:variable>
-  <xsl:value-of select="$subst1"/>
+  <xsl:call-template name="default-text-processing">
+    <xsl:with-param name="text" select="$subst1"/>
+  </xsl:call-template>
 </xsl:template>
 
 <!--
@@ -219,7 +290,7 @@
   <xsl:if test="$id">
     <xsl:value-of select="concat(' @ingroup ',$id,'&#x0A;')"/>
   </xsl:if>
-  <xsl:text> @brief&#x0A;</xsl:text>
+  <xsl:text> @brief </xsl:text>
 </xsl:template>
 
 <!--
@@ -400,7 +471,7 @@ owns the object will most likely fail or crash your application.
   <!-- group (module) definitions -->
   <xsl:for-each select="//descGroup">
     <xsl:if test="@id and (@title or desc)">
-      <xsl:value-of select="concat('/** @defgroup ',@id,' ',@title)"/>
+      <xsl:value-of select="concat('/** @defgroup ', @id, ' ', @title, '&#x0A;')"/>
       <xsl:apply-templates select="desc" mode="middle"/>
       <xsl:text>&#x0A;*/&#x0A;</xsl:text>
     </xsl:if>