A GTK-Doc comment block can be constructed out of multiple parts that can
be combined to write different types of documentation.
See `GTK-Doc's documentation`_ to learn more about possible valid combinations.
Each part can be further divided into fields which are separated by `:` characters.

Possible parts and the fields they are constructed from look like the
following (optional fields are enclosed in square brackets):

.. code-block:: c
    /**
     * identifier_name: [annotations]
     * @parameter_name: [annotations:] [description]
     *
     * comment_block_description
     * tag_name: [annotations:] [description]
     */

    - There has to be exactly 1 `identifier` part on the first line of the
      comment block which consists of:
          * an `identifier_name` field
          * an optional `annotations` field
    - There can be 0 or more `parameter` parts following the `identifier` part,
      each consisting of:
          * a `parameter_name` field
          * an optional `annotations` field
          * an optional `description` field
    - There has to be exactly 1 empty line, which signals the end of the
      `parameter` parts (even if there where no parameters) and the beginning
      of the `comment block description` part.
    - There can be 0 or 1 `comment block description` parts following
      the `parameter` part.
    - There can be 0 or more `tag` parts following the
      `comment block description` part, each consisting of:
          * a `tag_name` field
          * an optional `annotations` field
          * an optional `description` field

Additionally, the following restrictions are in effect:

    - Parts and fields cannot span multiple lines, except for
      `parameter descriptions`, `tag descriptions` and the
      `comment block description` fields.
    - `tag descriptions` and `comment block description` fields can
      span multiple paragraphs, `parameter descriptions` fields can't.
    - Parts can optionally be separated by an empty line, except between
      the `parameter` parts and the `comment block description` part where
      an empty line is required (see above).

.. _GTK-Doc's documentation:
        http://developer.gnome.org/gtk-doc-manual/1.18/documenting.html.en