cvs commit: src/sys/doc/subsys Dependencies Doxyfile-cam Doxyfile-crypto Doxyfile-dev_pci Doxyfile-dev_sound Doxyfile-dev_usb Doxyfile-geom Doxyfile-i4b Doxyfile-kern Doxyfile-libkern Doxyfile-linux Doxyfile-net80211 ...

[Robert Watson]

On Sun, 28 May 2006, Alexander Leidinger wrote:

> Quoting gnn at FreeBSD.org (Sun, 28 May 2006 11:12:19 +0900):
>
>> Am I allowed to call this a tempest in a teacup?
>>
>> There, I just have.
>>
>> While I think that there have been some very good points made both ways, I 
>> believe that since the documentation will be generated only by people who 
>> are using the system, and will not appear on line, or in a manual, that we 
>> do not need to worry about this.  It is, IMHO, easier
>
> As Scott already said: it doesn't matter if it is made public or not. "The 
> bad guys"(TM) will use non-public functions regardless.

I think the bad guys concept is a red herring.  Not even having the source 
code matters for bad guys -- there's some darn evil code that runs on entirely 
closed source platforms and run-time patches kernels.  This code is by 
necessity very fragile, and the vendors of those closed source systems work 
hard to try and convince people to use published APIs, and add APIs to try and 
facilitate it.  Otherwise they risk one of the Evil Apps hitting the Critical 
Must Support List, and leaving them stuck for how to change the kernel in the 
future.

Presumably, what matters to us is making it clear what APIs (structures, etc) 
are intended for "external" use -- i.e., use that doesn't closely track 
internal development.  It's seeming to me more and more like we should 
consider Doxygen an "internal" use tool, label it as such, and not try to use 
it as documentation for developers programming to plug-in interfaces.

Robert N M Watson