In Code Documentation - madscatt/sasmol GitHub Wiki

Stub to hold EPYDOC usage definitions.

EPYDOC

http://epydoc.sourceforge.net/epydoc.html#python-docstrings

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

This function can be used in conjuction with L{z_transform} to
find an arbitrary function's zeros.

@type  m: number
@param m: The slope of the line.
@type  b: number
@param b: The y intercept of the line.  The X{y intercept} of a
          line is the point at which it crosses the y axis (M{x=0}).
@rtype:   number
@return:  the x intercept of the line M{y=m*x+b}.
"""
return -b/m

You can compare this function definition with the API documentation generated by epydoc. Note that:

Paragraphs are separated by blank lines. Inline markup has the form "x{...}", where "x" is a single capital letter. This example uses inline markup to mark mathematical expressions ("M{...}"); terms that should be indexed ("X{...}"); and links to the documentation of other objects ("L{...}"). Descriptions of parameters, return values, and types are marked with "@field:" or "@field arg:", where "field" identifies the kind of description, and "arg" specifies what object is described.

def example(): """ This is a paragraph. 1. This is a list item. - This is a sublist. - The sublist contains two items. - The second item of the sublist has its own sublist.

  2. This list item contains two
     paragraphs and a doctest block.

     >>> print 'This is a doctest block'
     This is a doctest block

     This is the second paragraph.
"""

def example(): """ - U{www.python.org} - U{http://www.python.org} - U{The epydoc homepage<http:// epydoc.sourceforge.net>} - U{The B{Python} homepage <www.python.org>} - U{Edward Loper<mailto:edloper@ gradient.cis.upenn.edu>} """

5.2.1 Functions and Methods parameters

@param p: ... A description of the parameter p for a function or method. @type p: ... The expected type for the parameter p. @return: ... The return value for a function or method. @rtype: ... The type of the return value for a function or method. @keyword p: ... A description of the keyword parameter p. @raise e: ... A description of the circumstances under which a function or method raises exception e.

Class and instance variables

class Point: 
    """ 
    @ivar x:  This is where you document x. 
    @ivar y:  This is where you document y. 
    """ 
    def __init__(self, x, y): 
        '''Create new point 
           @param x: X coord 
           @param y: Y coord 
        ''' 
        self.x = x
        self.y = y