You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
58 lines
1.8 KiB
58 lines
1.8 KiB
15 years ago
|
<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, ⪚ &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 ⪚ 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. &kdevelop; 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 -->
|