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 ...

[Alexander Leidinger]

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
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