linux-kernel - Re: [RFC] [PATCH 1/2] cpusets: restructure the function update_cpumask() and update

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:	Thu, 29 May 2008 21:27:46 -0700
From:	Randy Dunlap <rdunlap@...otime.net>
To:	Paul Jackson <pj@....com>
Cc:	miaox@...fujitsu.com, akpm@...ux-foundation.org,
	linux-kernel@...r.kernel.org, menage@...gle.com
Subject: Re: [RFC] [PATCH 1/2] cpusets: restructure the function
 update_cpumask() and update_nodemask()

On Thu, 29 May 2008 22:57:08 -0500 Paul Jackson wrote:

> Randy wrote:
> > For static functions, it's up to the maintainer/developer whether to do that
> > or not.  But if the functions already have kernel-doc, there's no strong
> > reason to remove it.  And these look good currently, so I see no
> > good reason to change them.
> 
> Ok - thank-you for the explanation.
> 
> I had this vague recollection that kernel-doc was just for non-static
> functions, so when I saw Miao put kernel-doc comments on a static
> routine, I looked around to see if that was normal.
> 
> I didn't see mention of static functions in kernel-doc-nano-HOWTO.txt,

There's no restriction to static or non-static.

> and in a brief survey, didn't happen to see any static functions with
> kernel-doc comments.  However my survey was so brief I even missed five

There are plenty of them.

> such functions in the file I maintain, kernel/cpuset.c.  So from that
> I came to the (apparently flawed) conclusion that it didn't make sense
> to kernel-doc static functions, and so advised Miao.
> 
> I don't quite see what purpose kernel-doc would have for static
> functions, and am still concerned that such would (mildly) clutter the
> presentation of the externally visible cpuset functions in which those
> who just use cpusets would be interested.

Well, they won't clutter the generated kernel-doc docbook output unless
you/we/someone requests that both non-static and static functions be listed
in it.  (more on that below)

> It remains, of course, important to have good documentation of
> functions, static or not, but I would expect developers working inside
> the kernel/cpuset.c file to look for documentation of functions
> static to that file within the code and comments of that file, not in
> kernel-doc.

kernel-doc is in comments.  Just specially formatted ones.

> However I am just the cpuset maintainer, not a kernel-doc expert.
> 
> I remain inclined toward removing the kernel-doc markings on static
> functions in kernel/cpuset.c, but if you wish, Randy, to make a renewed
> appeal for me not to do so, I will happily honor that appeal.
> 
> Life is good either way when we are discussing how to annotate
> documentation, rather than lamenting its absence.

a.  I looked at those 5 functions.  They should be documented, whether
it's done with kernel-doc or some other way.  I don't see why there would
be a problem with using kernel-doc instead of something else.

b.  Yes, any documentation along these lines is better than none.  We agree.

> If you, Randy, felt inclined to explain the value of kernel-doc comments
> on file static functions in kernel-doc-nano-HOWTO.txt, that might be
> valuable for the next person who travels this path.

It might need a little tweaking.  Basically what is already there says:

"""
!E<filename> is replaced by the documentation, in <filename>, for
functions that are exported using EXPORT_SYMBOL: the function list is
collected from files listed in Documentation/DocBook/Makefile.

!I<filename> is replaced by the documentation for functions that are
_not_ exported using EXPORT_SYMBOL.
"""

so if a docbook (like one generated from Documentation/DocBook/kernel-api.tmpl)
uses both of these:
!Ekernel/cpuset.c
!Ikernel/cpuset.c

then that docbook will contain both exported functions and non-exported ones.
To produce a docbook with only exported symbols, use only
!Ekernel/cpuset.c

The nuance here is the difference in exported/non-exported vs. non-static/static.

> Thank-you.

Same to you, sir.

Does that help?  your understanding of kernel-doc or your decision?

---
~Randy
"He closes his eyes and drops the goggles.  You can't get hurt
by looking at a bitmap.  Or can you?"
--
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/