Date: Sat, 27 May 2006 10:57:04 +0200 From: "Poul-Henning Kamp" <phk@phk.freebsd.dk> To: Alexander Leidinger <netchild@FreeBSD.org> 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: <13817.1148720224@critter.freebsd.dk> In-Reply-To: Your message of "Sat, 27 May 2006 10:45:39 %2B0200." <20060527104539.1f4c0738@Magellan.Leidinger.net>
next in thread | previous in thread | raw e-mail | index | archive | help
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. -- Poul-Henning Kamp | UNIX since Zilog Zeus 3.20 phk@FreeBSD.ORG | TCP/IP since RFC 956 FreeBSD committer | BSD since 4.3-tahoe Never attribute to malice what can adequately be explained by incompetence.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?13817.1148720224>