[PATCH] ath9k: debug.h: fix kernel-doc bad lines and struct ath_tx_stats

[PATCH] ath9k: debug.h: fix kernel-doc bad lines and struct ath_tx_stats

[Randy Dunlap]

Repair "bad line" warnings by starting each line with " *".
Add or correct kernel-doc entries for missing struct members in
struct ath_tx_stats.

Warning: ../drivers/net/wireless/ath/ath9k/debug.h:144 bad line:
  may have had errors.
Warning: ../drivers/net/wireless/ath/ath9k/debug.h:146 bad line:
  may have had errors.
Warning: ../drivers/net/wireless/ath/ath9k/debug.h:156 bad line:
  Valid only for:
Warning: ../drivers/net/wireless/ath/ath9k/debug.h:157 bad line:
  - non-aggregate condition.
Warning: ../drivers/net/wireless/ath/ath9k/debug.h:158 bad line:
  - first packet of aggregate.
Warning: drivers/net/wireless/ath/ath9k/debug.h:191 struct member
 'xretries' not described in 'ath_tx_stats'
Warning: drivers/net/wireless/ath/ath9k/debug.h:191 struct member
 'data_underrun' not described in 'ath_tx_stats'
Warning: drivers/net/wireless/ath/ath9k/debug.h:191 struct member
 'delim_underrun' not described in 'ath_tx_stats'

Fixes: 99c15bf575b1 ("ath9k: Report total tx/rx bytes and packets in debugfs.")
Fixes: fec247c0d5bf ("ath9k: Add debug counters for TX")
Fixes: 5a6f78afdabe ("ath9k: show excessive-retry MPDUs in debugfs")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Toke Høiland-Jørgensen <toke@toke.dk>
Cc: Johannes Berg <johannes@sipsolutions.net>
Cc: linux-wireless@vger.kernel.org
---
 drivers/net/wireless/ath/ath9k/debug.h |   15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

--- linux-next-20251107.orig/drivers/net/wireless/ath/ath9k/debug.h
+++ linux-next-20251107/drivers/net/wireless/ath/ath9k/debug.h
@@ -142,11 +142,12 @@ struct ath_interrupt_stats {
 /**
  * struct ath_tx_stats - Statistics about TX
  * @tx_pkts_all:  No. of total frames transmitted, including ones that
-	may have had errors.
+ *	may have had errors.
  * @tx_bytes_all:  No. of total bytes transmitted, including ones that
-	may have had errors.
+ *	may have had errors.
  * @queued: Total MPDUs (non-aggr) queued
  * @completed: Total MPDUs (non-aggr) completed
+ * @xretries: Total MPDUs with xretries
  * @a_aggr: Total no. of aggregates queued
  * @a_queued_hw: Total AMPDUs queued to hardware
  * @a_completed: Total AMPDUs completed
@@ -154,14 +155,14 @@ struct ath_interrupt_stats {
  * @a_xretries: No. of AMPDUs dropped due to xretries
  * @txerr_filtered: No. of frames with TXERR_FILT flag set.
  * @fifo_underrun: FIFO underrun occurrences
-	Valid only for:
-		- non-aggregate condition.
-		- first packet of aggregate.
+ *	Valid only for:
+ *		- non-aggregate condition.
+ *		- first packet of aggregate.
  * @xtxop: No. of frames filtered because of TXOP limit
  * @timer_exp: Transmit timer expiry
  * @desc_cfg_err: Descriptor configuration errors
- * @data_urn: TX data underrun errors
- * @delim_urn: TX delimiter underrun errors
+ * @data_underrun: TX data underrun errors
+ * @delim_underrun: TX delimiter underrun errors
  * @puttxbuf: Number of times hardware was given txbuf to write.
  * @txstart:  Number of times hardware was told to start tx.
  * @txprocdesc:  Number of times tx descriptor was processed

Re: [PATCH] ath9k: debug.h: fix kernel-doc bad lines and struct ath_tx_stats

[Toke Høiland-Jørgensen]

Randy Dunlap <rdunlap@infradead.org> writes:

> Repair "bad line" warnings by starting each line with " *".
> Add or correct kernel-doc entries for missing struct members in
> struct ath_tx_stats.
>
> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:144 bad line:
>   may have had errors.
> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:146 bad line:
>   may have had errors.
> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:156 bad line:
>   Valid only for:
> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:157 bad line:
>   - non-aggregate condition.
> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:158 bad line:
>   - first packet of aggregate.
> Warning: drivers/net/wireless/ath/ath9k/debug.h:191 struct member
>  'xretries' not described in 'ath_tx_stats'
> Warning: drivers/net/wireless/ath/ath9k/debug.h:191 struct member
>  'data_underrun' not described in 'ath_tx_stats'
> Warning: drivers/net/wireless/ath/ath9k/debug.h:191 struct member
>  'delim_underrun' not described in 'ath_tx_stats'
>
> Fixes: 99c15bf575b1 ("ath9k: Report total tx/rx bytes and packets in debugfs.")
> Fixes: fec247c0d5bf ("ath9k: Add debug counters for TX")
> Fixes: 5a6f78afdabe ("ath9k: show excessive-retry MPDUs in debugfs")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>

Acked-by: Toke Høiland-Jørgensen <toke@toke.dk>

Re: [PATCH] ath9k: debug.h: fix kernel-doc bad lines and struct ath_tx_stats

[Jeff Johnson]

On 11/16/2025 6:03 PM, Randy Dunlap wrote:
> Repair "bad line" warnings by starting each line with " *".
> Add or correct kernel-doc entries for missing struct members in
> struct ath_tx_stats.
> 
> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:144 bad line:
>   may have had errors.
> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:146 bad line:
>   may have had errors.
> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:156 bad line:
>   Valid only for:
> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:157 bad line:
>   - non-aggregate condition.
> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:158 bad line:
>   - first packet of aggregate.
> Warning: drivers/net/wireless/ath/ath9k/debug.h:191 struct member
>  'xretries' not described in 'ath_tx_stats'
> Warning: drivers/net/wireless/ath/ath9k/debug.h:191 struct member
>  'data_underrun' not described in 'ath_tx_stats'
> Warning: drivers/net/wireless/ath/ath9k/debug.h:191 struct member
>  'delim_underrun' not described in 'ath_tx_stats'
> 
> Fixes: 99c15bf575b1 ("ath9k: Report total tx/rx bytes and packets in debugfs.")
> Fixes: fec247c0d5bf ("ath9k: Add debug counters for TX")
> Fixes: 5a6f78afdabe ("ath9k: show excessive-retry MPDUs in debugfs")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> ---
> Cc: Toke Høiland-Jørgensen <toke@toke.dk>
> Cc: Johannes Berg <johannes@sipsolutions.net>
> Cc: linux-wireless@vger.kernel.org

I'm picking this up, but my automation noticed there are still kdoc issues:
Warning: drivers/net/wireless/ath/ath9k/debug.h:138 struct member 'txeol' not described in 'ath_interrupt_stats'
...
Warning: drivers/net/wireless/ath/ath9k/debug.h:138 struct member 'mac_sleep_access' not described in 'ath_interrupt_stats'
19 warnings as errors

Are these handled elsewhere, or will they need to be handled later?

/jeff

Re: [PATCH] ath9k: debug.h: fix kernel-doc bad lines and struct ath_tx_stats

[Randy Dunlap]

On 1/14/26 7:53 AM, Jeff Johnson wrote:
> On 11/16/2025 6:03 PM, Randy Dunlap wrote:
>> Repair "bad line" warnings by starting each line with " *".
>> Add or correct kernel-doc entries for missing struct members in
>> struct ath_tx_stats.
>>
>> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:144 bad line:
>>   may have had errors.
>> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:146 bad line:
>>   may have had errors.
>> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:156 bad line:
>>   Valid only for:
>> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:157 bad line:
>>   - non-aggregate condition.
>> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:158 bad line:
>>   - first packet of aggregate.
>> Warning: drivers/net/wireless/ath/ath9k/debug.h:191 struct member
>>  'xretries' not described in 'ath_tx_stats'
>> Warning: drivers/net/wireless/ath/ath9k/debug.h:191 struct member
>>  'data_underrun' not described in 'ath_tx_stats'
>> Warning: drivers/net/wireless/ath/ath9k/debug.h:191 struct member
>>  'delim_underrun' not described in 'ath_tx_stats'
>>
>> Fixes: 99c15bf575b1 ("ath9k: Report total tx/rx bytes and packets in debugfs.")
>> Fixes: fec247c0d5bf ("ath9k: Add debug counters for TX")
>> Fixes: 5a6f78afdabe ("ath9k: show excessive-retry MPDUs in debugfs")
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> ---
>> Cc: Toke Høiland-Jørgensen <toke@toke.dk>
>> Cc: Johannes Berg <johannes@sipsolutions.net>
>> Cc: linux-wireless@vger.kernel.org
> 
> I'm picking this up, but my automation noticed there are still kdoc issues:
> Warning: drivers/net/wireless/ath/ath9k/debug.h:138 struct member 'txeol' not described in 'ath_interrupt_stats'
> ...
> Warning: drivers/net/wireless/ath/ath9k/debug.h:138 struct member 'mac_sleep_access' not described in 'ath_interrupt_stats'
> 19 warnings as errors
> 
> Are these handled elsewhere, or will they need to be handled later?
> 
> /jeff

Hi Jeff,
I didn't attempt to address those warnings. They need to be handled
later by someone who knows that they are.

-- 
~Randy

Re: [PATCH] ath9k: debug.h: fix kernel-doc bad lines and struct ath_tx_stats

[Jeff Johnson]

On Sun, 16 Nov 2025 18:03:03 -0800, Randy Dunlap wrote:
> Repair "bad line" warnings by starting each line with " *".
> Add or correct kernel-doc entries for missing struct members in
> struct ath_tx_stats.
> 
> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:144 bad line:
>   may have had errors.
> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:146 bad line:
>   may have had errors.
> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:156 bad line:
>   Valid only for:
> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:157 bad line:
>   - non-aggregate condition.
> Warning: ../drivers/net/wireless/ath/ath9k/debug.h:158 bad line:
>   - first packet of aggregate.
> Warning: drivers/net/wireless/ath/ath9k/debug.h:191 struct member
>  'xretries' not described in 'ath_tx_stats'
> Warning: drivers/net/wireless/ath/ath9k/debug.h:191 struct member
>  'data_underrun' not described in 'ath_tx_stats'
> Warning: drivers/net/wireless/ath/ath9k/debug.h:191 struct member
>  'delim_underrun' not described in 'ath_tx_stats'
> 
> [...]

Applied, thanks!

[1/1] ath9k: debug.h: fix kernel-doc bad lines and struct ath_tx_stats
      commit: c6131765a2c0052b2c5a2310ff92191ff33aec8b

Best regards,
-- 
Jeff Johnson <jeff.johnson@oss.qualcomm.com>