[PATCH] drm/tinydrm: Fix doc build warnings

[Noralf Trønnes]

Den 10.07.2018 18.40, skrev David Lechner:
> On 07/10/2018 11:31 AM, Noralf Trønnes wrote:
>>
>> Den 10.07.2018 18.18, skrev David Lechner:
>>> On 07/10/2018 10:05 AM, Noralf Trønnes wrote:
>>>> include/drm/tinydrm/tinydrm.h:34: warning: Function parameter or 
>>>> member 'fb_dirty' not described in 'tinydrm_device'
>>>> drivers/gpu/drm/tinydrm/mipi-dbi.c:272: warning: Function parameter 
>>>> or member 'crtc_state' not described in 'mipi_dbi_enable_flush'
>>>> drivers/gpu/drm/tinydrm/mipi-dbi.c:272: warning: Function parameter 
>>>> or member 'plane_state' not described in 'mipi_dbi_enable_flush'
>>>>
>>>> Move struct member docs inline so it's not missed next time.
>>>>
>>>> Cc: David Lechner <david at lechnology.com>
>>>> Signed-off-by: Noralf Trønnes <noralf at tronnes.org>
>>>> ---
>>>>   drivers/gpu/drm/tinydrm/mipi-dbi.c |  2 ++
>>>>   include/drm/tinydrm/tinydrm.h      | 23 +++++++++++++++++++----
>>>>   2 files changed, 21 insertions(+), 4 deletions(-)
>>>>
>>>> diff --git a/drivers/gpu/drm/tinydrm/mipi-dbi.c 
>>>> b/drivers/gpu/drm/tinydrm/mipi-dbi.c
>>>> index 4d1fb31a781f..cb3441e51d5f 100644
>>>> --- a/drivers/gpu/drm/tinydrm/mipi-dbi.c
>>>> +++ b/drivers/gpu/drm/tinydrm/mipi-dbi.c
>>>> @@ -260,6 +260,8 @@ static const struct drm_framebuffer_funcs 
>>>> mipi_dbi_fb_funcs = {
>>>>   /**
>>>>    * mipi_dbi_enable_flush - MIPI DBI enable helper
>>>>    * @mipi: MIPI DBI structure
>>>> + * @crtc_state: CRTC state
>>>> + * @plane_state: Plane state
>>>>    *
>>>>    * This function sets &mipi_dbi->enabled, flushes the whole 
>>>> framebuffer and
>>>>    * enables the backlight. Drivers can use this in their
>>>> diff --git a/include/drm/tinydrm/tinydrm.h 
>>>> b/include/drm/tinydrm/tinydrm.h
>>>> index 56e4a916b5e8..fe9827d0ca8a 100644
>>>> --- a/include/drm/tinydrm/tinydrm.h
>>>> +++ b/include/drm/tinydrm/tinydrm.h
>>>> @@ -16,16 +16,31 @@
>>>>     /**
>>>>    * struct tinydrm_device - tinydrm device
>>>> - * @drm: DRM device
>>>> - * @pipe: Display pipe structure
>>>> - * @dirty_lock: Serializes framebuffer flushing
>>>> - * @fb_funcs: Framebuffer functions used when creating framebuffers
>>>>    */
>>>>   struct tinydrm_device {
>>>> +    /**
>>>> +     * @drm: DRM device
>>>> +     */
>>>>       struct drm_device *drm;
>>>> +
>>>> +    /**
>>>> +     * @pipe: Display pipe structure
>>>> +     */
>>>>       struct drm_simple_display_pipe pipe;
>>>> +
>>>> +    /**
>>>> +     * @dirty_lock: Serializes framebuffer flushing
>>>> +     */
>>>>       struct mutex dirty_lock;
>>>> +
>>>> +    /**
>>>> +     * @fb_funcs: Framebuffer functions used when creating 
>>>> framebuffers
>>>> +     */
>>>>       const struct drm_framebuffer_funcs *fb_funcs;
>>>> +
>>>> +    /**
>>>> +     * @fb_dirty: Framebuffer dirty callback
>>>> +     */
>>>>       int (*fb_dirty)(struct drm_framebuffer *framebuffer,
>>>>               struct drm_file *file_priv, unsigned flags,
>>>>               unsigned color, struct drm_clip_rect *clips,
>>>>
>>>
>>> I assume the kerneldoc parser know how to handle this?
>>>
>>
>> This? What are you referring to?
>>
>> This is how I build the documentation: make DOCBOOKS="" htmldocs
>>
>> Noralf.
>>
>
> I haven't seen struct fields with doc comments on each individual
> field before. What I meant to say is that I'm assuming that when
> you build the htmldocs that it picks up this documentation for each
> field the same as if they were documented in the doc comment for
> the struct itself. In other words, the resulting documentation
> looks the same either way?
>

Yes it does.
https://www.kernel.org/doc/html/v4.17/doc-guide/kernel-doc.html#in-line-member-documentation-comments