From: Bart Van Assche <bvanassche@acm.org>
To: "Jens Axboe" <axboe@kernel.dk>,
"André Almeida" <andrealmeid@collabora.com>,
linux-block@vger.kernel.org, linux-kernel@vger.kernel.org
Cc: kernel@collabora.com, krisman@collabora.com
Subject: Re: [PATCH 1/1] blk-mq: fill header with kernel-doc
Date: Wed, 2 Oct 2019 13:27:16 -0700 [thread overview]
Message-ID: <f46014fd-b29d-aee5-d49d-d2c5f2ddfb9f@acm.org> (raw)
In-Reply-To: <f1ca9de7-383b-4a84-31d0-92cfbb3759b2@kernel.dk>
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.
next prev parent reply other threads:[~2019-10-02 20:27 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-09-30 19:48 [PATCH 1/1] blk-mq: fill header with kernel-doc André Almeida
[not found] ` <CGME20190930211400epcas2p4253bdc8cc3630f87d7e955cd23fdf1f2@epcms2p6>
2019-09-30 21:54 ` Minwoo Im
2019-10-01 0:01 ` André Almeida
2019-09-30 22:01 ` Bart Van Assche
2019-10-01 0:01 ` André Almeida
2019-10-02 3:33 ` Jens Axboe
2019-10-02 17:18 ` André Almeida
2019-10-02 20:27 ` Bart Van Assche [this message]
2019-10-02 21:05 ` André Almeida
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=f46014fd-b29d-aee5-d49d-d2c5f2ddfb9f@acm.org \
--to=bvanassche@acm.org \
--cc=andrealmeid@collabora.com \
--cc=axboe@kernel.dk \
--cc=kernel@collabora.com \
--cc=krisman@collabora.com \
--cc=linux-block@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).