Re: comments with gtk-doc

[Malcolm Tredinnick <malcolm commsecure com au>]

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.

Cheers,
Malcolm