Em Wed, 31 Aug 2016 12:09:39 +0200 Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu: > 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. It is not uncommon to "promote" some such macros to inline functions, in order to have a stronger type check, or to do the reverse, when we need a more generic declaration that would work for multiple types. So, keeping both macro function-like functions and functions using the :c:function: seems to be the best, IMHO. It also makes life easier for kernel-doc script. > > -- 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 > Thanks, Mauro -- 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
