Hello Bart,
On 10/2/19 5:27 PM, Bart Van Assche wrote:
> 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:
The same documentation also suggests that one can use inline comments:
In-line member documentation comments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The structure members may also be documented in-line within the definition.
There are two styles, single-line comments where both the opening
``/**`` and
closing ``*/`` are on the same line, and multi-line comments where they
are each
on a line of their own, like all other kernel-doc comments::
/**
* struct foo - Brief description.
* @foo: The Foo member.
*/
struct foo {
int foo;
/**
* @bar: The Bar member.
*/
...
You can also check this here:
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#in-line-member-documentation-comments
Thanks,
André
