Re: [RFC] kernel-doc: allow object-like macros in ReST output

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

 




On 10/14/24 6:40 AM, Randy Dunlap wrote:
> Hi,
> 
> On 10/13/24 11:45 PM, Vlastimil Babka wrote:
>> On 10/14/24 07:13, Randy Dunlap wrote:
>>> output_function_rst() does not handle object-like macros. It presents
>>> a trailing "()" while output_function_man() handles these macros
>>> correctly.
>>
>> Thanks!
>>
>>> Update output_function_rst() to handle object-like macros.
>>> Don't show the "Parameters" heading if there are no parameters.
>>>
>>> For output_function_man(), do show the "ARGUMENTS" heading if there
>>> are no parameters.
>>>
>>> I have tested this quite a bit with my ad hoc test files for both ReST
>>> and man format outputs. The generated output looks good.
>>>
>>> However, I am seeing one problem that I don't have any idea about and
>>> would appreciate some assistance, even just email commentary about it.
>>> The output now includes around 100 warnings like these examples:
>>>
>>> Documentation/core-api/mm-api:37: ../include/linux/slab.h:154: WARNING: Inline literal start-string without end-string. [docutils]
>>> Documentation/core-api/mm-api:37: ../include/linux/slab.h:192: WARNING: Inline literal start-string without end-string. [docutils]
>>
>> To clarify, I assume this part only happens with my patch that motivated this?
>> https://lore.kernel.org/all/20241009142936.56092-2-vbabka@xxxxxxx/
> 
> Sorry, I  didn't mean to imply that your patch causes this.
> To be sure, I am rerunning the docs build with only my patch now.

Yes, with just my patch this problem is still present but I will now
test Jon's patch.
> 
>> Also can you clarify whether these docs should look like:
>>
>>   /**
>>    * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \
>>
>> per Documentation/doc-guide/kernel-doc.rst
>>
>> or
>>
>> /**
>>  * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - Initializes struct drm_plane_helper_funcs
>>  *                                   for VRAM handling
>>
>> as it is in the actual file include/drm/drm_gem_vram_helper.h
>> i.e. if that "define" keyword is needed, or it doesn't matter?
> 
> OK, I'll check that also.
>

still pending.


-- 
~Randy




[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