O Manual de Programação do KDevelop: Class Documentation with KDoc

Página seguinte Página anterior Índice geral

### 10. Class Documentation with KDoc

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.

### 10.1 How to use KDevelop's Documentation features

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.

### 10.2 Adding Class and Member Documentation

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_);

> `

### 10.3 Special Tags

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:

- Normal text. Paragraphs must be separated by at least one blank line.
- text of the form

      <pre>
      .....code fragments....
      </pre>

- Various tags of the form:

  > `

  >     @tagname [tag parameters]

  > `

The valid tags for each type of source code entity are:

- Classes

  > `

  >       @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.

  > `

- Methods

  > `

  >       @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.

  > `

- Constants, Enums, Properties

  > `

  >       @see
  >         as above

  > `

- ALSO `@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).

Página seguinte Página anterior Índice geral