Skip to end of metadata
Go to start of metadata

Part 21 - Documentation

Icon

A communicable material used to explain some attributes of an object, system or procedure.

I've saved the most important for last, as documentation is itself, just as important as the code which it describes.

When documenting your code, be sure to remember:

  1. All your documents should be in English.
  2. Use full sentences.
  3. Avoid spelling/grammar mistakes.
  4. Use present tense.

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

Documentation with Summary

That "docstring" is the least you can do to document your code. It gave a simple summary.
If your docstring spans more than one line, then the quotes should go on their own lines.
You may have noticed that 'Says "hello" to the world.' is not a full sentence. For the first sentence in a summary, you can imply "This member".

Parameters should also be documented.

Parameters

To read it to yourself, it goes as such: 'Say "hello" to the given name. Parameter name is defined as the name to say hello to.'
This keeps in line with using full sentences.

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

Long Parameter

The same goes with any block.

Here is a list of all the tags that can be used

Tag

Description

No tag

A summary of the member.

Param <name>: <description>

This specifies the parameter <name> of the method.

Returns: <description>

This describes what the method returns.

Remarks: <text>

This provides descriptive text about the member.

Raises <exception>: <description>

Gives a reason why an Exception is raised.

Example: <short_description>: <code_block>

Provides an example.

Include <filename>: <tagpath>[@<name>="<id>"]

Includes an excerpt from another file.

Permission <permission>: <description>

Describe a required Permission.

See Also: <reference>

Lets you specify the reference that you might want to appear in a See Also section.

And a list of inline tags

Tag

Description

* <item>
* <item>
* <item>

Bullet list

# <item>
# <item>
# <item>

Numbered List

<<reference>>

Provides an inline link to a reference. e.g. <int> or <string> would link.

[<param_reference>]

References to a parameter of the method.

Here's some examples of proper documentation:

Documentation example

This should give you a good view on how to document your code.

I think Dick Brandon said it best:

Quote: Dick Brandon
Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing.

Go on to Part 22 - Useful Links

  • No labels