logo_kerberos.gif

Difference between revisions of "Projects/Kerberos Documentation"

From K5Wiki
Jump to: navigation, search
(Initial check-in)
 
(Added workflow descr for "Documenting functions".)
Line 3: Line 3:
 
== 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 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, read and verify message, etc
 
* Cookbook for administrators - Installation, configuration, troubleshooting
  
* Cookbook for administrators - Installation, configuration, troubleshooting
  +
* Contributions to Kerberos code - topics on how to write plugins, kerberize cloud, etc
  +
   
 
The documentation will be built incrementally. We will analyze what works and what doesn't and correct the course of action as needed.
  
The documentation will be built incrementally. We will analyze what works and what doesn't and correct the course of action as needed.
Line 18: Line 20:
   
   
−
==== Function documentation ====
 +
==== Documenting functions ====
   
   
Line 24: Line 26:
   
   
−
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) :
 +
The following fields ''must'' be included in the function documentation and should reside in the source code (as the most useful for those who update the code and fix the 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)
 
   
   
Line 47: Line 48:
   
   
−
This effectively means that we expect the Doxygen comments in the headers in the following format:
 +
This effectively means that we expect the Doxygen style comments in the headers in the following format:
   
 
/**
  
/**
Line 54: Line 55:
 
* Optional long and very detailed description
 
* Optional long and very detailed description
 
*
 
*
−
* @param[in] context A krb5 library context (see krb5_init_context())
 +
* @param[in] context A krb5 library context (see krb5_Z())
 
*
  
*
 
* @return Something useful
  
* @return Something useful
 
*/
  
*/
 
char * KRB5_CALLCONV
 
char * KRB5_CALLCONV
−
krb5_f1 ( krb5_context context)
+
krb5_X ( 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:
 +
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 (one file per function). For example:
   
 
* Warnings and suggestions
  
* Warnings and suggestions
Line 74: Line 75:
 
* Example
  
* Example
 
The place for the function usage examples
  
The place for the function usage examples
  +
  +
  +
'''Workflow: Putting Part_1 and Part_2 together'''
  +
  +
  +
# Configure Doxygen to generate output both in xml and html formats. Run Doxygen.
  +
# 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''.
  +
# 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.
  +
# 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''.
  +
# File ''krb5_X.rst'' can be used as input for Sphinx
  +
  +
  +
NOTE: We provide Python script to automate steps 2-4.
  +
  +
  +
==== Documenting data types ====
  +
  +
TODO
   
   
 
== 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.
 
# 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. There will be a designated mail box krbdoc@mit.edu for this purpose
   
Line 86: Line 105:
 
== 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+
−
* Restructured Text markup (docutils.sourceforge.net/docs/user/rst/quickstart.html)
 +
* Restructured Text markup <http://docutils.sourceforge.net/docs/user/rst/quickstart.html>

Revision as of 11:08, 7 December 2010

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 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, read and verify message, etc
  • Cookbook for administrators - Installation, configuration, troubleshooting
  • Contributions to Kerberos code - topics on how to write plugins, kerberize cloud, etc


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

Documenting functions

Part_1


The following fields must be included in the function documentation and should reside in the source code (as the most useful for those who update the code and fix the bugs) :

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


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


This effectively means that we expect the Doxygen style 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_Z())
  *
  * @return Something useful
  */
 char * KRB5_CALLCONV 
 krb5_X ( 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 (one file per function). 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


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. 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. 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: We provide Python script to automate steps 2-4.


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.
  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. There will be a designated mail box krbdoc@mit.edu for this purpose


Tools

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