Re: comments with gtk-doc

[Damon Chaplin <damon kendo fsnet co uk>]

On Mon, 2002-10-07 at 02:57, Malcolm Tredinnick wrote:
> On Sun, Oct 06, 2002 at 07:58:40PM -0500, Jacob Perkins wrote:
> > I want to comment a gnome app's source files, but where should the
> > function comments go, header or source?  Or should the same comments go
> > in both?  If not both, then what kind of comments should go in the other
> > file?
> 
> Firstly I would recommend reading the various files in the doc/
> directory of the gtk-doc source distribution. They will give you a good
> start on where to put things.
> 
> Secondly, to give some general answers to your questions:
> 	- Documentation of functions generally goes before the function
> 	  body in the source file.
> 
> 	- Documentation of structures and enums will usually go in the
> 	  header file at the point where the struct or enum is defined.
> 
> 	- You can always put documentation in the corresponding .tmpl
> 	  file (in the tmpl/ directory under where the docs are built).
> 	  This is useful if, for example, you are wanting to document
> 	  the parameters to a macro (since gtk-doc will not
> 	  automatically extract these parameters).
> 
> The best way to start out using gtk-doc is to use an existing package as
> a reference. I used gtk+ and glib a fair bit when I was starting out
> doing API documentation. Since then, I have used all of the techniques I
> mentioned above in libgnome and libgnomeui, so you might want to poke
> around in those modules to see cases where each technique is useful.
> 
> My "advice on a postcard" version: start out documenting all of the
> publically available functions by putting comments just before the
> function in the source file. Then work out what is left and fill those
> in  in the header files and template files.

Also if you use emacs see gtk-doc/tools/gtk-doc.el.
You can then type C-x 4 h and it will insert an empty comment before the
function you are in, with all the arguments ready to be documented. Very
handy!

Damon