Skip to contentSkip to conversation

documentation: key header files: fix member variable description warnings

PATCH In review Alissa Guo 3 participants 4 messages Jul 31, 2024 – Aug 1, 2024

Subsystems (3)
lore
Share & tools
lore

Alissa Guo

author
#0 lore raw

PATCH 1/1 documentation: key header files: fix member variable description warnings

---
 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(-)
include/drm/display/drm_dp_helper.h +1 -0
index ea03e1dd26ba..7f2567fa230d 100644
@@ -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 {
include/linux/jbd2.h +1 -1
index 5157d92b6f23..17662eae408f 100644
@@ -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
 	 */
include/uapi/drm/drm_mode.h +6 -0
index d390011b89b4..c61b72bc04a6 100644
@@ -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;
 };
 
Signature · 1 line
2.43.0
author
#2 lore raw

PATCH 1/1 documentation: key header files: fix member variable description warnings

In reply to Alissa Guo

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

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

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'

---
 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(-)
include/drm/display/drm_dp_helper.h +1 -0
index ea03e1dd26ba..7f2567fa230d 100644
@@ -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 {
include/linux/jbd2.h +1 -1
index 5157d92b6f23..17662eae408f 100644
@@ -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
 	 */
include/uapi/drm/drm_mode.h +6 -0
index d390011b89b4..c61b72bc04a6 100644
@@ -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;
 };
 
Signature · 1 line
2.43.0
#3 lore raw
Quoted 3 lines · Alissa Guo

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

Quoted 5 lines

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.

Quoted 50 lines

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'

---
  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(-)
include/drm/display/drm_dp_helper.h +1 -0
index ea03e1dd26ba..7f2567fa230d 100644
@@ -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 {
include/linux/jbd2.h +1 -1
index 5157d92b6f23..17662eae408f 100644
@@ -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
  	 */
include/uapi/drm/drm_mode.h +0 -0
index d390011b89b4..c61b72bc04a6 100644
@@ -864,7 +864,13 @@ struct drm_color_lut {
   * array of struct drm_plane_size_hint.
   */
  struct drm_plane_size_hint {

include/uapi/drm/drm_mode.h struct drm_color_lut { · line 876

Quoted 10 lines
include/uapi/drm/drm_mode.h +6 -0
+	/**
+	 * @width: Desired horizontal size of the plane in pixels
+	 */
  	__u16 width;
+	/**
+	 * @height: Desired vertical size of the plane in pixels
+	 */
  	__u16 height;
  };
 

thanks,
-- Shuah