Epydoc Fields

Fields are used to describe specific properties of a documented object. For example, fields can be used to define the parameters and return value of a function; the instance variables of a class; and the author of a module. Each field consists of a tag, an optional argument, and a body.

• The tag is a case-insensitive word that indicates what kind of documentaiton is given by the field.
• The optional argument specifies what object, parameter, or group is documented by the field.
• The body contains the main contents of the field.

1. Field Markup

Each docstring markup langauge marks fields differently. The following table shows the basic fields syntax for each markup language. For more information, see the definition of field syntax for each markup language.

2. Supported Fields

The following table lists the fields that epydoc currently recognizes. Field tags are written using epytext markup; if you are using a different markup language, then you should adjust the markup accordingly.

2.1. Notes on Supported Fields

• @param fields should be used to document any explicit parameter (including the keyword parameter). @keyword fields should only be used for non-explicit keyword parameters:

  def plant(seed, *tools, **options):
      """
      @param seed: The seed that should be planted.
      @param tools: Tools that should be used to plant the seed.
      @param options: Any extra options for the planting.
  
      @keyword dig_deep: Plant the seed deep under ground.
      @keyword soak: Soak the seed before planting it.
      """
      [...]
  

• For the @group and @sort tags, asterisks (*) can be used to specify multiple children at once. An asterisk in a child name will match any substring:

  class widget(size, weight, age):
      """
      @group Tools: zip, zap, *_tool
      @group Accessors: get_*
      @sort: get_*, set_*, unpack_*, cut
      """
      [...]
  

• Since the @type field allows for arbitrary text, it does not automatically create a crossreference link to the specified type, and is not written in fixed-width font by default. If you want to create a crossreference link to the type, or to write the type in a fixed-width font, then you must use inline markup:

  def ponder(person, time):
      """
      @param person: Who should think.
      @type person: L{Person} or L{Animal}
      @param time: How long they should think.
      @type time: C{int} or C{float}
      """
      [...]
  

3. Field Synonyms

Several fields have "synonyms," or alternate tags. The following table lists all field synonyms. Field tags are written using epytext markup; if you are using a different markup language, then you should adjust the markup accordingly.

New fields can be defined for the docstrings in a module with the special module-level variable "__extra_epydoc_fields__". This variable should contain a list of field specifications, where each field specification is one of the following:

• A single string, which defines both the tag and the label for the field.
• A tuple (tag, label), where tag is the field's tag, and label is its label.
• A tuple (tag, singular, plural), where tag is the field's tag, singular is the label that is used when the field has one entry, and plural is the label that is used when the field has multiple entries.

The following example illustrates how the special variable "__extra_epydoc_fields__" can be used:

__extra_epydoc_fields__ = [
    ('corpus', 'Corpus', 'Corpora')]

def example():
    """
    @corpus: Bob's wordlist.
    @corpus: The British National Corpus.
    """
    [...]

New fields can also be defined for an individual docstring, using the special @newfield field. In particular, "@newfield tag: label [, plural]" will define a new field, whose tag is tag; and which is labeled in output documentation as label. The optional argument plural specifies the label that should be used if the field has multiple entries.

5. Markup-Specific Notes

For the most part, fields are treated identically, regardless of what markup language is used to encode them. However, there are a few minor differences, which are intended to accomodate existing standards for each markup language. In particular:

• ReStructuredText supports an extra group of fields, called consolidated fields, which combine the documentation for several objects into a single field.
• Javadoc uses a special syntax for the body of the @see fields.
• Javadoc does not support multi-word arguments.

For more information about these differences, read the subsections below.

5.1. ReStructuredText Fields

In ReStructuredText, a single field can be used to encode the documentation for a group of related items. For example, a single :Parameters: field is often used to describe all of the parameters for a function or method:

def fox_speed(size, weight, age):
    """
    Return the maximum speed for a fox.

    :Parameters:
      - `size`: The size of the fox (in meters)
      - `weight`: The weight of the fox (in stones)
      - `age`: The age of the fox (in years)
    """
    [...]

Epydoc will automatically extract information about each parameter from this list. These consolidated fields may be written using either a bulleted list or a definition list. If a consolidated field is written as a bulleted list, then each list item must begin with the field's argument, marked as interpreted text, and followed by a colon or dash. If a consolidated field is written as a definition list, then each definition item's term should contain the field's argument, marked as interpreted text. The term classifier, if present, is used to specify the associated type. The following example shows the use of a definition list to define a consolidated field. (Note that docutils requires a space before and after the ":" used to mark classifiers.)

def fox_speed(size, weight, age):
    """
    Return the maximum speed for a fox.

    :Parameters:
      `size`
          The size of the fox (in meters)
      `weight` : float
          The weight of the fox (in stones)
      `age` : int
          The age of the fox (in years)
    """
    [...]

The following consolidated fields are currently supported by epydoc:

5.2. Javadoc Fields

For compatibility with Javadoc, every @see field is assumed to contain a single crossreference link, unless its body is quoted, or it starts with an HTML tag. See the Javadoc reference manual for more information about how the @see field is encoded in Javadoc.

Because Javadoc does not mark end of the optional argument, field arguments must contain exactly one word. Thus, multi-word arguments are not available in Javadoc. In particular, all group names must be single words.