"Fossies" - the Fresh Open Source Software Archive

Member "gimp-2.10.28/devel-docs/README.gtkdoc" (14 Sep 2021, 4777 Bytes) of package /linux/misc/gimp-2.10.28.tar.bz2:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 Developers documentation using gtk-doc
    2 --------------------------------------
    3 
    4 The goal is to provide useful source documentation. Right now this is
    5 limited to libgimp since that is the part that is used by third-party
    6 coders (plug-in developers). Other parts of the code may follow later,
    7 but not before libgimp is properly documented.
    8 
    9 
   10 Principle
   11 ---------
   12 
   13 The documentation is extracted out of the source using gtk-doc (see
   14 http://www.gtk.org/gtk-doc/). We use a combination of comment blocks
   15 embedded into the source and additional information added manually
   16 into SGML template files.
   17 
   18 
   19 Requirements
   20 ------------
   21 
   22 GIMP release tarballs contain a complete set of precompiled HTML files
   23 as well as DocBook XML files to create other formats. You only need
   24 gtk-doc if you want to work on the documentation itself.  In that case
   25 you will need the following utilities:
   26 
   27 Perl v5 - Most of the scripts used are written in Perl.
   28 
   29 libxslt & libxml2 (version >= 2.3.6)
   30     This is used to convert the XML templates to HTML.
   31     http://xmlsoft.org/
   32 
   33 DocBook XML DTD v4.1.2
   34     http://www.docbook.org/
   35 
   36 gtk-doc (version >= 1.0)
   37     This package automatically generates DocBook documentation from
   38     source and is able to convert it into HTML (and other formats).
   39     ftp://ftp.gtk.org/pub/gtk-doc/
   40 
   41 
   42 You need to have all this properly setup. This includes the
   43 availability of an XML catalog (/etc/xml/catalog) that tells the
   44 XSLT processor where to look for locally installed DTDs. If that
   45 file is missing, the XSLT processor will try to access the DTDs
   46 online which will either fail or take forever. For this reason,
   47 the docs are not built by default. If you think you have a working
   48 setup, pass '--enable-gtk-doc' to configure.
   49 
   50 
   51 How it works
   52 ------------
   53 
   54 The following lines will only give you hints about how our system
   55 works. You should have understood the principles of gtk-doc before you
   56 touch it.
   57 
   58 The system is already set up, so unless there are substantial changes
   59 to the source e.g. new files were added, functions were added, renamed
   60 or removed or parameters changed, there is no need to touch the
   61 Makefile or any other files in the toplevel directory.
   62 
   63 In most cases you will work on the documentation by adding or editing
   64 comment blocks in the C source and by editing the template XML files
   65 in the tmpl directory.
   66 
   67 After you've done any changes to the documentation, running 'make'
   68 should rebuild the documentation. This will however only work if
   69 configure was called with the option '--enable-gtk-doc' and gtk-doc
   70 was successfully found. If everything was set up correctly, running
   71 'make' should do the trick and generate the XML and HTML files for
   72 you. Since the dependencies are not perfect, you sometimes need to
   73 call 'make clean; make' to force regeneration.
   74 
   75 
   76 How to write proper gtk-doc comments
   77 ------------------------------------
   78 
   79 Here are some hints on writing proper gtk-doc comments. They are based
   80 on the gtk-doc documentation which comes with the gtk-doc source tree:
   81 
   82 These are the comment blocks used in GIMP source files to document
   83 functions (and macros, signals and properties, if you want).
   84 
   85 /**
   86  * function_name:
   87  * @par1:  description of parameter 1. These can extend over more than
   88  *         one line.
   89  * @par2:  description of parameter 2
   90  *
   91  * The function description goes here. You can use @par1 to refer to
   92  * parameters so that they are highlighted in the output. You can also
   93  * use %constant for constants, function_name2() for functions and
   94  * #GtkWidget for links to other declarations (which may be documented
   95  * elsewhere).
   96  * 
   97  * Return value: an integer.
   98  **/
   99 
  100 The block starts with '/**'.
  101 Each line starts with ' * '.
  102 
  103 The second line is the function name, followed by a ':'. In order to
  104 document signals in inline comments, use a name of the form
  105 class::signal, e.g. GtkWidget::notify-child. For properties, use a
  106 name of the form class:property, e.g. GtkAlignment:top-padding. Note
  107 that gtk-doc expects the signal and property names to be spelled with
  108 hyphens, not underlines.
  109 
  110 Following the function name are the parameters, e.g. '@par1:' above.
  111 
  112 A blank line MUST be used to separate parameter descriptions from the
  113 main description (otherwise it is assumed to be a continuation of the
  114 parameter description.)
  115 
  116 After the main description is a 'Return value:' line to describe the
  117 returned value of the function (if it is not void).
  118 
  119 
  120 More information
  121 ----------------
  122 
  123 Using the system as described above, you can write documentation
  124 without any knowledge of DocBook XML, but when editing the templates
  125 you will sometimes want to do a little extra structuring or
  126 markup. The best source for information about DocBook seems to be
  127 "DocBook: The Definitive Guide" which is available online at
  128 http://www.docbook.org/tdg/html/.