Re: Library/function documentation

[Carl Fredrik Hammar]

Hello!

> Hi,
>
> How do core developers go through Hurd servers/library or gnumach
> functions? Do you use etags/ctags?

Personally I use etags when browsing through code.

> Wouldn't it be useful for newbies if all functions can have comments
> to generate gtk-doc style documentation?
> http://library.gnome.org/devel/glib/unstable/index.html

Well most functions do have comments with short description already,
so you can use gtk-doc if you want a better overview of which
functions are available.

> It will be helpful to skim through a particular library with this
> documentation, and then look at each function in detail? Or, do you
> prefer doxygen over gtk-doc style?
>
> Or do you recommend to use cross-referencing with GLOBAL?
> http://www.htu.tugraz.at/~past/hurd/global/

Making comments more detailed has been discussed before (see [1].)
The consensus seem to be that proper overview documentation belongs in
info pages were it can be handled more appropriate.  And that
functions should be written in a clear manner so that they document
themselves.  Any in-code comments should be a very short summeries.

With this said, the info pages are currently very lacking and needs to
be updated.

> Appreciate any inputs,
>
> Thanks,
>
> SK

Regards,
  Fredrik

[1] http://lists.gnu.org/archive/html/bug-hurd/2007-07/msg00047.html