Example syntax in comments

[tazjin]

In @grahamc's manually written doc comments, multiple (named) examples are supported. It would be great to be able to specify examples in the comments, too.

Currently these syntaxes are recognised:

Example: <some example code>

# or alternatively
Example:
    <some example code>

I propose keeping those working, and adding an additional syntax for named examples:

Example: This shows how to do X
    <code to do X>