~ubuntu-branches/ubuntu/utopic/gtk-doc/utopic

<para>First copy the <filename>Makefile.am</filename> from the <filename class="directory">examples</filename> subdirectory of the GTK-Doc sources to your project's API documentation directory (<filename class="directory">./docs/reference/<replaceable>package</replaceable></filename>). If you have multiple doc-packages, repeat this for each one.</para>

423

<para>

424

First copy the <filename>Makefile.am</filename> from the

425

<filename class="directory">examples</filename> sub directory of the

426

<ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink>

427

to your project's API documentation directory (

428

<filename class="directory">./docs/reference/<package></filename>).

429

A local copy should be available under e.g.

430

<filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.

431

If you have multiple doc-packages repeat this for each one.

432

</para>

418

433

419

434

<para>

420

435

The next step is to edit the settings inside the <filename>Makefile.am</filename>.

427

442

428

443

429

444

430

<para>

431

You may also want to enable GTK-Doc for the distcheck make target. Just

432

add the one line shown in the next example to your top-level

433

<filename>Makefile.am</filename>:

434

</para>

435

436

<para>

437

<example><title>Enable GTK-Doc during make distcheck</title>

438

439

<![CDATA[

440

DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc

441

]]>

442

</programlisting>

443

</example>

444

</para>

445

446

445

</sect1>

447

446

448

447

687

686

</listitem>

688

687

689

688

<para>

690

Use #Struct.field to refer to a field inside a structure.

689

Use #Struct.field to refer to a field inside a structure and

690

#GObjectClass.foo_bar() to refer to a vmethod.

691

</para>

692

</listitem>

693

</itemizedlist>

694

</para>

695

696

<tip>

697

<para>

697

<para>

698

If you need to use the special characters '<', '>', '()', '@',

699

'%', or '#' in your documentation without GTK-Doc changing them you

700

can use the XML entities "&lt;", "&gt;", "&lpar;",

701

"&rpar;", "&commat;", "&percnt;" and "&num;"

702

respectively or escape them with a backslash '\'.

703

</para>

703

</para>

704

</tip>

705

706

<para>

707

DocBook can do more than just links. One can also have lists, tables and

708

examples. To enable the usage of docbook SGML/XML tags inside

709

doc-comments you need to have <option>--xml-mode</option> or

707

DocBook can do more than just links. One can also have lists,

708

examples, headings, and images. As of version 1.20, the

709

preferred way is to use a subset of the basic text formatting

710

syntax called

711

<ulink url="http://daringfireball.net/projects/markdown/">Markdown</ulink>.

712

On older GTK-Doc versions any documentation that includes

713

Markdown will be rendered as is. For example, list items will

714

appear as lines starting with a dash.

715

</para>

716

717

<para>

718

In older GTK-Doc releases, if you need support for additional

719

formatting, you would need to enable the usage of docbook

720

SGML/XML tags inside doc-comments by

721

putting <option>--xml-mode</option> or

710

722

<option>--sgml-mode</option> in the variable

711

723

<symbol>MKDB_OPTIONS</symbol> inside <filename>Makefile.am</filename>.

712

724

</para>

713

725

714

726

<para>

715

Since GTK-Doc-1.18 the tool supports a subset or the

716

<ulink url="http://daringfireball.net/projects/markdown/">markdown language</ulink>.

717

One can use it for sub-headings and simple itemized lists. On older

718

GTK-Doc versions the content will be rendered as it (the list items will

719

appear in one line separated by dashes).

720

<example><title>GTK-Doc comment block using markdown</title>

727

<example><title>GTK-Doc comment block using Markdown</title>

721

728

722

729

<![CDATA[

723

730

/**

724

731

* identifier:

725

732

726

* documentation ...

727

728

* # Sub heading #

733

* documentation paragraph ...

734

735

* # Sub Heading #

736

737

* ## Second Sub Heading

738

739

* # Sub Heading With a Link Anchor # {#heading-two}

729

740

730

741

* more documentation:

742

731

743

* - list item 1

744

745

* Paragraph inside a list item.

746

732

747

* - list item 2

733

748

734

* Even more docs.

749

* 1. numbered list item

750

751

* 2. another numbered list item

752

753

* Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/)

754

755

* ![an inline image][plot-result.png]

756

757

* [A link to the heading anchor above][heading-two]

758

759

* A C-language example:

760

* |[

761

* GtkWidget *label = gtk_label_new ("Gorgeous!");

762

* ]|

735

763

736

764

]]>

737

765

</programlisting>

738

766

</example>

739

767

</para>

740

768

769

<para>

770

More examples of what markdown tags are supported can be found in the

771

<ulink url="https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown">GTK+ Documentation Markdown Syntax Reference</ulink>.

772

</para>

773

741

774

<tip>

742

775

<para>

743

776

As already mentioned earlier GTK-Doc is for documenting public API. Thus

1552

1585

<filename><package>.interfaces.txt</filename>,

1553

1586

<filename><package>.prerequisites.txt</filename> and

1554

1587

<filename><package>.signals.txt</filename>. If there are missing

1555

symbols in any of those, one can ask gtkdoc to keep the intermediate scanner

1556

file for further analysis, by running it as

1588

symbols in any of those, one can ask GTK-Doc to keep the intermediate

1589

scanner file for further analysis, by running it as

1557

1590

<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.

1558

1591

</para>

1559

1592

</chapter>

1593

1594

1595

<title>Modernizing the documentation</title>

1596

1597

<para>

1598

GTK-Doc has been around for quite some time. In this section we list new

1599

features together with the version since when it is available.

1600

</para>

1601

1602

1603

1604

1605

<para>

1606

When using xml instead of sgml, one can actually name the master

1607

document <filename><package>-docs.xml</filename>.

1608

</para>

1609

1610

<para>

1611

This version supports <option>SCAN_OPTIONS=--rebuild-sections</option>

1612

in <filename>Makefile.am</filename>. When this is enabled, the

1613

<filename><package>-sections.txt</filename> is autogenerated and

1614

can be removed from the vcs. This only works nicely for projects that

1615

have a very regular structure (e.g. each .{c,h} pair will create new

1616

section). If one organize a project close to that updating a manually

1617

maintained section file can be as simple as running

1618

<code>meld <package>-decl-list.txt <package>-sections.txt</code>.

1619

</para>

1620

1621

<para>

1622

Version 1.8 already introduced the syntax for documenting sections in

1623

the sources instead of the separate files under <filename class="directory">tmpl</filename>.

1624

This version adds options to switch the whole doc module to not use the

1625

extra tmpl build step at all, by using <option>--flavour no-tmpl</option>

1626

in <filename>configure.ac</filename>.

1627

</para>

1628

</sect1>

1629

1630

1631

1632

1633

<para>

1634

This version supports <option>SCAN_OPTIONS=--rebuild-types</option> in

1635

<filename>Makefile.am</filename>. When this is enabled, the

1636

<filename><package>.types</filename> is autogenerated and can be

1637

removed from the vcs. When using this feature it is important to also

1638

setup the <varname>IGNORE_HFILES</varname> in

1639

<filename>Makefile.am</filename> for code that is build conditionally.

1640

</para>

1641

</sect1>

1642

1643

1644

1645

1646

<para>

1647

This version includes a new tool called gtkdoc-check. This tool can run

1648

a set of sanity checks on your documentation. It is enabled by adding

1649

these lines to the end of <filename>Makefile.am</filename>.

1650

<example><title>Enable gtkdoc-check</title>

1651

1652

<![CDATA[

1653

if ENABLE_GTK_DOC

1654

TESTS_ENVIRONMENT = \

1655

DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \

1656

SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)

1657

TESTS = $(GTKDOC_CHECK)

1658

endif

1659

]]>

1660

</programlisting>

1661

</example>

1662

</para>

1663

</sect1>

1664

1665

1666

1667

1668

<para>

1669

Version 1.18 brought some initial markdown support. Using markdown in

1670

doc comments is less intrusive than writing docbook xml. This version

1671

improves a lot on this and add a lot more styles. The section that

1672

explains the <link linkend="documenting_syntax">comment syntax</link>

1673

has all the details.

1674

</para>

1675

</sect1>

1676

</chapter>

1560

1677

1561

1678

1562

1679

<title>Documenting other interfaces</title>

Older »