Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

...

Documentation is placed in tripled double-quoted strings right below what you are documenting.

Code Block
borderStylesolid
titleDocumentation with Summary
borderStylesolid
def Hello():
"""Says "hello" to the world."""
    print "Hello, World!"

Hello()

...

Parameters should also be documented.

Code Block
titleParameters
borderStylesolid
titleParameters
def Hello(name as string):
"""
Say "hello" to the given name.
Param name: The name to say hello to.
"""
    print "Hello, $name!"

Hello("Harry")

...

If describing the parameter takes more than one line, you should move it all to a new line and indent.

Code Block
borderStylesolid
titleLong Parameter
borderStylesolid
def Hello(name as string):
"""
Say "hello" to the given name.
Param name:
    The name to say hello to.
    It might do other things as well.
"""
    print "Hello, $name!"

...

Here's some examples of proper documentation:

Code Block
borderStylesolid
titleDocumentation example
borderStylesolid
import System

class MyClass:
"""Performs specific duties."""
    def constructor():
    """Initializes an instance of <MyClass>"""
        _rand = Random()

    def Commit():
    """Commits an action."""
        pass

    def CalculateDouble(i as int) as int:
    """
    Returns double the value of [i].
    Parameter i: An <int> to be doubled.
    Returns: Double the value of [i].
    """
        return i * 2

    def CauseError():
    """
    Causes an error.
    Remarks: This method has not been implemented.
    Raises NotImplementedException: This has not been implemented yet.
    """
        return NotImplementedException("CauseError() is not implemented")

    def DoSomething() as int:
    """
    Returns a number.
    Example: Here is a short example:
        print DoSomething()
    Returns: An <int>.
    See Also: MakeChaos()
    """
        return 0

    def MakeChaos():
    """
    Creates Chaos.
    Include file.xml: Foo/Bar[@id="entropy"]
    Permission Security.PermissionSet: Everyone can access this method.
    """
        print "I am making chaos: $(_rand.Next(100))"

    def Execute():
    """
    Executes the protocol.
    Does one of two things,
    # Gets a sunbath.
    # Doesn't get a sunbath.
    """
        if _rand.Next(2) == 0:
            print "I sunbathe."
        else:
            print "I decide not to sunbathe."

    def Calculate():
    """
    Does these things, in no particular order,
    * Says "Hello"
    * Looks at you
    * Says "Goodbye"
    """
        thingsToDo = ["I look at you.", 'I say "Hello."', 'I say "Goodbye."']
        while len(thingsToDo) > 0:
            num = _rand.Next(len(thingsToDo))
            print thingsToDo[num]
            thingsToDo.RemoveAt(num)

    [Property(Name)]
    _name as string
    """A name""" // documents the property, not the field

    Age as int:
    """An age"""
        get:
            return _rand.Next(8) + 18

    _age as int

    _rand as Random

...