Re: argument names in function declarations

[Thor Lancelot Simon <tls%panix.com@localhost>]

On Tue, Aug 25, 2009 at 01:02:11AM -0400, der Mouse wrote:
> 
> semantics for the identifiers in question.  And I see additional
> reasons to avoid them: system headers are not, in general, the right
> place to document call arguments, and, even if you _do_ want to
> document the arguments there, just a name is at best a memory-jogger,
> not real documentation.  If you want to document them in the header, I
> say, use comments; that's what they exist for.

I'd go further: I think we should, if this is really important, use
something like Doxygen/JavaDoc markup, and we should use it in the
source files, not the header files.

We have Doxygenated a large amount of NetBSD library and kernel code at
work and generally we've found that the usual Doxygen convention of doing
the markup in the header files is a bad one -- it separates the actual
code from the comments and makes it hard to see when they are changed so
that they diverge.  But one thing Doxygen outputs is a nice browseable
view of the source tree, so it's all linked back and forth and, in the
output, if you want the comments describing the function parameters as
you're browsing the header file, they're still at your fingertips.

-- 
Thor Lancelot Simon                                        
tls%rek.tjls.com@localhost
    "Even experienced UNIX users occasionally enter rm *.* at the UNIX
     prompt only to realize too late that they have removed the wrong
     segment of the directory structure." - Microsoft WSS whitepaper