Am 31.08.2016 um 11:02 schrieb Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx>: > On Wed, 31 Aug 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> 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. Ah, OK. > 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. In the index, sphinx refers only object-like macros with an entry "FOO (C macro))". Function-like macros are referred as "BAR (C function)". I thought it is more straight forward to refer all macros with a "BAR (C macro)" entry in the index. I will split this change in a separate patch, so we can decide if we like to patch the index that way. But now, as we discuss this, I have another doubt to fix the index. It might be confusing when writing references to those macros. Since function-like macros internally are functions in the c-domain, they are referred with ":c:func:`BAR`". On the other side, object-like macros are referred by role ":c:macro:`FOO`". Taking this into account, it might be one reason more to follow your conclusion that functions and function-like macros are interchangeable from the user's perspective. -- Markus -- > > BR, > Jani. > > > -- > Jani Nikula, Intel Open Source Technology Center > -- > To unsubscribe from this list: send the line "unsubscribe linux-doc" in > the body of a message to majordomo@xxxxxxxxxxxxxxx > More majordomo info at http://vger.kernel.org/majordomo-info.html -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
