[PATCH] drm/tinydrm: Fix doc build warnings

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