From a66557c790208610bdc21c0c788e7b9524b1a356 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Thu, 13 Jul 2023 21:51:19 -0700 Subject: [PATCH 1/9] net: bonding: remove kernel-doc comment marker Change an errant kernel-doc comment marker (/**) to a regular comment to prevent a kernel-doc warning. bonding.h:282: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst * Returns NULL if the net_device does not belong to any of the bond's slaves Fixes: 1da177e4c3f4 ("Linux-2.6.12-rc2") Signed-off-by: Randy Dunlap Cc: Jay Vosburgh Cc: Andy Gospodarek Link: https://lore.kernel.org/r/20230714045127.18752-2-rdunlap@infradead.org Signed-off-by: Jakub Kicinski --- include/net/bonding.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/net/bonding.h b/include/net/bonding.h index b57bec6e737e..30ac427cf0c6 100644 --- a/include/net/bonding.h +++ b/include/net/bonding.h @@ -277,7 +277,7 @@ struct bond_vlan_tag { unsigned short vlan_id; }; -/** +/* * Returns NULL if the net_device does not belong to any of the bond's slaves * * Caller must hold bond lock for read From a63e40444e1bdb2ccdcd7c2e4afa51fdbc6c8589 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Thu, 13 Jul 2023 21:51:20 -0700 Subject: [PATCH 2/9] net: cfg802154: fix kernel-doc notation warnings Add an enum heading to the kernel-doc comments to prevent kernel-doc warnings. cfg802154.h:174: warning: Cannot understand * @WPAN_PHY_FLAG_TRANSMIT_POWER: Indicates that transceiver will support on line 174 - I thought it was a doc line cfg802154.h:192: warning: Enum value 'WPAN_PHY_FLAG_TXPOWER' not described in enum 'wpan_phy_flags' cfg802154.h:192: warning: Excess enum value 'WPAN_PHY_FLAG_TRANSMIT_POWER' description in 'wpan_phy_flags' Fixes: edea8f7c75ec ("cfg802154: introduce wpan phy flags") Signed-off-by: Randy Dunlap Cc: Alexander Aring Cc: Stefan Schmidt Cc: Marcel Holtmann Acked-by: Miquel Raynal Link: https://lore.kernel.org/r/20230714045127.18752-3-rdunlap@infradead.org Signed-off-by: Jakub Kicinski --- include/net/cfg802154.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/include/net/cfg802154.h b/include/net/cfg802154.h index e00057984489..f79ce133e51a 100644 --- a/include/net/cfg802154.h +++ b/include/net/cfg802154.h @@ -170,7 +170,8 @@ wpan_phy_cca_cmp(const struct wpan_phy_cca *a, const struct wpan_phy_cca *b) } /** - * @WPAN_PHY_FLAG_TRANSMIT_POWER: Indicates that transceiver will support + * enum wpan_phy_flags - WPAN PHY state flags + * @WPAN_PHY_FLAG_TXPOWER: Indicates that transceiver will support * transmit power setting. * @WPAN_PHY_FLAG_CCA_ED_LEVEL: Indicates that transceiver will support cca ed * level setting. From cfe57122bba5dc16ad64b162d97e42923fc7587e Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Thu, 13 Jul 2023 21:51:21 -0700 Subject: [PATCH 3/9] codel: fix kernel-doc notation warnings Use '@' before the struct member names in kernel-doc notation to prevent kernel-doc warnings. codel.h:158: warning: Function parameter or member 'ecn_mark' not described in 'codel_stats' codel.h:158: warning: Function parameter or member 'ce_mark' not described in 'codel_stats' Fixes: 76e3cc126bb2 ("codel: Controlled Delay AQM") Signed-off-by: Randy Dunlap Cc: Jamal Hadi Salim Cc: Cong Wang Cc: Jiri Pirko Cc: Dave Taht Link: https://lore.kernel.org/r/20230714045127.18752-4-rdunlap@infradead.org Signed-off-by: Jakub Kicinski --- include/net/codel.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/net/codel.h b/include/net/codel.h index 5fed2f16cb8d..aa80f744826c 100644 --- a/include/net/codel.h +++ b/include/net/codel.h @@ -145,8 +145,8 @@ struct codel_vars { * @maxpacket: largest packet we've seen so far * @drop_count: temp count of dropped packets in dequeue() * @drop_len: bytes of dropped packets in dequeue() - * ecn_mark: number of packets we ECN marked instead of dropping - * ce_mark: number of packets CE marked because sojourn time was above ce_threshold + * @ecn_mark: number of packets we ECN marked instead of dropping + * @ce_mark: number of packets CE marked because sojourn time was above ce_threshold */ struct codel_stats { u32 maxpacket; From 839f55c5ebdfc2c0825bc7e711a7dedaca11f84e Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Thu, 13 Jul 2023 21:51:22 -0700 Subject: [PATCH 4/9] devlink: fix kernel-doc notation warnings Spell function or struct member names correctly. Use ':' instead of '-' for struct member entries. Mark one field as private in kernel-doc. Add a few entries that were missing. Fix a typo. These changes prevent kernel-doc warnings: devlink.h:252: warning: Function parameter or member 'field_id' not described in 'devlink_dpipe_match' devlink.h:267: warning: Function parameter or member 'field_id' not described in 'devlink_dpipe_action' devlink.h:310: warning: Function parameter or member 'match_values_count' not described in 'devlink_dpipe_entry' devlink.h:355: warning: Function parameter or member 'list' not described in 'devlink_dpipe_table' devlink.h:374: warning: Function parameter or member 'actions_dump' not described in 'devlink_dpipe_table_ops' devlink.h:374: warning: Function parameter or member 'matches_dump' not described in 'devlink_dpipe_table_ops' devlink.h:374: warning: Function parameter or member 'entries_dump' not described in 'devlink_dpipe_table_ops' devlink.h:374: warning: Function parameter or member 'counters_set_update' not described in 'devlink_dpipe_table_ops' devlink.h:374: warning: Function parameter or member 'size_get' not described in 'devlink_dpipe_table_ops' devlink.h:384: warning: Function parameter or member 'headers' not described in 'devlink_dpipe_headers' devlink.h:384: warning: Function parameter or member 'headers_count' not described in 'devlink_dpipe_headers' devlink.h:398: warning: Function parameter or member 'unit' not described in 'devlink_resource_size_params' devlink.h:487: warning: Function parameter or member 'id' not described in 'devlink_param' devlink.h:645: warning: Function parameter or member 'overwrite_mask' not described in 'devlink_flash_update_params' Fixes: 1555d204e743 ("devlink: Support for pipeline debug (dpipe)") Fixes: d9f9b9a4d05f ("devlink: Add support for resource abstraction") Fixes: eabaef1896bc ("devlink: Add devlink_param register and unregister") Fixes: 5d5b4128c4ca ("devlink: introduce flash update overwrite mask") Signed-off-by: Randy Dunlap Cc: Jiri Pirko Cc: Moshe Shemesh Cc: Jacob Keller Link: https://lore.kernel.org/r/20230714045127.18752-5-rdunlap@infradead.org Signed-off-by: Jakub Kicinski --- include/net/devlink.h | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/include/net/devlink.h b/include/net/devlink.h index 9a3c51aa6e81..0cdb4b16e5b5 100644 --- a/include/net/devlink.h +++ b/include/net/devlink.h @@ -221,7 +221,7 @@ struct devlink_dpipe_field { /** * struct devlink_dpipe_header - dpipe header object * @name: header name - * @id: index, global/local detrmined by global bit + * @id: index, global/local determined by global bit * @fields: fields * @fields_count: number of fields * @global: indicates if header is shared like most protocol header @@ -241,7 +241,7 @@ struct devlink_dpipe_header { * @header_index: header index (packets can have several headers of same * type like in case of tunnels) * @header: header - * @fieled_id: field index + * @field_id: field index */ struct devlink_dpipe_match { enum devlink_dpipe_match_type type; @@ -256,7 +256,7 @@ struct devlink_dpipe_match { * @header_index: header index (packets can have several headers of same * type like in case of tunnels) * @header: header - * @fieled_id: field index + * @field_id: field index */ struct devlink_dpipe_action { enum devlink_dpipe_action_type type; @@ -292,7 +292,7 @@ struct devlink_dpipe_value { * struct devlink_dpipe_entry - table entry object * @index: index of the entry in the table * @match_values: match values - * @matche_values_count: count of matches tuples + * @match_values_count: count of matches tuples * @action_values: actions values * @action_values_count: count of actions values * @counter: value of counter @@ -342,7 +342,9 @@ struct devlink_dpipe_table_ops; */ struct devlink_dpipe_table { void *priv; + /* private: */ struct list_head list; + /* public: */ const char *name; bool counters_enabled; bool counter_control_extern; @@ -355,13 +357,13 @@ struct devlink_dpipe_table { /** * struct devlink_dpipe_table_ops - dpipe_table ops - * @actions_dump - dumps all tables actions - * @matches_dump - dumps all tables matches - * @entries_dump - dumps all active entries in the table - * @counters_set_update - when changing the counter status hardware sync + * @actions_dump: dumps all tables actions + * @matches_dump: dumps all tables matches + * @entries_dump: dumps all active entries in the table + * @counters_set_update: when changing the counter status hardware sync * maybe needed to allocate/free counter related * resources - * @size_get - get size + * @size_get: get size */ struct devlink_dpipe_table_ops { int (*actions_dump)(void *priv, struct sk_buff *skb); @@ -374,8 +376,8 @@ struct devlink_dpipe_table_ops { /** * struct devlink_dpipe_headers - dpipe headers - * @headers - header array can be shared (global bit) or driver specific - * @headers_count - count of headers + * @headers: header array can be shared (global bit) or driver specific + * @headers_count: count of headers */ struct devlink_dpipe_headers { struct devlink_dpipe_header **headers; @@ -387,7 +389,7 @@ struct devlink_dpipe_headers { * @size_min: minimum size which can be set * @size_max: maximum size which can be set * @size_granularity: size granularity - * @size_unit: resource's basic unit + * @unit: resource's basic unit */ struct devlink_resource_size_params { u64 size_min; @@ -457,6 +459,7 @@ struct devlink_flash_notify { /** * struct devlink_param - devlink configuration parameter data + * @id: devlink parameter id number * @name: name of the parameter * @generic: indicates if the parameter is generic or driver specific * @type: parameter type @@ -632,6 +635,7 @@ enum devlink_param_generic_id { * struct devlink_flash_update_params - Flash Update parameters * @fw: pointer to the firmware data to update from * @component: the flash component to update + * @overwrite_mask: which types of flash update are supported (may be %0) * * With the exception of fw, drivers must opt-in to parameters by * setting the appropriate bit in the supported_flash_update_params field in From d20909a0689f585fb6443da2d8797f7ad549f931 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Thu, 13 Jul 2023 21:51:23 -0700 Subject: [PATCH 5/9] inet: frags: eliminate kernel-doc warning Modify the anonymous enum kernel-doc content so that it doesn't cause a kernel-doc warning. inet_frag.h:33: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst Fixes: 1ab1934ed80a ("inet: frags: enum the flag definitions and add descriptions") Signed-off-by: Randy Dunlap Cc: Nikolay Aleksandrov Link: https://lore.kernel.org/r/20230714045127.18752-6-rdunlap@infradead.org Signed-off-by: Jakub Kicinski --- include/net/inet_frag.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/net/inet_frag.h b/include/net/inet_frag.h index 325ad893f624..153960663ce4 100644 --- a/include/net/inet_frag.h +++ b/include/net/inet_frag.h @@ -29,7 +29,7 @@ struct fqdir { }; /** - * fragment queue flags + * enum: fragment queue flags * * @INET_FRAG_FIRST_IN: first fragment has arrived * @INET_FRAG_LAST_IN: final fragment has arrived From 201a08830d8c4698f97ce65329ba92e36b7f402a Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Thu, 13 Jul 2023 21:51:24 -0700 Subject: [PATCH 6/9] net: llc: fix kernel-doc notation warnings Use the corrent function parameter name or format to prevent kernel-doc warnings. Add 2 function parameter descriptions to prevent kernel-doc warnings. llc_pdu.h:278: warning: Function parameter or member 'da' not described in 'llc_pdu_decode_da' llc_pdu.h:278: warning: Excess function parameter 'sa' description in 'llc_pdu_decode_da' llc_pdu.h:330: warning: Function parameter or member 'skb' not described in 'llc_pdu_init_as_test_cmd' llc_pdu.h:379: warning: Function parameter or member 'svcs_supported' not described in 'llc_pdu_init_as_xid_cmd' llc_pdu.h:379: warning: Function parameter or member 'rx_window' not described in 'llc_pdu_init_as_xid_cmd' Fixes: 1da177e4c3f4 ("Linux-2.6.12-rc2") Signed-off-by: Randy Dunlap Link: https://lore.kernel.org/r/20230714045127.18752-7-rdunlap@infradead.org Signed-off-by: Jakub Kicinski --- include/net/llc_pdu.h | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/include/net/llc_pdu.h b/include/net/llc_pdu.h index 49aa79c7b278..7e73f8e5e497 100644 --- a/include/net/llc_pdu.h +++ b/include/net/llc_pdu.h @@ -269,7 +269,7 @@ static inline void llc_pdu_decode_sa(struct sk_buff *skb, u8 *sa) /** * llc_pdu_decode_da - extracts dest address of input frame * @skb: input skb that destination address must be extracted from it - * @sa: pointer to destination address (6 byte array). + * @da: pointer to destination address (6 byte array). * * This function extracts destination address(MAC) of input frame. */ @@ -321,7 +321,7 @@ static inline void llc_pdu_init_as_ui_cmd(struct sk_buff *skb) /** * llc_pdu_init_as_test_cmd - sets PDU as TEST - * @skb - Address of the skb to build + * @skb: Address of the skb to build * * Sets a PDU as TEST */ @@ -369,6 +369,8 @@ struct llc_xid_info { /** * llc_pdu_init_as_xid_cmd - sets bytes 3, 4 & 5 of LLC header as XID * @skb: input skb that header must be set into it. + * @svcs_supported: The class of the LLC (I or II) + * @rx_window: The size of the receive window of the LLC * * This function sets third,fourth,fifth and sixth bytes of LLC header as * a XID PDU. From d1533d726aa1efca3a7ae8f40c94ccb149d22e6a Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Thu, 13 Jul 2023 21:51:25 -0700 Subject: [PATCH 7/9] net: NSH: fix kernel-doc notation warning Use the struct member's name and the correct format to prevent a kernel-doc warning. nsh.h:200: warning: Function parameter or member 'context' not described in 'nsh_md1_ctx' Fixes: 1f0b7744c505 ("net: add NSH header structures and helpers") Signed-off-by: Randy Dunlap Cc: Jiri Benc Link: https://lore.kernel.org/r/20230714045127.18752-8-rdunlap@infradead.org Signed-off-by: Jakub Kicinski --- include/net/nsh.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/net/nsh.h b/include/net/nsh.h index 350b1ad11c7f..16a751093896 100644 --- a/include/net/nsh.h +++ b/include/net/nsh.h @@ -192,7 +192,7 @@ /** * struct nsh_md1_ctx - Keeps track of NSH context data - * @nshc<1-4>: NSH Contexts. + * @context: NSH Contexts. */ struct nsh_md1_ctx { __be32 context[4]; From d1cca974548d76e0fa8b6761d25f7b47376a3780 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Thu, 13 Jul 2023 21:51:26 -0700 Subject: [PATCH 8/9] pie: fix kernel-doc notation warning Spell a struct member's name correctly to prevent a kernel-doc warning. pie.h:38: warning: Function parameter or member 'tupdate' not described in 'pie_params' Fixes: b42a3d7c7cff ("pie: improve comments and commenting style") Signed-off-by: Randy Dunlap Cc: Leslie Monis Cc: "Mohit P. Tahiliani" Cc: Gautam Ramakrishnan Cc: Jamal Hadi Salim Cc: Cong Wang Cc: Jiri Pirko Link: https://lore.kernel.org/r/20230714045127.18752-9-rdunlap@infradead.org Signed-off-by: Jakub Kicinski --- include/net/pie.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/net/pie.h b/include/net/pie.h index 3fe2361e03b4..01cbc66825a4 100644 --- a/include/net/pie.h +++ b/include/net/pie.h @@ -17,7 +17,7 @@ /** * struct pie_params - contains pie parameters * @target: target delay in pschedtime - * @tudpate: interval at which drop probability is calculated + * @tupdate: interval at which drop probability is calculated * @limit: total number of packets that can be in the queue * @alpha: parameter to control drop probability * @beta: parameter to control drop probability From 04be3c95da8266a099c8446b6d1205ccf8a62e66 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Thu, 13 Jul 2023 21:51:27 -0700 Subject: [PATCH 9/9] rsi: remove kernel-doc comment marker Change an errant kernel-doc comment marker (/**) to a regular comment to prevent a kernel-doc warning. rsi_91x.h:3: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst * Copyright (c) 2017 Redpine Signals Inc. Fixes: 4c10d56a76bb ("rsi: add header file rsi_91x") Signed-off-by: Randy Dunlap Cc: Prameela Rani Garnepudi Cc: Siva Rebbagondla Acked-by: Kalle Valo Link: https://lore.kernel.org/r/20230714045127.18752-10-rdunlap@infradead.org Signed-off-by: Jakub Kicinski --- include/net/rsi_91x.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/net/rsi_91x.h b/include/net/rsi_91x.h index 040f07b47f1f..b2283762e446 100644 --- a/include/net/rsi_91x.h +++ b/include/net/rsi_91x.h @@ -1,4 +1,4 @@ -/** +/* * Copyright (c) 2017 Redpine Signals Inc. * * Permission to use, copy, modify, and/or distribute this software for any