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
netchild at FreeBSD.org
Sat May 27 02:38:10 PDT 2006
Quoting "Poul-Henning Kamp" <phk at phk.freebsd.dk> (Sat, 27 May 2006 10:57:04 +0200):
> In message <20060527104539.1f4c0738 at 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
> 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
> 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
You got already a response for this, but wait for my example which will
hopefully address your concerns.
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
More information about the cvs-src