linux-kernel - Re: [osd-dev] [PATCH 04/18] libosd: OSDv1 preliminary implementation

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]

Message-ID: <4917C89A.70909@oracle.com>
Date:	Sun, 09 Nov 2008 21:37:30 -0800
From:	Randy Dunlap <randy.dunlap@...cle.com>
To:	Boaz Harrosh <bharrosh@...asas.com>
CC:	Sam Ravnborg <sam@...nborg.org>,
	open-osd development <osd-dev@...n-osd.org>,
	Mike Christie <michaelc@...wisc.edu>,
	linux-scsi <linux-scsi@...r.kernel.org>,
	Jeff Garzik <jeff@...zik.org>, Sami.Iren@...gate.com,
	linux-kernel <linux-kernel@...r.kernel.org>,
	James Bottomley <James.Bottomley@...senpartnership.com>,
	Andrew Morton <akpm@...ux-foundation.org>,
	Randy Dunlap <randy.dunlap@...cle.com>
Subject: Re: [osd-dev] [PATCH 04/18] libosd: OSDv1 preliminary implementation

Boaz Harrosh wrote:
> Boaz Harrosh wrote:
>> Sam Ravnborg wrote:
>>>> +EXPORT_SYMBOL(osd_dev_init);
>>> kernel-doc comments for all exported funtions / variables.
>>>
>> I have some kernel-doc comments of exported functions in the Header
>> file. I have not yet finished all of them. (Laziness on my part).
>>
>> Are kernel-doc comments in headers a big NO-NO. I like it this way,
>> so when I have to learn a new Library all the information
>> I need to know is in the header. Also the header is a much better place
>> when you do programing by shopping, that is you don't know what you need
>> and you look for what's available.
>>
>> Thanks
>> Boaz
> 
> Sam please comment if kernel-doc comments are OK in headers

Hi,

The de facto standard for kernel-doc comments is at the implementation site,
which means normally in .c files, except for macros or inline functions.

Sure you can find some exceptions to that.  And there is no hard requirement
in Documentation/kernel-doc-nano-HOWTO.txt.

IMO the biggest concern is making sure that the (kernel-doc) comments are
updated when the function implementation changes (if updates are needed).
Where would be the best place for this to be more likely to happen?
Usually at the function implementation, I would say.

~Randy


-- 
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/