[PATCH] drm/tinydrm: Fix doc build warnings

[PATCH] drm/tinydrm: Fix doc build warnings

[Noralf Trønnes]

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@lechnology.com>
Signed-off-by: Noralf Trønnes <noralf@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,
-- 
2.15.1

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH] drm/tinydrm: Fix doc build warnings

[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@lechnology.com>
> Signed-off-by: Noralf Trønnes <noralf@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?

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH] drm/tinydrm: Fix doc build warnings

[Noralf Trønnes]

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@lechnology.com>
>> Signed-off-by: Noralf Trønnes <noralf@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.

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [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@lechnology.com>
>>> Signed-off-by: Noralf Trønnes <noralf@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?

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [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@lechnology.com>
>>>> Signed-off-by: Noralf Trønnes <noralf@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

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH] drm/tinydrm: Fix doc build warnings

[David Lechner]

On 07/10/2018 12:09 PM, Noralf Trønnes wrote:
> 
> 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@lechnology.com>
>>>>> Signed-off-by: Noralf Trønnes <noralf@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
> 

Nifty.

Reviewed-by: David Lechner <david@lechnology.com>

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH] drm/tinydrm: Fix doc build warnings

[Daniel Vetter]

On Tue, Jul 10, 2018 at 06:31:15PM +0200, 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@lechnology.com>
> > > Signed-off-by: Noralf Trønnes <noralf@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

Fyi DOCBOOKS="" no longer needed since all the old docbook stuff is gone.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH] drm/tinydrm: Fix doc build warnings

[Noralf Trønnes]

Den 10.07.2018 17.05, skrev Noralf Trønnes:
> 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@lechnology.com>
> Signed-off-by: Noralf Trønnes <noralf@tronnes.org>
> ---

Applied, thanks for reviewing.

Noralf.

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

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel