doc/tdevelop/documentation.docbook


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

<chapter id="documentation">
<title>Documentation</title>

<para>
Documention unfortunately belongs to the most-overlooked programming
issues. Yet, once properly set up and maintained internal and external
documentation provides most valuable help.
</para>

<para>
Documentation has multiple facets. There is
<itemizedlist>
  <listitem><para>
  <emphasis>project internal documentation</emphasis>, mainly consisting of
  <itemizedlist>
    <listitem><para>
    <emphasis>comments</emphasis> in header/source files
    </para></listitem>
    <listitem><para>
    <emphasis>internal &API; documentation</emphasis> of your project
    generated from the program file by special tools, &eg; &doxygen;
    </para></listitem>
  </itemizedlist>
  </para></listitem>
  <listitem><para>
  <emphasis>project external documentation</emphasis>, comprising among others
  <itemizedlist>
    <listitem><para>
    <emphasis>external &API; documentation</emphasis> of &eg; common system libraries (&kde;, &Qt;, &etc;)
    </para></listitem>
    <listitem><para>
    any other documentation (programming language manuals, general system information, how-to articles and the like)
    </para></listitem>
  </itemizedlist>
  </para></listitem>
</itemizedlist>
</para>
<para>
All this documentation should be easily maintainable and ready at hand whenever you need it. &tdevelop; has provisions for just this.
</para>

<!-- ### doc browser, notes on internal documentation, how to profit from Doxygen -->

<sect1 id="docbrowser">
<title>The Documentation Browser</title>


<figure id="screenshot-doctreeview" float="1">
<title>A Screenshot of the Documentation Tree</title>
<mediaobject>
<imageobject><imagedata fileref="doctreeview.png"/></imageobject>
</mediaobject>
</figure>

</sect1> <!-- docbrowser -->

</chapter> <!-- documentation -->