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>
* */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.
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
works. You should have understood the principles of gtk-doc before you
touch it.
@ -73,6 +72,50 @@ you. Since the dependencies are not perfect, you sometimes need to
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
----------------