Date: Sat, 27 May 2006 11:37:43 +0200 From: Alexander Leidinger <netchild@FreeBSD.org> To: "Poul-Henning Kamp" <phk@phk.freebsd.dk> Cc: cvs-src@FreeBSD.org, 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: <20060527113743.03b5a263@Magellan.Leidinger.net> In-Reply-To: <13817.1148720224@critter.freebsd.dk> References: <20060527104539.1f4c0738@Magellan.Leidinger.net> <13817.1148720224@critter.freebsd.dk>
next in thread | previous in thread | raw e-mail | index | archive | help
Quoting "Poul-Henning Kamp" <phk@phk.freebsd.dk> (Sat, 27 May 2006 10:57:04 +0200): > In message <20060527104539.1f4c0738@Magellan.Leidinger.net>, Alexander Leidinger writes: > > >> Can we agree that no functions will be put into publicized documentation > >> until somebody has considered if the function actually is a public > >> function or not ? > > > >Does this mean you want to have everything marked as "@internal" by > >default? I don't think there's a switch which does this, so you would > >have to mark every function with @internal by hand. > > Yes, until somebody decides otherwise. > > We do not want all non-static kernel functions become published APIs > by default. > > >What about adding a comment to the pages which tells everyone that we > >are working on this documentation and so far we haven't reviewed every > >function and decided if it is an internal one or not. > > I don't think the documentation should be published before it reaches > a certain level of quality. "Not including random stuff" would be > a sensible first goal-post. I prepare something regarding this and come back to you later with an example. > Rather than aim to enable this for the entire kernel and create > showel-ware documentation of no value, why don't you start with one > subsystem which is currently being worked on and make a usable > documentation of that subsystem ? > > >And the most important point is: what does it mean if a function is > >internal? > > It means that the function should not be called outside the subsystem > it is part of. > > To take an example: g_run_events() is not static, but it should be > called only from one single place and there will never be a reason > to call it from anywhere else. > > There is no automatic way to make this determination, you need somebody > to look at each and every function to decide it. That's the same way I think about @internal. > So until somebody explicitly decides otherwise on a function by function > bases, all functions should either be excluded or marked internal > automatically. You got already a response for this, but wait for my example which will hopefully address your concerns. 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?20060527113743.03b5a263>