logo_kerberos.gif

Difference between revisions of "Projects/Kerberos Documentation"

From K5Wiki
Jump to: navigation, search
(Initial check-in)
 
m
 
(14 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
{{project-early}}
 +
{{project-rel|1.11}}
   
 
== Purpose ==
  
== Purpose ==
   
−
The goal of the project is to create infrastructure and process for the future development of the extensive Kerberos documentation.
 +
The goal of the project is to create an infrastructure and process for the future development of the extensive Kerberos documentation.
  +
The documentation should be useful and correct; it must be detailed, but optimized -- do not be too verbose.
  +
  +
'''The documentation will be built incrementally. We will analyze what works and what doesn't and correct the course of action as needed.'''
  +
Part of the criteria for "what works" is that the documentation should be easy to maintain.
   
 
The actualized documentation will be useful for developers and administrators, both for experienced ones and newcomers. It will address the following topics:
  
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
  
  +
* Complete reference - API, internal functions, data types, macros
−
* Tutorial for application developers
 +
* 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
 +
* 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.
  
   
  +
== Documentation for application developers ==
   
  +
Generally any topic in the Kerberos documentation can cross-reference with function documentation and each other.
   
−
== Details of source documentation ==
  
   
   
−
==== Function documentation ====
 +
== Details of source documentation ==
   
   
−
'''Part_1'''
  
  +
=== Documenting functions ===
   
−  
  +
The following fields ''must'' be included in the function documentation and should reside in the source code :
−
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
  
# Function signature
 
# Brief function description
  
# Brief function description
−
# Arguments - in/out with description
 +
# Arguments - [in/out] with description
 
# Return value description
  
# Return value description
 
# Detailed description (optional)
  
# Detailed description (optional)
−
# Link to Doxygen generated documentation (generated automatically)
 
−  
−  
−
'''Part_2'''
 
   
  +
<pre>
  +
/** Some brief description
  +
*
  +
* Optional detailed description
  +
*
  +
* @param[in] arg1 Description of arg1
  +
*
  +
* @return Something useful
  +
*/
  +
char * KRB5_CALLCONV
  +
krb5_X(type arg1)
  +
</pre>
   
 
The ''optional'' fields may include:
  
The ''optional'' fields may include:
Line 47: Line 54:
   
   
−
This effectively means that we expect the Doxygen comments in the headers in the following format:
  
  +
==== Workflow ====
   
−
/**
  
  +
# Configure Doxygen to generate output both in xml and html formats. Run Doxygen.
−
* @brief Some brief descr
  
  +
# For each function and data type generate document in ReST format. For the function ''krb5_X()'' lets call it ''krb5_X_p1''.
−
*
 
  +
# File ''krb5_X.rst'' can be used as input for Sphinx
−
* 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
  
  +
=== Documenting data types and macros===
−
Warn about any potential mistakes.
  
−
Point to other usefull places.
  
   
−
* Links to RFC, wiki Projects, krbdev discussions
  
  +
Similar to documenting functions.
−
: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 ==
  
== 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.
+
# 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.
 
# Community can suggest new tasks
 
# 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.
 +
# 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.
−
# Community can provide the feedback on the documented tasks. There will be a designated mail box krbdoc@mit.edu for this purpose
 +
# Community can provide the feedback on the documented tasks.
−  
   
 
== Tools ==
  
== Tools ==
   
−
* Doxygen 1.7.2 (www.stack.nl/~dimitri/doxygen/index.html)
 +
* Doxygen 1.7.2 <http://www.stack.nl/~dimitri/doxygen/index.html>
−
* Sphinx 1.0.4 (sphinx.pocoo.org)
 +
* Sphinx 1.0.4 <http://sphinx.pocoo.org>
−
* Python 2.5+
 +
* Python 2.5+ (with lxml extension)
−
* Restructured Text markup (docutils.sourceforge.net/docs/user/rst/quickstart.html)
 +
* Cheetah 2.4.4 <http://www.cheetahtemplate.org>
  +
* Restructured Text markup <http://docutils.sourceforge.net/docs/user/rst/quickstart.html>

Latest revision as of 10:21, 29 October 2013

This project was completed in release 1.11.


Purpose

The goal of the project is to create an infrastructure and process for the future development of the extensive Kerberos documentation. The documentation should be useful and correct; it must be detailed, but optimized -- do not be too verbose.

The documentation will be built incrementally. We will analyze what works and what doesn't and correct the course of action as needed. Part of the criteria for "what works" is that the documentation should be easy to maintain.

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.


Documentation for application developers

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


Details of source documentation

Documenting functions

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)
/** Some brief description
 * 
 * Optional  detailed description 
 * 
 * @param[in]  arg1  Description of arg1
 *
 * @return Something useful
 */
char * KRB5_CALLCONV 
krb5_X(type arg1)

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


Workflow

  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. For the function krb5_X() lets call it krb5_X_p1.
  3. File krb5_X.rst can be used as input for Sphinx


Documenting data types and macros

Similar to documenting functions.


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

Retrieved from "https://k5wiki.kerberos.org/wiki?title=Projects/Kerberos_Documentation&oldid=5245"