dnrops
/
gimp
mirror of https://github.com/GNOME/gimp.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

added some information on how to write proper gtk-doc comments. 

2003-11-09  Sven Neumann  <sven@gimp.org>

	* README.gtkdoc: added some information on how to write proper
	gtk-doc comments.
This commit is contained in:
Sven Neumann 2003-11-09 14:11:28 +00:00 committed by Sven Neumann
parent 47c862f353
commit 2ac2308a7e
2 changed files with 51 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
devel-docs/ChangeLog
View File

@ -1,3 +1,8 @@
2003-11-09 Sven Neumann <sven@gimp.org>
* README.gtkdoc: added some information on how to write proper
gtk-doc comments.
2003-11-08 Sven Neumann <sven@gimp.org> 2003-11-08 Sven Neumann <sven@gimp.org>
* */version.xml.in: renamed to version.in. * */version.xml.in: renamed to version.in.

49
devel-docs/README.gtkdoc
View File

@ -47,10 +47,9 @@ the docs are not built by default. If you think you have a working
setup, pass '--enable-gtk-doc' to configure. setup, pass '--enable-gtk-doc' to configure.
HOWTO How it works
----- ------------
Carefully read the README that comes with gtk-doc. Then read it again!
The following lines will only give you hints about how our system The following lines will only give you hints about how our system
works. You should have understood the principles of gtk-doc before you works. You should have understood the principles of gtk-doc before you
touch it. touch it.
@ -73,6 +72,50 @@ you. Since the dependencies are not perfect, you sometimes need to
call 'make clean; make' to force regeneration. call 'make clean; make' to force regeneration.
How to write proper gtk-doc comments
------------------------------------
Here are some hints on writing proper gtk-doc comments. They are based
on the gtk-doc documentation which comes with the gtk-doc source tree:
These are the comment blocks used in GIMP source files to document
functions (and macros, signals and properties, if you want).
/**
* function_name:
* @par1: description of parameter 1. These can extend over more than
* one line.
* @par2: description of parameter 2
*
* The function description goes here. You can use @par1 to refer to
* parameters so that they are highlighted in the output. You can also
* use %constant for constants, function_name2() for functions and
* #GtkWidget for links to other declarations (which may be documented
* elsewhere).
*
* Return value: an integer.
**/
The block starts with '/**'.
Each line starts with ' * '.
The second line is the function name, followed by a ':'. In order to
document signals in inline comments, use a name of the form
class::signal, e.g. GtkWidget::notify-child. For properties, use a
name of the form class:property, e.g. GtkAlignment:top-padding. Note
that gtk-doc expects the signal and property names to be spelled with
hyphens, not underlines.
Following the function name are the parameters, e.g. '@par1:' above.
A blank line MUST be used to separate parameter descriptions from the
main description (otherwise it is assumed to be a continuation of the
parameter description.)
After the main description is a 'Return value:' line to describe the
returned value of the function (if it is not void).
More information More information
---------------- ----------------