Re: [PATCH v3] docs-rst: ignore arguments on macro definitions

[Jani Nikula <jani.nikula@linux.intel.com>]

On Wed, 31 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> I haven't tested your suggestion, but since *void* is in the list
> of stop-words:
>
>     # These C types aren't described anywhere, so don't try to create
>     # a cross-reference to them
>     stopwords = set((
>         'const', 'void', 'char', 'wchar_t', 'int', 'short',
>         'long', 'float', 'double', 'unsigned', 'signed', 'FILE',
>         'clock_t', 'time_t', 'ptrdiff_t', 'size_t', 'ssize_t',
>         'struct', '_Bool',
>     ))
>
> I think it will work in the matter you think. 
>
> However I like to prefer to fix it in the C-domain, using
> Mauro's suggestion on argument parsing. IMHO it is not
> the best solution to add a void type to the reST signature
> of a macro. This will result in a unusual output and does
> not fix what is wrong in Sphinx's c-domain (there is also
> a drawback in the index, where a function-type macro is
> referred as function, not as macro).

>From an API user's perspective, functions and function-like macros
should work interchangeably. Personally, I don't think there needs to be
a difference in the index. This seems to be the approach taken in
Sphinx, but it just doesn't work well for automatic documentation
generation because we can't deduce the parameter types from the macro
definition.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center