Messages in this thread | | | Date | Thu, 29 May 2008 21:27:46 -0700 | From | Randy Dunlap <> | 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?"
| |