lkml.org 
[lkml]   [2019]   [Oct]   [2]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
SubjectRe: [PATCH 1/1] blk-mq: fill header with kernel-doc
From
Date
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.

\
 
 \ /
  Last update: 2019-10-02 22:28    [W:0.076 / U:2.152 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site