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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Am 31.08.2016 um 12:26 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>:

> 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.


May, I was unclear. I don't want to change the behavior: """keeping both
macro function-like functions and functions using the :c:function:""". 

The only thing I thought to change is, how the index entry will be. 
First I thought it might be more straight forward to refer func-like 
as "BAR (C macro)". But after Jani's conclusion, I had a doubt if
this is really a better entry in the index, than that what sphinx
already does "BAR (C function)".

Sorry for the confusion.

-- Markus --



--
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



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux