Re: [PATCH 05/12] infiniband: fix ulp/opa_vnic/opa_vnic_encap.h kernel-doc notation

[Jani Nikula <jani.nikula@linux.intel.com>]

On Tue, 22 Oct 2019, Randy Dunlap <rdunlap@infradead.org> wrote:
> On 10/22/19 10:52 AM, Jason Gunthorpe wrote:
>> On Wed, Oct 09, 2019 at 08:52:44PM -0700, rd.dunlab@gmail.com 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