Render macros as literals

Some convenience macros are referring to and dereferencing pointers,
and Sphinx will get a bit confused trying to interpret this as markup.
There should never be any markup intended to be interpreted in the
value of a macro definition, so we can silence this class of
warnings by treating them as literals.  (In some sense, they actually
are literals, too.)

This will cause a warning for macros that only cause a
symbol to be defined, that is, a literal "#define MACRO" with no
initializer, due to the lack of body in the inline-literal markup.
Such macros should probably be added to the exclude list for conversion
to reStructuredText in the Doxygen-Sphinx bridge, as was already
done for KRB5_OLD_CRYPTO.  Support code to programmatically omit
macros of this sort is deliberately *not* included, so that explicit
action must be taken when a new macro is to be undocumented.

Also, strip leading and trailing whitespace from the macro name,
since this causes problems with the markup.

ticket: 7447
tags: pullup
target_version: 1.11

diff --git a/doc/tools/define_document.tmpl b/doc/tools/define_document.tmpl
index 8bf2fd393a9e5db18d035d964f3c0d49aa4ecf2f..ca56d866cec1c437e3b5262067b49958e4a33912 100644 (file)
--- a/doc/tools/define_document.tmpl
+++ b/doc/tools/define_document.tmpl
@@ -17,11 +17,11 @@ $composite.short_description
 $composite.long_description
 
 #if $composite.name_signature is not None and len($composite.name_signature)
-#echo ''.join(['=']*len($composite.name_signature)) + '== ======================' #
-$composite.name_signature       $composite.initializer
-#echo ''.join(['=']*len($composite.name_signature)) + '== ======================' #
+#echo ''.join(['=']*(len($composite.name_signature)+4)) + '== ======================' #
+``$composite.name_signature``       ``$composite.initializer``
+#echo ''.join(['=']*(len($composite.name_signature)+4)) + '== ======================' #
 #else
-#echo ''.join(['=']*len($composite.name)) + '=== ======================' #
-$composite.name       $composite.initializer
-#echo ''.join(['=']*len($composite.name)) + '=== ======================' #
+#echo ''.join(['=']*(len($composite.name)+4)) + '=== ======================' #
+``$composite.name``       ``$composite.initializer``
+#echo ''.join(['=']*(len($composite.name)+4)) + '=== ======================' #
 #end if

diff --git a/doc/tools/doxybuilder_types.py b/doc/tools/doxybuilder_types.py
index ea151034099ab9ebde1e6bed6e511252e849938e..10eab1b5658c278d45f61f17aa9c1f34c688cbde 100644 (file)
--- a/doc/tools/doxybuilder_types.py
+++ b/doc/tools/doxybuilder_types.py
@@ -195,7 +195,7 @@ class DoxyTypes(object):
             if prm_list is not None:
                 prm_str = prm_str.join(prm_list)
             d_signature = " %s (%s) " % (d_name , prm_str)
-            d_signature = re.sub(', \)', ')', d_signature)
+            d_signature = re.sub(', \)', ')', d_signature).strip()
 
         if len(node.xpath('./initializer')) > 0:
             len_ref = len(node.xpath('./initializer/ref'))