Projects/Kerberos Documentation

This is an early stage project for MIT Kerberos. It is being fleshed out by its proponents. Feel free to help flesh out the details of this project. After the project is ready, it will be presented for review and approval.

Purpose

The goal of the project is to create an infrastructure and process for the future development of the extensive Kerberos documentation.

The documentation will be built incrementally. We will analyze what works and what doesn't and correct the course of action as needed.

The actualized documentation will be useful for developers and administrators, both for experienced ones and newcomers. It will address the following topics:

• Complete reference - API, internal functions, data types, macros
• Tutorial for application developers - description on various tasks such as working with credentials, topics on how to write plugins, etc
• Cookbook for administrators - Installation, configuration, troubleshooting.

Example

Please, follow this link for Kerberos documentation general example [1]; advanced admin topic example: [2] MIT Kerberos features: [3]

Documentation for application developers

TODO

Generally any topic in the Kerberos documentation can cross-reference with function documentation and each other. See [4]

Details of source documentation

Documenting functions

Part_1

The following fields must be included in the function documentation and should reside in the source code  :

1. Function signature
2. Brief function description
3. Arguments - [in/out] with description
4. Return value description
5. Detailed description (optional)

One can see that Part_1 contains the information that is the most useful for those who update the code and fix the bugs. To avoid the code overcrowding and make any additions to the function documentation as simple as possible, we suggest to save additional documentation ( see below Part_2) in the separate location - one file per function..

Effectively this means that we expect the Doxygen style comments in the headers in the following format:

/**
 * @brief Some brief description
 * 
 * Optional  detailed description 
 * 
 * @param[in]  arg1  Description of arg1
 *
 * @return Something useful
 */
char * KRB5_CALLCONV 
krb5_X(type arg1) 

Note, that @brief notation may be omitted if JAVADOC_AUTOBRIEF is set to YES in the Doxygen configuration file. In this case the very first line of the comments will be interpreted as the brief description:

/** Some brief description
 * 
 * Optional  detailed description 
 * 
 * @param[in]  arg1  Description of arg1
 *
 * @return Something useful
 */
char * KRB5_CALLCONV 
krb5_X(type arg1) 

Part_2

The optional fields may include:

1. See also section to refer to the related functions,
2. Note section to highlight the specifics of the behaivor
3. Examples of the usage
4. Snap-shot of the real code involving this function
5. Links to KRB5 Wiki Project page, krbdev discussion, RFC document or its section etc
6. Version of Kerberos when fuction was introduced or became obsolete

Part_2 in ReST format

When available, we suggest to have Part_2 information associated with the particular function in ReST format. For example:

* Warnings and suggestions
  Warn about any potential mistakes and misuse.
  Point to other useful routines.

 * Links to RFC, wiki Projects, krbdev discussions
  :rfc:4120 
  Or if you want to reffer to the specific section of the RFC use the following notation: :rfc:4120#section-5.2
  Or link to Kerberos Project page, for example, Disable_DES project  <http://k5wiki.kerberos.org/wiki/Projects/Disable_DES>

 * Example
    The place for the function usage examples

Part_2 in Doxygen format

Alternatively, when desired, Part_2 may be documented in Doxygen format by adding @include directive to the comment, for example, to reference to example code fragments

/** Some brief description
 * 
 * Optional  detailed description 
 * 
 * @param[in]  arg1  Description of arg1
 *
 * @return Something useful
 *
 * @include example_krb5_X.c
 */
char * KRB5_CALLCONV 
krb5_X(type arg1) 

Note: The path to the example file (here example_krb5_X.c) must be set in the EXAMPLE_PATH tag in the Doxygen configuration file

Workflow: Putting Part_1 and Part_2 together

1. Configure Doxygen to generate output both in xml and html formats. Run Doxygen.
2. For each function and data type generate document in ReST format. It is expected that it contains information from Part_1. For the function krb5_X() lets call it krb5_X_p1.
3. (For ReST format only) If the Part_2 documentation for krb5_X() has been already written, there is a file called krb5_X_p2.rst in the designated directory. If not - nothing happens.
4. (For ReST format only) Concatenate krb5_X_p1 and krb5_X_p2.rst (if it exists), add the link to Doxygen generated documentation for this function in html format (generated automatically) and save as a file krb5_X.rst.
5. File krb5_X.rst can be used as input for Sphinx

NOTE: Initially we provide Python script to automate steps 2-4. The whole process will be automated later.

Documenting data types

TODO

How to contribute

1. The core team - the administrator - posts the initial list of the tasks (such as API, admin tasks, "How to"-s etc) and further supports it. See Projects/Documentation Tasks for more detailed information.
2. Community can suggest new tasks
3. The core team provides templates that, if helpful, may be used by the documentation writers. The most desirable format for the contributed documents is ReST as the easiest to integrate with the mainstream documentation.
4. Community can provide the feedback on the documented tasks.

Tools

• Doxygen 1.7.2 <http://www.stack.nl/~dimitri/doxygen/index.html>
• Sphinx 1.0.4 <http://sphinx.pocoo.org>
• Python 2.5+ (with lxml extension)
• Cheetah 2.4.4 <http://www.cheetahtemplate.org>
• Restructured Text markup <http://docutils.sourceforge.net/docs/user/rst/quickstart.html>