Re: [PATCH 1/1] blk-mq: fill header with kernel-doc

[Bart Van Assche]

On 10/1/19 8:33 PM, Jens Axboe wrote:
> On 9/30/19 1:48 PM, Andrà Almeida wrote:
> > -
> > +/**
> > + * struct blk_mq_ops - list of callback functions for blk-mq drivers
> > + */
> >    struct blk_mq_ops {
> > -	/*
> > -	 * Queue request
> > +	/**
> > +	 * @queue_rq: Queue a new request from block IO.
> >    	 */
> >    	queue_rq_fn		*queue_rq;
> >    
> > -	/*
> > -	 * If a driver uses bd->last to judge when to submit requests to
> > -	 * hardware, it must define this function. In case of errors that
> > -	 * make us stop issuing further requests, this hook serves the
> > +	/**
> > +	 * @commit_rqs: If a driver uses bd->last to judge when to submit
> > +	 * requests to hardware, it must define this function. In case of errors
> > +	 * that make us stop issuing further requests, this hook serves the
> >    	 * purpose of kicking the hardware (which the last request otherwise
> >    	 * would have done).
> >    	 */
> >    	commit_rqs_fn		*commit_rqs;
>
> Stuff like this is MUCH better. Why isn't all of it done like this?

Hi Jens,

If you prefer this style you may want to update
Documentation/doc-guide/kernel-doc.rst. I think that document recommends 
another style for documenting struct members, maybe because that style 
requires less vertical space:

------------------------------------------------------------------------
Structure, union, and enumeration documentation
-----------------------------------------------

The general format of a struct, union, and enum kernel-doc comment is::

  /**
   * struct struct_name - Brief description.
   * @member1: Description of member1.
   * @member2: Description of member2.
   *           One can provide multiple line descriptions
   *           for members.
   *
   * Description of the structure.
   */

You can replace the ``struct`` in the above example with ``union`` or
``enum``  to describe unions or enums. ``member`` is used to mean struct
and union member names as well as enumerations in an enum.

The brief description following the structure name may span multiple
lines, and ends with a member description, a blank comment line, or the
end of the comment block.
------------------------------------------------------------------------

Thanks,

Bart.