[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Library/function documentation

From: Carl Fredrik Hammar
Subject: Re: Library/function documentation
Date: Sun, 16 Dec 2007 15:10:04 +0100
User-agent: Gnus/5.11 (Gnus v5.11) Emacs/22.1 (gnu/linux)


> 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


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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]