Changeset 92153 in vbox

Timestamp:

Oct 29, 2021 4:41:20 PM (3 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

147974

Message:

Main/doxygen: Remove the attempt to produce a .chm file with the doxygen generated API documentation. HTML is good enough. In doxygen.xsl handle input in <tt> specially, which currently means quoting :: to avoid annoying error messages from doxygen. Additionally switch to the string processing templates from doc/manual/string.xsl, phasing out the home grown ones (too much work to write another string replace template, and too inconsistent to keep using the self-written uppercasing). Finally no more doxygen complaint about the MAC address example in the API documentation.

Location:

trunk/src/VBox/Main

Files:

• Doxyfile.Main (modified) (2 diffs)
• Makefile.kmk (modified) (2 diffs)
• idl/VirtualBox.xidl (modified) (1 diff)
• idl/doxygen.xsl (modified) (4 diffs)

trunk/src/VBox/Main/Doxyfile.Main

@@ -1270 +1270 @@
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-GENERATE_HTMLHELP      = YES
+GENERATE_HTMLHELP      = NO
 
 # The CHM_FILE tag can be used to specify the file name of the resulting .chm
@@ -1277 +1277 @@
 # This tag requires that the tag GENERATE_HTMLHELP is set to YES.
 
-CHM_FILE               = $(PATH_CHM)
+CHM_FILE               =
 
 # The HHC_LOCATION tag can be used to specify the location (absolute path

trunk/src/VBox/Main/Makefile.kmk

@@ -267 +267 @@
         $(call MSG_TOOL,xsltproc,doxygen input,$<,$@)
         $(QUIET)$(RM) -f $(wildcard $(VBOX_MAIN_DOC_DIR)/html/*) $(PATH_TARGET)/docs.Main
-        $(QUIET)$(VBOX_XSLTPROC) -o $(PATH_TARGET)/VirtualBox.idl $(VBOX_PATH_MAIN_SRC)/idl/doxygen.xsl $(VBOX_XIDL_FILE_SRC)
-        $(QUIET)$(REDIRECT) -E 'DOCDIR=$(VBOX_MAIN_DOC_DIR)' -E 'PATH_TARGET=$(PATH_TARGET)' -E 'PATH_CHM=$(subst /,\,$(VBOX_MAIN_DOC_DIR)/VirtualBoxAPI.chm)' \
+        $(QUIET)$(VBOX_XSLTPROC) --path ".:$(PATH_ROOT)/doc/manual" -o $(PATH_TARGET)/VirtualBox.idl $(VBOX_PATH_MAIN_SRC)/idl/doxygen.xsl $(VBOX_XIDL_FILE_SRC)
+        $(QUIET)$(REDIRECT) -E 'DOCDIR=$(VBOX_MAIN_DOC_DIR)' -E 'PATH_TARGET=$(PATH_TARGET)' \
                 -- doxygen $(VBOX_PATH_MAIN_SRC)/Doxyfile.Main
         $(QUIET)$(TEST) -s "$(PATH_TARGET)/Main.err" -- $(ECHO_EXT) ">>>>>>>>>>>>>>>>>>>> Main.err: >>>>>>>>>>>>>>>>>>>>>>>>"
@@ -277 +277 @@
         $(QUIET)$(TEST) -s "$(PATH_TARGET)/Main.err" -- $(ECHO_EXT) "===> $(PATH_TARGET)/Main.err"
         $(QUIET)$(TEST) -s "$(PATH_TARGET)/Main.err" -- $(ECHO_EXT) "===> **************************************************"
-        -$(EXEC_X86_WIN32) $(VBOX_PATH_HTML_HELP_WORKSHOP)/hhc.exe $(subst /,\\,$(VBOX_MAIN_DOC_DIR)/html/index.hhp)
         $(APPEND) $(PATH_TARGET)/docs.Main
 # aliases

trunk/src/VBox/Main/idl/VirtualBox.xidl

@@ -2154 +2154 @@
     </const>
     <const name="Hex"                    value="1">
-      <desc>Value format is a series of hex bytes (09314f3200fe), optionally colons
-        as byte separators (9:31:4f:32::fe).</desc>
+      <desc>Value format is a series of hex bytes (<tt>09314f3200fe</tt>),
+        optionally colons as byte separators (<tt>9:31:4f:32::fe</tt>).</desc>
     </const>
   </enum>

trunk/src/VBox/Main/idl/doxygen.xsl

@@ -17 +17 @@
 -->
 
-<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+<xsl:stylesheet
+  version="1.0"
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+  xmlns:str="http://xsltsl.org/string"
+  exclude-result-prefixes="str"
+>
+<!-- The exclude-result-prefixes attribute is needed since otherwise the <tt>
+  tag added for the ID in interface and enum descriptions would get the
+  namespace, confusing doxygen completely. -->
+
+<xsl:import href="string.xsl"/>
+
 <xsl:output method="html" indent="yes"/>
 
 <xsl:strip-space elements="*"/>
-
-<xsl:include href="typemap-shared.inc.xsl" />
 
 
@@ -46 +55 @@
     <xsl:apply-templates/>
   </xsl:copy>
+</xsl:template>
+
+<!--
+ * special treatment of <tt>, making sure that Doxygen will not interpret its
+ * contents (assuming it is a leaf tag)
+-->
+<xsl:template match="desc//tt/text()">
+  <xsl:variable name="subst1">
+    <xsl:call-template name="str:subst">
+      <xsl:with-param name="text" select="." />
+      <xsl:with-param name="replace" select="'::'" />
+      <xsl:with-param name="with" select="'\::'" />
+    </xsl:call-template>
+  </xsl:variable>
+  <xsl:value-of select="$subst1"/>
 </xsl:template>
 
@@ -235 +259 @@
   <xsl:apply-templates select="." mode="middle"/>
 @par Interface ID:
-<tt>{<xsl:call-template name="string-to-upper">
-    <xsl:with-param name="str" select="../@uuid"/>
+<tt>{<xsl:call-template name="str:to-upper">
+    <xsl:with-param name="text" select="../@uuid"/>
   </xsl:call-template>}</tt>
   <xsl:text>&#x0A;*/&#x0A;</xsl:text>
@@ -303 +327 @@
   <xsl:apply-templates select="." mode="middle"/>
 @par Interface ID:
-<tt>{<xsl:call-template name="string-to-upper">
-    <xsl:with-param name="str" select="../@uuid"/>
+<tt>{<xsl:call-template name="str:to-upper">
+    <xsl:with-param name="text" select="../@uuid"/>
   </xsl:call-template>}</tt>
   <xsl:text>&#x0A;*/&#x0A;</xsl:text>