How to make doc strings for EDNA code

From EdnaWiki
Jump to: navigation, search

What are DocStrings

Python documentation strings (or docstrings) provide a convenient way of associating documentation with Python modules, functions, classes, and methods. An object's docsting is defined by including a string constant as the first statement in the object's definition. For example, the following function defines a docstring:

def x_intercept(m, b):
    """
    Return the x intercept of the line y=m*x+b.  The x intercept of a
    line is the point at which it crosses the x axis (y=0).
    """
    return -b/m

Rich Text Formatting

As most of EDNA documentation is generated automatically from docstrings by processing the source code through epydoc (to create HTML or PDF), the developer could want richer typesetting like lists, ... this is done by using the Epytext Markup Language which is a wiki-like typesetting.

To specify the markup language for a module (ReStructured Text instead of the default Epytext Markup Language for example), you should define a module-level string variable __docformat__, containing the name of the module's markup language. The name of the markup language may optionally be followed by a language code (such as en for English). Conventionally, the definition of the __docformat__ variable immediately follows the module's docstring:

__docformat__ = "restructuredtext en"

But this is out of the scope of this documentation, please refer to the epydoc Documentation

Interface documentation

As python uses dynamic typing of objects, it is very important to documents interfaces, this is easily be done by using epytext Fields. The example before gives:

def x_intercept(m, b):
    """
    Calculate the x intercept of the line y=m*x+b .  The x intercept of a line is the point at which it crosses the x axis (y=0).

    @param m: the slope of the line defined by the equation  y=m*x+b
    @type m: float
    @param b: The y intercept of a line with the y axis (x=0).
    @type b: float
    @return the x intercept of the line y=m*x+b with the x axis (y=0).
    @rtype: float
    """
    return -b/m


Back to documentation page