linux-kernel - Re: [PATCH RFC v2] Documentation/infiniband: Add docs for rdma-helpers

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:	Mon, 18 May 2015 12:58:11 -0400
From:	Doug Ledford <dledford@...hat.com>
To:	Michael Wang <yun.wang@...fitbricks.com>
Cc:	Or Gerlitz <gerlitz.or@...il.com>,
	Roland Dreier <roland@...nel.org>,
	Sean Hefty <sean.hefty@...el.com>,
	Hal Rosenstock <hal@....mellanox.co.il>,
	"linux-rdma@...r.kernel.org" <linux-rdma@...r.kernel.org>,
	Linux Kernel <linux-kernel@...r.kernel.org>,
	linux-doc@...r.kernel.org, Or Gerlitz <ogerlitz@...lanox.com>,
	Ira Weiny <ira.weiny@...el.com>,
	Jason Gunthorpe <jgunthorpe@...idianresearch.com>
Subject: Re: [PATCH RFC v2] Documentation/infiniband: Add docs for
 rdma-helpers

On Mon, 2015-05-18 at 17:27 +0200, Michael Wang wrote:
> 
> On 05/18/2015 05:21 PM, Doug Ledford wrote:
> [snip]
> >>
> >> I'll put the highlights and changelog under '---' in next version, is it
> >> looks like this?
> > 
> > We're still missing Jason's feedback request though.  Specifically, he
> > pointed out that kdocs are usually not done in Documentation/*, they are
> > done in the .c files where the function is (or the .h file if the
> > function is an inline, which these all are).  So, you included some
> > limited documentation for each of these items in your original patches
> > that added them.  His request was that you put this expanded information
> > not in Documentation/infiniband where someone has to go looking for it,
> > but as part of the kdoc header for each of the various helpers in
> > ib_verbs.h itself.
> 
> I see :-) I've not work with the kdoc yet, not sure if there is any
> guidelines on how to write the header of inline func for kdoc?

It's an automated tool thing.  Any comment section that starts with /**
is automatically included as a kdoc.  Then there is an expected format
after that.  See Documentation/kernel-doc-nano-HOWTO.txt.

> > 
> > Just because I want to move this along versus waiting for another
> > respin, I'm going to copy and paste these into those locations and clean
> > up the changelog when I integrate this patch.
> 
> Got it, if there is anything I could help, please let me know ;-)

I'm sending the patch for review, please let me know if you are OK with
how I handled the attribution.

-- 
Doug Ledford <dledford@...hat.com>
              GPG KeyID: 0E572FDD


Download attachment "signature.asc" of type "application/pgp-signature" (820 bytes)