diff options
| author | Ben Kaduk <kaduk@mit.edu> | 2012-11-16 19:48:55 -0500 |
|---|---|---|
| committer | Ben Kaduk <kaduk@mit.edu> | 2012-11-27 17:55:03 -0500 |
| commit | 94947241bd347e9b4dd729c5d550150b7e8cd64c (patch) | |
| tree | 2442b97c8fdf42ba1371b72798ceaeecfe4597b2 | |
| parent | 760155906bc47163bac1fb5622034a9d53e15294 (diff) | |
| download | krb5-94947241bd347e9b4dd729c5d550150b7e8cd64c.tar.gz krb5-94947241bd347e9b4dd729c5d550150b7e8cd64c.tar.xz krb5-94947241bd347e9b4dd729c5d550150b7e8cd64c.zip | |
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
| -rw-r--r-- | doc/tools/define_document.tmpl | 12 | ||||
| -rw-r--r-- | 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 8bf2fd393..ca56d866c 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 ea1510340..10eab1b56 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')) |