On Tue, 22 Oct 2019, Randy Dunlap <rdunlap@xxxxxxxxxxxxx> wrote:
> On 10/22/19 10:52 AM, Jason Gunthorpe wrote:
>> On Wed, Oct 09, 2019 at 08:52:44PM -0700, rd.dunlab@xxxxxxxxx wrote:
>>> Make reserved struct fields "private:" so that they don't need to
>>> be added to the kernel-doc notation. This removes 24 warnings.
>>
>>> +++ linux-next-20191009/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h
>>> @@ -129,21 +129,31 @@ struct opa_vesw_info {
>>> __be16 fabric_id;
>>> __be16 vesw_id;
>>>
>>> + /* private: */
>>> u8 rsvd0[6];
>>> + /* public: */
>>> __be16 def_port_mask;
>>
>> This seems overly ugly, is there some other way to handle these
>> reserved fields? Maybe wire protocol structures shouldn't be kdoc?
>
> I don't know of any other way to handle them with kernel-doc.
> Sure, changing the /** to just /* would be one way to hide the
> warnings. Either this patch or not having them be kernel-doc
> is needed just to "fix" 24 warnings.
The currently available options are:
- The patch at hand (private/public comments). Ugly and verbose.
- Document the structs using regular comments instead of
kernel-doc. Might be suitable here, but not a generally useful
approach. Loses all format checking and generated documentation.
- Also document the reserved fields. Ugly and verbose, also in the
generated documentation.
Some options that I think might be relatively easy to implement:
- Add struct documentation comment indicator to not complain about
missing member documentation. Some special tag in the struct
comment. This would also ignore members that actually need to be
documented.
- Add support for designating private members in the member
documentation, i.e. require the documentation, but omit the members
from the generated document. Something like this, with PRIVATE
replaced with your favorite bikeshed colors:
/**
* @rsvd0: PRIVATE
*/
This could be used either in the struct documentation comment or in
the inline member documentation comment. Less ugly than the patch at
hand, and arguably a better notation, but still requires documenting
the members.
- Add support for a catch-all member documentation comment, for example:
/**
* struct foo - bar
* @*: This member is private.
*/
Would generate the documentation for the member with the catch-all
documentation, which might be a generally useful feature, and would be
easy on the source code side. This could be combined with the PRIVATE
designation above, practically leading to the same result as the first
option but with more flexibility.
BR,
Jani.
--
Jani Nikula, Intel Open Source Graphics Center
