From: Ben Kaduk <kaduk@mit.edu>
Date: Sat, 17 Nov 2012 00:48:55 +0000 (-0500)
Subject: Render macros as literals
X-Git-Tag: krb5-1.12-alpha1~453
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=94947241bd347e9b4dd729c5d550150b7e8cd64c;p=thirdparty%2Fkrb5.git

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 8bf2fd393a..ca56d866ce 100644
--- 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 ea15103409..10eab1b565 100644
--- 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'))