HID: core: Improve the kerneldoc for hid_report_len()

AlanStern · Benjamin Tissoires · commit 12f33ef6c2aa · 2025-07-15T17:28:27.000+02:00
The kerneldoc for hid_report_len() needs to be improved. The description of the @report argument is ungrammatical, and the documentation does not explain under what circumstances the report length will include the byte reserved for the report ID. Let's fix up the kerneldoc. Signed-off-by: Alan Stern <stern@rowland.harvard.edu> Link: https://patch.msgid.link/1c8416cb-7347-4a06-b00a-20518069d263@rowland.harvard.edu Signed-off-by: Benjamin Tissoires <bentiss@kernel.org>
diff --git a/include/linux/hid.h b/include/linux/hid.h
@@ -1216,7 +1216,11 @@ static inline void hid_hw_wait(struct hid_device *hdev)
 /**
  * hid_report_len - calculate the report length
  *
- * @report: the report we want to know the length
+ * @report: the report whose length we want to know
+ *
+ * The length counts the report ID byte, but only if the ID is nonzero
+ * and therefore is included in the report.  Reports whose ID is zero
+ * never include an ID byte.
  */
 static inline u32 hid_report_len(struct hid_report *report)
 {

Original file line number	Diff line number	Diff line change
`@@ -1216,7 +1216,11 @@ static inline void hid_hw_wait(struct hid_device *hdev)`
`1216`	`1216`	`/**`
`1217`	`1217`	`* hid_report_len - calculate the report length`
`1218`	`1218`	`*`
`1219`		`- * @report: the report we want to know the length`
	`1219`	`+ * @report: the report whose length we want to know`
	`1220`	`+ *`
	`1221`	`+ * The length counts the report ID byte, but only if the ID is nonzero`
	`1222`	`+ * and therefore is included in the report. Reports whose ID is zero`
	`1223`	`+ * never include an ID byte.`
`1220`	`1224`	`*/`
`1221`	`1225`	`static inline u32 hid_report_len(struct hid_report *report)`
`1222`	`1226`	`{`