Re: [RFC] [PATCH 1/2] cpusets: restructure the function update_cpumask() and update_nodemask()

[Randy Dunlap <rdunlap@xenotime.net>]

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?"