Re: [PATCH] wifi: ath11k: document HAL_RX_BUF_RBM_SW4_BM

[Kalle Valo]

Jeff Johnson <quic_jjohnson@xxxxxxxxxxx> writes:

> On 1/14/2024 7:17 AM, Kalle Valo wrote:
>> Jeff Johnson <quic_jjohnson@xxxxxxxxxxx> writes:
>> 
>>> Commit 7636c9a6e7d7 ("wifi: ath11k: Add multi TX ring support for WCN6750")
>>> added HAL_RX_BUF_RBM_SW4_BM to enum hal_rx_buf_return_buf_manager. However,
>>> as flagged by the kernel-doc script, the documentation was not updated:
>>>
>>> drivers/net/wireless/ath/ath11k/hal.h:689: warning: Enum value
>>> 'HAL_RX_BUF_RBM_SW4_BM' not described in enum
>>> 'hal_rx_buf_return_buf_manager'
>>>
>>> So update the documentation. No functional changes, compile tested only.
>>>
>>> Signed-off-by: Jeff Johnson <quic_jjohnson@xxxxxxxxxxx>
>> 
>> I'm not really a fan of kernel-doc in wireless drivers, it feels more
>> unnecessary work. Should we remove the kernel-doc markings from ath11k
>> altogether?
>
> Are you not a fan of kernel-doc format specifically, or not a fan of
> documentation at all?

I'm definitely a fan of documentation where it makes sense, but I'm not
fan of kernel-doc if there are no users or readers. For example, using
kernel-doc in cfg80211 or mac80211 makes a lot of sense, and is
important, but I'm not convinced about using kernel-doc in wireless
drivers.

> I'm personally a fan of documentation since good documentation makes the
> code more maintainable. Yes, there is a cost in creating and maintaining
> the documentation, but this is hopefully offset by cost saving when new
> developers are trying to understand and modify the code.
>
> I'm also a fan of consistency. And since kernel-doc is the standard
> format defined for the kernel, it is my personal preference to use that
> format.

I understand your points and if we had plenty of free time I would be
onboard with this. To keep my mail short few quick points:

* To make sure there are no kernel-doc warnings we would have to add
  checks to ath11k-check, which would slow down it considerably and it
  would again slow down our workflow (I run it several times a day).

* To use kernel-doc formatting alone doesn't really make sense so we
  would have to start creating a kernel-doc book or something. But who
  would read it?

* kernel-doc moves field documentation in structures away from the
  actual fields which I find confusing.

* The risk of having outdated kernel-doc documentation is high, it would
  need active maintenance etc.

* I'm worried about creating useless documentation, like "Count number
  foo" for foo_count() just because of kernel-doc.

This is why I consider return on investment is low here :) My preference
is to make the code understandable (good symbol names etc) and document
the special cases, which are not obvious from the code, with a normal
code comment.

> I'm curious what others think of the ath10/11/12k level and style of
> documentation.

IIRC iwlwifi uses kernel-doc to document the firmware interface, not
sure how much it's used elsewhere in the driver.

-- 
https://patchwork.kernel.org/project/linux-wireless/list/

https://wireless.wiki.kernel.org/en/developers/documentation/submittingpatches