# The KDOC Handbook

Write developer documentation, easily and quickly

Sirtaj Singh Kang

    taj@kde.org

1999 2000 Sirtaj Singh Kang
&FDLNotice;
17/11/2000
2.0.0

KDOC generates documentation in a variety of formats, directly from C, C++ and IDL interface definitions. KDOC uses specially formatted comments in the source to allow customized documentation.

KDOC C++ C KDE Libraries Documentation API Literate Programming

## Introduction

### What is KDOC?

KDOC generates documentation in a variety of formats, directly from C, C++ and IDL interface definitions. KDOC uses specially formatted comments in the source to allow customized documentation.

It is also very useful as a general class browser for libraries, since the output is quickly navigable and many index views are presented.

### Features

- Support for C, C++ and OMG CORBA IDL languages.

- Output in HTML, LaTeX, Manpage, Texinfo and DocBook SGML formats. The DocBook format can in turn be converted to various printable and online formats.

- Automatically works out many relationships between objects and their properties, such as hierarchies, overridden virtuals, non-instantiable (abstract) classes and more.

- Doc Comments are written in the javadoc style, with many useful extensions for organizing, documenting and presenting libraries.

- Supports a CPP (preprocessor) pass via an external preprocessor, to expand macros and #ifdefs.

- Support for the Qt GUI Toolkit's signal and slot specifiers.

- Cross-reference documentation generated for other libraries. Links and class hierarchies that reference external libraries are correctly shown.

- Includes makekdedoc, an easy automake-like tool for generating documentation for multiple libraries at once.

- Includes qt2kdoc, which allows you to link your documentation with the Qt GUI Toolkit's HTML documentation as if it had been generated by KDOC itself.

- An output mode that allows you to check for errors or omissions in your documentation.

- The application is written entirely in Perl, and is therefore quite portable and extensible.

### History

Torben Weis weis@kde.org wrote a perl script that proved how simple it was to parse the KDE Library headers to generate documentation that looked like the Qt documentation.

Sirtaj Singh Kang taj@kde.org took it upon himself to extend this program to turn it into a full-fledged application. He found out the hard way that while it takes 10% effort to parse 75% of source, the next 10% takes another 100%.

KDOC 1.0 still used some of Torben's source, but never really worked properly but was useful enough for a year or so.

KDOC 2.0 is a complete rewrite of KDOC, and is much more extensible and robust, even though it has scores of new features that were impossible to put into 1.0.

## Using KDOC

### Support and Downloads

Web page

  KDOC has a web page at http://www.ph.unimelb.edu.au/~ssk/kde/kdoc/. It can be downloaded from there.

Via KDE CVS or CVSup

  You can checkout KDOC from the KDE CVS server in the module kdoc. This is the repository used for KDOC development, so it will always be up to date.

Mailing List

  There is a KDOC mailing list hosted by the KDE project, at kdoc-list@kde.org. To subscribe, mail kdoc-list-request@kde.org with `subscribe` in the message body (not the subject).

The KDOC FAQ

  The KDOC FAQ has answers to common questions and problems with KDOC.

Email: the last resort

  If all else fails, I will respond to decent questions via email, but I cannot promise prompt replies. Mail the KDOC team at kdoc@kde.org.

### Installation

#### Supported Environments

KDOC requires Perl 5.004 to function. Most environments where this is installed are supported by KDOC.

KDOC has been reported to run to some extent on &Microsoft; &Windows; (NT/95/98) but you may encounter some problems with filenames. Also, you will probably have to hack the install scripts and file locations manually since the configure script only works on &UNIX;.

#### Building the distribution

The procedure for building KDOC is similar to most other GPL programs that come with a configure script.

- Unpack the distribution

  Unpack the distribution into a temporary directory. It will extract itself into its own directory. If you have downloaded the `tar.bz2` version:

      # bunzip2 < kdoc-2.0a1.tar.bz2 | tar xf -

  Or if you have downloaded the `tar.gz` version:

      # gunzip < kdoc-2.0a1.tar.gz | tar xf -

  Replace the distribution file name in the above procedure with the one you have downloaded.

- Build the application

  This will configure KDOC to install itself in `/usr/local/`:

      # cd kdoc-2.0a1
      # ./configure

  To install it in a different directory, say `/opt/kdoc`, add a prefix option to configure like this:

      # ./configure --prefix=/opt/kdoc

- Perform the installation

      # make; make install

- Remove the temporary directory

      # cd ..
      # rm -rf kdoc-2.0a1

Now KDOC should be installed on your system.

### KDOC at the command line

The most up-to-date source for command line options is always the man page that is distributed with the application. This section will provide a general overview of how to run the program.

## Writing Documentation

### Commenting Source

TODO: Explain doc comments. Explain tags. Examples.

### Tips on Style

TODO: Various doc suggestions: internal/deprecated, short descriptions, link to Qt documentation guidelines.

## Frequently Asked Questions

TODO: No questions, no answers.

## Credits and Licenses

KDOC

Copyright 1999-2000 Sirtaj Singh Khan taj@kde.org

Documentation Copyright 1999-2000 Sirtaj Singh Khan taj@kde.org

&underFDL; &underGPL;

## Doc tag reference

### Doc Comments

TODO

### Common tags

@li <text>

  A list item.

@internal

  Mark member as internal to the library and not for external use.

@deprecated

  Marks member as obsolete.

@version <string>

  Provide version information about the member. I normally set this to the RCS/CVS ID tag.

@author <string>

  Specify the author.

@since <string>

  Specify the version of the API in which this member was added.

@sect <string>

  A section heading, for grouping your doc comment logically.

<pre> text </pre>

  A block of literal (preformatted) text, useful for code examples.

@image <path>

  Embed an image in the output. This can be set to a URL, but it is better to use a path if possible since this will allow the image to be included in other formats in the future.

@see <ref>,...

  Links to related information.

@ref <ref>

  Like @see, but inline, so it can be used within a text paragraph. Also, only one member can be referenced at a time, so you will have to include multiple @ref tags for multiple members.

### Tags for Library Documentation

To provide documentation for the entire library, use the @libdoc tag within a doc comment. If this appears in a doc comment, the comment is associated with the library instead of with the following syntax member.

@libdoc <string>

  Marks a doc comment as documentation for the library. The string is used as the title of the library.

### Tags for Classes

@short <string>

  Short description of the class, one sentence long.

  If class documentation is present but no short description is specified, the first sentence (up to and including the first period) is used instead.

### Tags for Functions

@param <paramname> <text>

  Documentation for a parameter. No check is done whether the parameter name specified is actually a parameter of the function.

@return <text>

  Documentation for the value returned by the function.

@throws <ref>,...

  Define the exceptions that may be thrown from this function. Synonyms are: @exception and @raises.

@param <paramname> <text>

  Documentation for a parameter. No check is done whether the parameter name specified is actually a parameter of the function.

## Utilities

### qt2kdoc: Link with &Qt; HTML documentation

### makekdedoc: Generate docs for KDELIBS and other groups of libraries

## Other useful tools