manuals/reference/libanjuta/README.inline-doc

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