From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Jason Gunthorpe <jgg@nvidia.com>
Cc: "Linux Doc Mailing List" <linux-doc@vger.kernel.org>,
"Gustavo A. R. Silva" <gustavoars@kernel.org>,
"Håkon Bugge" <haakon.bugge@oracle.com>,
"Jonathan Corbet" <corbet@lwn.net>,
"Bart Van Assche" <bvanassche@acm.org>,
"Chuck Lever" <chuck.lever@oracle.com>,
"Danit Goldberg" <danitg@mellanox.com>,
"Dennis Dalessandro" <dennis.dalessandro@cornelisnetworks.com>,
"Divya Indi" <divya.indi@oracle.com>,
"Doug Ledford" <dledford@redhat.com>,
"Gal Pressman" <galpress@amazon.com>,
"Leon Romanovsky" <leon@kernel.org>,
"Maor Gottlieb" <maorg@mellanox.com>,
"Max Gurtovoy" <mgurtovoy@nvidia.com>,
"Mike Marciniszyn" <mike.marciniszyn@cornelisnetworks.com>,
"Moni Shoua" <monis@mellanox.com>,
"Or Gerlitz" <ogerlitz@mellanox.com>,
"Parav Pandit" <parav@mellanox.com>,
"Sagi Grimberg" <sagi@grimberg.me>,
"Ursula Braun" <ubraun@linux.ibm.com>,
"Xi Wang" <wangxi11@huawei.com>,
"Yamin Friedman" <yaminf@mellanox.com>,
linux-kernel@vger.kernel.org, linux-rdma@vger.kernel.org,
target-devel@vger.kernel.org
Subject: Re: [PATCH v4 07/27] IB: fix kernel-doc markups
Date: Tue, 1 Dec 2020 12:39:21 +0100 [thread overview]
Message-ID: <20201201123921.2009cbea@coco.lan> (raw)
In-Reply-To: <20201123234542.GA142861@nvidia.com>
Em Mon, 23 Nov 2020 19:45:42 -0400
Jason Gunthorpe <jgg@nvidia.com> escreveu:
> On Mon, Nov 16, 2020 at 11:18:03AM +0100, Mauro Carvalho Chehab wrote:
>
> > +/**
> > + * ib_alloc_pd - Allocates an unused protection domain.
> > + * @device: The device on which to allocate the protection domain.
> > + * @flags: protection domain flags
> > + *
> > + * A protection domain object provides an association between QPs, shared
> > + * receive queues, address handles, memory regions, and memory windows.
> > + *
> > + * Every PD has a local_dma_lkey which can be used as the lkey value for local
> > + * memory operations.
> > + */
> > #define ib_alloc_pd(device, flags) \
> > __ib_alloc_pd((device), (flags), KBUILD_MODNAME)
>
> Why this hunk adding a completely new description in this patch?
In order to document ib_alloc_pd().
See, currently, verbs.c has this kernel-doc markup:
/**
* ib_alloc_pd - Allocates an unused protection domain.
* @device: The device on which to allocate the protection domain.
* @flags: protection domain flags
* @caller: caller's build-time module name
*
* A protection domain object provides an association between QPs, shared
* receive queues, address handles, memory regions, and memory windows.
*
* Every PD has a local_dma_lkey which can be used as the lkey value for local
* memory operations.
*/
struct ib_pd *__ib_alloc_pd(struct ib_device *device, unsigned int flags,
const char *caller)
Which doesn't actually work as expected, as kernel-doc will, instead,
document __ib_alloc_pd():
$ ./scripts/kernel-doc -sphinx-version 3.1 -function ib_alloc_pd drivers/infiniband/core/verbs.c
drivers/infiniband/core/verbs.c:1: warning: 'ib_alloc_pd' not found
$ ./scripts/kernel-doc -sphinx-version 3.1 -function __ib_alloc_pd drivers/infiniband/core/verbs.c
.. c:function:: struct ib_pd * __ib_alloc_pd (struct ib_device *device, unsigned int flags, const char *caller)
Allocates an unused protection domain.
**Parameters**
``struct ib_device *device``
The device on which to allocate the protection domain.
``unsigned int flags``
protection domain flags
``const char *caller``
caller's build-time module name
**Description**
A protection domain object provides an association between QPs, shared
receive queues, address handles, memory regions, and memory windows.
Every PD has a local_dma_lkey which can be used as the lkey value for local
memory operations.
So, what this patch does is to fix the kernel-doc markup at verbs.c for
it to reflect the function that it is documented, adding a new markup for
ib_alloc_pd(), which is identical to __ib_alloc_pd(), except for the
@caller field, which is set to KBUILD_MODNAME by this macro.
Thanks,
Mauro
next prev parent reply other threads:[~2020-12-01 11:40 UTC|newest]
Thread overview: 51+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
2020-11-16 10:17 ` [PATCH v4 01/27] net: phy: fix " Mauro Carvalho Chehab
2020-11-16 10:17 ` [PATCH v4 02/27] net: datagram: fix some " Mauro Carvalho Chehab
2020-11-16 10:20 ` Kirill Tkhai
2020-11-16 10:17 ` [PATCH v4 03/27] net: core: " Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 04/27] s390: fix " Mauro Carvalho Chehab
2020-11-16 10:25 ` Cornelia Huck
2020-11-16 10:38 ` Vineeth Vijayan
2020-11-16 12:04 ` Vineeth Vijayan
2020-11-16 10:18 ` [PATCH v4 05/27] drm: fix some " Mauro Carvalho Chehab
2020-11-16 11:37 ` Jani Nikula
2020-11-16 19:48 ` Daniel Vetter
2020-11-16 10:18 ` [PATCH v4 06/27] HSI: fix a kernel-doc markup Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 07/27] IB: fix kernel-doc markups Mauro Carvalho Chehab
2020-11-16 10:36 ` Gustavo A. R. Silva
2020-11-23 23:45 ` Jason Gunthorpe
2020-12-01 11:39 ` Mauro Carvalho Chehab [this message]
2020-11-16 10:18 ` [PATCH v4 08/27] parport: fix a kernel-doc markup Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 09/27] rapidio: fix kernel-doc a markup Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 10/27] video: fix some kernel-doc markups Mauro Carvalho Chehab
2020-11-16 15:36 ` Daniel Vetter
2020-11-16 16:38 ` Mauro Carvalho Chehab
2020-11-16 17:24 ` Daniel Vetter
2020-11-16 18:11 ` Sam Ravnborg
2020-11-16 19:43 ` Daniel Vetter
2020-11-16 18:42 ` Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 11/27] fs: fix " Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 12/27] jbd2: " Mauro Carvalho Chehab
2020-11-20 3:38 ` Theodore Y. Ts'o
2020-11-16 10:18 ` [PATCH v4 13/27] pstore/zone: fix a kernel-doc markup Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 14/27] completion: fix kernel-doc markups Mauro Carvalho Chehab
2020-11-16 11:36 ` Peter Zijlstra
2020-11-16 10:18 ` [PATCH v4 15/27] firmware: stratix10-svc: " Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 16/27] connector: fix a kernel-doc markup Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 17/27] lib/crc7: " Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 18/27] hrtimer: fix kernel-doc markups Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 19/27] genirq: " Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 20/27] list: fix a typo at the kernel-doc markup Mauro Carvalho Chehab
2020-11-16 19:57 ` Paul E. McKenney
2020-11-16 10:18 ` [PATCH v4 21/27] memblock: fix kernel-doc markups Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 22/27] w1: fix a kernel-doc markup Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 23/27] resource: fix kernel-doc markups Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 24/27] shed: fix kernel-doc markup Mauro Carvalho Chehab
2020-11-16 12:34 ` Vincent Guittot
2020-11-16 10:18 ` [PATCH v4 25/27] mm: fix kernel-doc markups Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 26/27] selftests: kselftest_harness.h: partially " Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 27/27] scripts: kernel-doc: validate kernel-doc markup with the actual names Mauro Carvalho Chehab
2020-11-16 15:06 ` kernel test robot
2020-11-16 15:42 ` kernel test robot
2020-11-16 15:51 ` kernel test robot
2020-11-17 22:19 ` [PATCH v4 00/27]Fix several bad kernel-doc markups Jakub Kicinski
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=20201201123921.2009cbea@coco.lan \
--to=mchehab+huawei@kernel.org \
--cc=bvanassche@acm.org \
--cc=chuck.lever@oracle.com \
--cc=corbet@lwn.net \
--cc=danitg@mellanox.com \
--cc=dennis.dalessandro@cornelisnetworks.com \
--cc=divya.indi@oracle.com \
--cc=dledford@redhat.com \
--cc=galpress@amazon.com \
--cc=gustavoars@kernel.org \
--cc=haakon.bugge@oracle.com \
--cc=jgg@nvidia.com \
--cc=leon@kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-rdma@vger.kernel.org \
--cc=maorg@mellanox.com \
--cc=mgurtovoy@nvidia.com \
--cc=mike.marciniszyn@cornelisnetworks.com \
--cc=monis@mellanox.com \
--cc=ogerlitz@mellanox.com \
--cc=parav@mellanox.com \
--cc=sagi@grimberg.me \
--cc=target-devel@vger.kernel.org \
--cc=ubraun@linux.ibm.com \
--cc=wangxi11@huawei.com \
--cc=yaminf@mellanox.com \
/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).