[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) |
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
Re: Library/function documentation, olafBuddenhagen, 2007/12/18