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 ...

[Alexander Leidinger]

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.

And since generating all docs isn't fast (I need several hours to
generate the current ones on my Athlon XP 2200+), it would be nice to
have them online somewhere.

I already have a disclaimer file (attached), I just wait for the "when
this text is included it's ok for me" from those people which worry
about the misuse of the docs.

> to go through and mark things up AFTER we have them visible and so
> visibility should be the first goal.  Since there is, as far as I
> know, no other or better tool for this job I suggest we go with what
> we have and begin to mark things correctly now.  Having everything by
> default internal, IMHO, leaves us just where we were before, lots of
> twisty little APIs all undocumented.
> 
> My $0.02.

I agree.

Bye,
Alexander.

-- 
Selling GoodYear Eagle F1 235/40ZR18, 2x 4mm + 2x 5mm, ~150 EUR
you have to pick it up between Germany/Saarland and Luxembourg/Capellen
http://www.Leidinger.net    Alexander @ Leidinger.net: PGP ID = B0063FE7
http://www.FreeBSD.org       netchild @ FreeBSD.org  : PGP ID = 72077137
-------------- next part --------------
/** @mainpage
 * <b>IMPORTANT:</b> This API documentation may contain both functions which
 * are public and functions that are for internal use only. Since we have not
 * reviewed every part of the documentation yet, <i>some internal functions
 * are not marked as such</i>. Until we finish reviewing the API documentation
 * and add appropriate comments to functions which are only for internal use,
 * you should take this into account. In case you want to use a function of
 * this kernel subsystem in another kernel subsystem you should search for
 * precedence of use outside this subsystem. If the function is not used
 * outside this subsystem you should ask on the mailinglists about it, else
 * you risk breaking something.
 */