Documentation | ||
| Prev | Next | |
It's important to document your application so that end-users can make the most of it. You should be clear and concise. Describe any non-standard installation, usage and UI features. There's no need to talk about how to use the File menu, for example, unless you've put some special entry on it. Include contact and bug-reporting information as well as a hyperlink to the application's home page. Writing documentation for KDE 3.x should be done in DocBook. Look at http://i18n.kde.org for more details on using the docbook tools.
You should also document your widgets and other classes. You can include comments in your header ( .h) files which describe each public or protected method. It you do this as you write the methods it will make the documentation process seem easier. (It may also help you be certain about what function(s) that method is to perform.) The script kdoc will turn your header files into beautiful class documentation. You can see examples of kdoc output if you look at http://www.ph.unimelb.edu.au/~ssk/kde/srcdoc/kdecore/index-long.html. (This page has the annotated list of the core KDE classes.)
It's called kdoc and it's in the kdedoc subdirectory of the CVS module kdesdk.
If you mark up your header files like this:
/**
* Short description of this class
*
* This is a longer description of my class. It does the following
* @li Some bulleted thing
* @li Some other bulleted thing
* You should use it when ... It's not appropriate for ...
*
* @author My Name <MYEMAIL@WHEREVER.EDU>
* @version 0.0.1
**/
class KMyClass
{
/**
* Describe method. It takes @p argument to mean ...
*
* @return A pointer to another class
* @see KOtherClass
**/
KOtherClass *method (int argument);
}
You can indicate parameters inline using the @p tag. Please do not use <i> any more.
To run kdoc, use the following command
kdoc -dhtml -L$KDEDIR/share/kdoc -a title header1.h header2.h ...
This instructs kdoc to generate HTML output (the default) in the
html directory (by the -d option) from the specified header
files. It uses title as the title for the documentation. ( -a
says to do work on all header files, even if they don't "ask for it". I
haven't told you how to "ask for it." The -L tells kdoc where
its libraries are.) Type kdoc -h for more information.