Date: Sat, 27 May 2006 10:48:11 -0600 From: Scott Long <scottl@samsco.org> To: Poul-Henning Kamp <phk@phk.freebsd.dk> Cc: cvs-src@FreeBSD.org, src-committers@FreeBSD.org, Alexander Leidinger <netchild@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: <447882CB.8020003@samsco.org> In-Reply-To: <13817.1148720224@critter.freebsd.dk> References: <13817.1148720224@critter.freebsd.dk>
next in thread | previous in thread | raw e-mail | index | archive | help
Poul-Henning Kamp wrote: > 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. > > 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. > > So until somebody explicitly decides otherwise on a function by function > bases, all functions should either be excluded or marked internal > automatically. > All very good points. Unfortunately, the very nature of open source means that people will go treading into non-APIs if they think that it helps them solve a problem. I have a long list of 3rd party drivers that do exactly this; calling MD routines in order to grub around in the BIOS, hijacking CAM internals because the correct API wasn't clear, etc. Whether a non-API appears is doxygen or not is irrelevant, an industrious developer will find it anyways. Scott
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?447882CB.8020003>