Chandler Epydoc Style Guide

Below are examples of basic and advanced epydoc docstrings - please use these in your Chandler code or the auto-generated docs will not look nice or could even break due to epydoc errors.

Basic Layout Rules

1. Triple quotes should be on lines by themselves
2. All paragraphs should start at the same indent level as the triple quotes
3. Use blank lines to separate paragraphs
4. All type and param info should be at the end of the doc string and at the same indent level as the triple quotes

If you find yourself doing something other than the basic layout, the best place to find what is valid is the epytext manual itself.

def epydocFunction(foo, bar):
    """
    Sample function to show epydoc basic layout rules

    The purpose of this function is to demonstrate the
    basic layout style for a docstring so that epydoc will
    parse it cleanly.
     1. This is a list item.
     2. This a second list item.
           - This is a sublist
     3. This is the third list item and
         note that subsequent lines of
         the item can be indented more
         than the bullet.

    @type foo: str
    @param foo: The foo parameter of course!.
    @type bar: int
    @param bar: The bar parameter and it must have a really long
                        description so you can see that indents are ok.
    @rtype: int
    @return: why 42 of course.
    """

    return 42

Examples that do not follow the above rules:

def malformedExampleOne():
    """Sample Function
    This example breaks item 1, 2 and 3
    """
def malformedExampleTwo():
    """
    Sample Function Two

        This example breaks rule #2 because the
    first line of the first paragraph is not on the
    same level as the other lines.
    """