doc/gnome.txt

   1 Note
   2 ====
   3
   4 There is now a user manual which can be read using yelp and can be found under
   5 'development'. Please refer to this documentation for up-to-date information.
   6
   7
   8 HowTo
   9 =====
  10
  11 These are the comment blocks used in Gnome source files to document
  12 functions (and macros, signals and properties, if you want).
  13
  14 /**
  15  * function_name:
  16  * @par1:  description of parameter 1. These can extend over more than
  17  * one line.
  18  * @par2:  description of parameter 2
  19  *
  20  * The function description goes here. You can use @par1 to refer to parameters
  21  * so that they are highlighted in the output. You can also use %constant
  22  * for constants, function_name2() for functions and #GtkWidget for links to
  23  * other declarations (which may be documented elsewhere).
  24  *
  25  * Returns: an integer.
  26  */
  27
  28 The block starts with '/**'.
  29 Each line starts with ' * '.
  30
  31 The second line is the function name, optionally followed by a ':'. In
  32 order to document signals in inline comments, use a name of the form
  33 class::signal, e.g. GtkWidget::notify-child. For properties, use a
  34 name of the form class:property, e.g. GtkAlignment:top-padding. Note
  35 that gtk-doc expects the signal and property names to be spelled with
  36 hyphens, not underlines.
  37
  38 Following the function name are the parameters, e.g. '@par1:' above.
  39
  40 A blank line MUST be used to separate parameter descriptions from the main
  41 description (otherwise it is assumed to be a continuation of the parameter
  42 description.)
  43
  44 After the main description is a 'Returns:' line to describe the
  45 returned value of the function (if it is not void).
  46
  47 Text inside the descriptions can use these special characters (they
  48 will be expanded into appropriate DocBook tags):
  49
  50    @name   a parameter.
  51    %name   a constant.
  52    name()  reference to a function, or a macro which works like a function
  53            (this will be turned into a hypertext link if the function is
  54            documented anywhere).
  55    #name   reference to any other type of declaration, e.g. a struct, enum,
  56            union, or macro (this will also be turned into a link if possible).
  57
  58 To avoid problems, the characters '<', '>' and '&' in the descriptions are
  59 converted into the SGML entities &lt; &gt; and &amp;.
  60 This means that you can't use Docbook SGML tags, unless specify the --sgml-mode
  61 option for gtkdoc-mkdb, which suppresses the escaping of '<', '>' and
  62 '&' and allows Docbook markup in inline comments.
  63
  64 If you are using markup in inline comments, you must be careful to to
  65 not run into problems with the automatic splitting of the comment in
  66 paragraphs at empty lines. A line counts as empty for this purpose, if
  67 it is empty after the removal of the initial ' * ' prefix. Thus you
  68 can work around this problem by adding some trailing whitespace to
  69 lines which should appear as empty, but not end a paragraph. This is
  70 especially relevant in code examples, which often contain empty lines.
  71
  72 Some more hints regarding examples: Hyperlinks in the formatted examples
  73 are confusing, therefore you should suppress the gtk-doc markup by using
  74 function(<!-- -->) instead of function(). Use character entities to refer
  75 to the characters %, &, < or #, e.g.
  76
  77    if (a < b && verbose)
  78       printf ("bla %s %#x", bla, a);
  79
  80 would become
  81
  82    if (a &lt; b &amp;&amp; verbose)
  83       printf ("bla &percnt;s &percnt;&num;x", bla, a);
  84