Next Previous Table of Contents
Another important part of the documentation is including a descriptive help for your class interfaces. This will allow you and other
programmers to use your classes by reading the HTML class documentation that can be created with KDoc. KDevelop supports the use
of KDoc completely by creating the KDE-library documentation, also your application frameworks are already documented. To work
yourself into the provided code, it would be a good start to read the included documentation online. The following describes what to do
to get the API documentation, where KDevelop helps you add it and what kind of special tags KDoc provides additionally.
To create the API documentation after you generated a project, select "Make API-Doc" from the "Project" menu. This will process all header files and create the HTML output. Then you can access the documentation by selecting "API-Documentation" from the Help-menu or the according book symbol in the Documentation tree, folder "Current Project".
The documentation is already cross-referenced to the KDE and Qt online-class documentation, so you can follow the inheritance easily with the inheritance overview. This may help you getting started with the KDE and Qt documentation as well.
As KDevelop provides all means to add code automatically, it also offers direct documentation. Whenever you're using the Class Generator by choosing "Project"->"New Class", add a descriptive help message to the documentation field. This will add the documentation to the class header.
When adding class member functions and attributes with the classtools, add the member documentation to the according documentation fields as well.
You may think that documentation is a part of the development process that isn't very necessary. But remember that the more your project grows and the more people take part on the development process, class documentation is the best help to save time. If developers have to guess by method names what exactly the method does, it is even more likely that the meaning is misunderstood and the method apparently doesn't do the job a developer guessed it would do. Therefore keep track of your documentation and rebuild it as often as possible.
Besides this, the documentation files are NOT included into the project, nor do they have any internationalization support. Therefore all API documentation should be held in English to allow international development groups to work with your sources.
Whenever you may want to add documentation by hand into the header file, just add the documentation above the method or class in a C-comment style with the difference that the first line has to begin with a slash and a double asterisk.
Example:
/** enables menuentries/toolbar items
*/
void enableCommand(int id_);
NOTE: The following documentation of this chapter is taken from the KDoc documentation provided with KDoc by Sirtaj S. Kang taj@.kde.org), author of KDoc; Copyright (c) 1997
The documentation is a mixture of:
<pre> .....code fragments.... </pre>
@tagname [tag parameters]
The valid tags for each type of source code entity are:
@short [one sentence of text]
A short description of the class
@author [one sentence of text]
Class author
@version [once sentence of text]
Class version (I normally set this to the RCS/CVS tag "Id")
@see [one or more references to classes or methods]
References to other related documentation.
@see
as above
@return [one sentence]
A sentence describing the return value
@param [param name identifier] [param description]
Describe a parameter. The param description can span multiple
lines and will be terminated by a blank line, the end of the
comment, or another param entry. For this reason, param entries
should normally be the last part of the doc comment.
@see
as above
@ref
As a departure from the javadoc format, the metatag "@ref" has the same format as @see, but can appear anywhere in the documentation
(all other tags must appear on a line by themselves).
Next Previous Table of Contents