The goal of the project is to create infrastructure and process for the future development of the extensive Kerberos documentation.
The actualized documentation will be useful for developers and administrators, both for experienced ones and newcomers. It will address the following topics:
- Tutorial for Kerberos developers
- Tutorial for application developers
- Cookbook for administrators - Installation, configuration, troubleshooting
The documentation will be built incrementally. We will analyze what works and what doesn't and correct the course of action as needed.
Details of source documentation
The following fields must be included in the function documentation and should reside in the source code (as the most useful for those who updates the code and fixes bugs) :
- Function signature
- Brief function description
- Arguments - in/out with description
- Return value description
- Detailed description (optional)
- Link to Doxygen generated documentation (generated automatically)
The optional fields may include:
- See also section to refer to the related functions,
- Note section to highlight the specifics of the behaivor
- Examples of the usage
- Snap-shot of the real code involving this function
- Links to KRB5 Wiki Project page, krbdev discussion, RFC document or its section etc
- Version of Kerberos when fuction was introduced or became obsolete
This effectively means that we expect the Doxygen comments in the headers in the following format:
/** * @brief Some brief descr * * Optional long and very detailed description * * @param[in] context A krb5 library context (see krb5_init_context()) * * @return Something useful */ char * KRB5_CALLCONV krb5_f1 ( krb5_context context)
Also, when available, we suggest to have Part_2 information associated with the particular function in ReST format. It will be kept in the separate file. For example:
* Warnings and suggestions Warn about any potential mistakes. Point to other usefull places.
* 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
How to contribute
- The core team - the administrator - will post the initial listing of the tasks (such as list of API, admin tasks, "How to"-s etc) and will further support it.
- Community can suggest new tasks
- The core team will provide templates that, if helpful, may be used by the documentation writers. The most desirable format of the contributed documents is ReST as the easiest to integrate with the mainstream documentation.
- Community can provide the feedback on the documented tasks. There will be a designated mail box firstname.lastname@example.org for this purpose
- Doxygen 1.7.2 (www.stack.nl/~dimitri/doxygen/index.html)
- Sphinx 1.0.4 (sphinx.pocoo.org)
- Python 2.5+
- Restructured Text markup (docutils.sourceforge.net/docs/user/rst/quickstart.html)