Skip site navigation (1)Skip section navigation (2)
Date:      Sat, 27 May 2006 19:07:51 +0200
From:      Alexander Leidinger <netchild@FreeBSD.org>
To:        "Ben Kaduk" <minimarmot@gmail.com>
Cc:        cvs-src@FreeBSD.org, Poul-Henning Kamp <phk@phk.freebsd.dk>, src-committers@FreeBSD.org, cvs-all@FreeBSD.org
Subject:   Re: 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 ...
Message-ID:  <20060527190751.3628e119@Magellan.Leidinger.net>
In-Reply-To: <47d0403c0605270827n665ccd5ved9ba0effccf248b@mail.gmail.com>
References:  <20060527104539.1f4c0738@Magellan.Leidinger.net> <13817.1148720224@critter.freebsd.dk> <20060527123344.355119b8@Magellan.Leidinger.net> <47d0403c0605270827n665ccd5ved9ba0effccf248b@mail.gmail.com>

next in thread | previous in thread | raw e-mail | index | archive | help
Quoting "Ben Kaduk" <minimarmot@gmail.com> (Sat, 27 May 2006 10:27:05 -0500):

> > At http://www.leidinger.net/FreeBSD/doxygen_notreviewed.png I have a
> > screenshot of the the index page of the HTML documentation. It shows
> > the following text in a very prominent position:
> > ---snip---
> 
> I have a few comments about the wording of this disclaimer.
> 
> 
> > IMPORTANT: This API documentation may contain functions which are
> > either public or for internal use only. Since we have not reviewed
> 
> Do you mean "not public" here?

No. I want to say that we not only have public function there, but also
functions for internal use only. I don't know if this is needed. It's
also ok for me if someone changes this disclaimer completely.

> > every part of the documentation yet, some internal functions are not
> > marked as such. Until we finished reviewing the API documentation and
> 
> finish

Fixed.

> > augmented functions for internal use with appropriate comments you have
> > to take this into account. In case you want to use a function of this
> 
> documentation and add appropriate comments to functions which are only
> for internal use, you should take this into account.

Fixed.

> > kernel subsystem in another kernel subsystem you better search for
> 
> you should search

Fixed.

> > 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 to break something.
> 
> you risk breaking something.

Fixed.

Thanks.

> Also, I am not certain that we should disclaim against "breaking
> something," but I can not think of a better admonition at the moment
> 
> Thanks for putting in the work to generate Doxygen documentation.  I
> am just starting to read the kernel code, and I feel that the call
> graphs, etc. that it generates will be quite helpful.

And the HTML version is even better to browse than the PDF version I
have on my website.

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



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20060527190751.3628e119>