Re: [PATCH] documentation: key header files: fix member variable description warnings

[Shuah Khan <skhan@linuxfoundation.org>]

On 7/31/24 18:51, Alissa Guo wrote:
> Fix the following documentation compilation warnings from missing member variable descriptions when 'make htmldocs' is called:
> 
> Fixed misspelling of @j_transaction_overhead to @j_transaction_overhead_buffers in ./include/linux/jbd2.h:1303

Fix

> 
> Add description of 'target_rr_divider' in  ./include/drm/display/drm_dp_helper.h
> 
> Add description of 'width' and 'height' in struct 'drm_plane_size_hint' in ./include/uapi/drm/drm_mode.h
> 

Lines should be wrapped at 75 columns

Refer to Documentation/process/submitting-patches.rst

Didn't you send this patch and got review feedback? You
are supposed to send v2 - Fix these problems and send
v2.


> Effects:
> 
> The following warnings should no longer arise upon 'make htmldocs'
> 
> ./include/linux/jbd2.h:1303: warning: Function parameter or struct member 'j_transaction_overhead_buffers' not described in 'journal_s'
> ./include/linux/jbd2.h:1303: warning: Excess struct member 'j_transaction_overhead' description in 'journal_s'
> ./include/drm/display/drm_dp_helper.h:127: warning: Function parameter or struct member 'target_rr_divider' not described in 'drm_dp_as_sdp'
> ./include/uapi/drm/drm_mode.h:869: warning: Function parameter or struct member 'width' not described in 'drm_plane_size_hint'
> ./include/uapi/drm/drm_mode.h:869: warning: Function parameter or struct member 'height' not described in 'drm_plane_size_hint'
> 
> Signed-off-by: Alissa Guo <guoalissa@gmail.com>
> ---
>   include/drm/display/drm_dp_helper.h | 1 +
>   include/linux/jbd2.h                | 2 +-
>   include/uapi/drm/drm_mode.h         | 6 ++++++
>   3 files changed, 8 insertions(+), 1 deletion(-)
> 
> diff --git a/include/drm/display/drm_dp_helper.h b/include/drm/display/drm_dp_helper.h
> index ea03e1dd26ba..7f2567fa230d 100644
> --- a/include/drm/display/drm_dp_helper.h
> +++ b/include/drm/display/drm_dp_helper.h
> @@ -112,6 +112,7 @@ struct drm_dp_vsc_sdp {
>    * @target_rr: Target Refresh
>    * @duration_incr_ms: Successive frame duration increase
>    * @duration_decr_ms: Successive frame duration decrease
> + * @target_rr_divider: Target refresh rate divider
>    * @mode: Adaptive Sync Operation Mode
>    */
>   struct drm_dp_as_sdp {
> diff --git a/include/linux/jbd2.h b/include/linux/jbd2.h
> index 5157d92b6f23..17662eae408f 100644
> --- a/include/linux/jbd2.h
> +++ b/include/linux/jbd2.h
> @@ -1086,7 +1086,7 @@ struct journal_s
>   	int			j_revoke_records_per_block;
>   
>   	/**
> -	 * @j_transaction_overhead:
> +	 * @j_transaction_overhead_buffers:
>   	 *
>   	 * Number of blocks each transaction needs for its own bookkeeping
>   	 */
> diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
> index d390011b89b4..c61b72bc04a6 100644
> --- a/include/uapi/drm/drm_mode.h
> +++ b/include/uapi/drm/drm_mode.h
> @@ -864,7 +864,13 @@ struct drm_color_lut {
>    * array of struct drm_plane_size_hint.
>    */
>   struct drm_plane_size_hint {
> +	/**
> +	 * @width: Desired horizontal size of the plane in pixels
> +	 */
>   	__u16 width;
> +	/**
> +	 * @height: Desired vertical size of the plane in pixels
> +	 */
>   	__u16 height;
>   };
>   

thanks,
-- Shuah