krb5 commit: Render macros as literals

[Benjamin Kaduk]

https://github.com/krb5/krb5/commit/94947241bd347e9b4dd729c5d550150b7e8cd64c
commit 94947241bd347e9b4dd729c5d550150b7e8cd64c
Author: Ben Kaduk <kaduk at mit.edu>
Date:   Fri Nov 16 19:48:55 2012 -0500

    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

 doc/tools/define_document.tmpl |   12 ++++++------
 doc/tools/doxybuilder_types.py |    2 +-
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/doc/tools/define_document.tmpl b/doc/tools/define_document.tmpl
index 8bf2fd3..ca56d86 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 ea15103..10eab1b 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'))