Target-devel archive on lore.kernel.org
 help / color / Atom feed
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
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

  reply index

Thread overview: 6+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-11-16 10:17 [PATCH v4 00/27]Fix several bad " Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 07/27] IB: fix " 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-17 22:19 ` [PATCH v4 00/27]Fix several bad " 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

Target-devel archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/target-devel/0 target-devel/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 target-devel target-devel/ https://lore.kernel.org/target-devel \
		target-devel@vger.kernel.org
	public-inbox-index target-devel

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.target-devel


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git