#51 Allow comments in code extend documentation

[Daniele Varrazzo]

Comments in #: form may add fields that should have been specified in the docstring, with the folowing benefits:

- the docstring, which should describe the function interface, is not cluttered with implementation details

- the implementation details are close to the relevant code, promoting consistence between code and docs

Here the proposed details and some edloper's considerations:

> - parsing some "#:" comments into functions body as they were part of the function docstring. It would keep some additional information close to the code implementing it, making the task to keep the API consistent with the code easier. Es.

This is a little bit problematic, because it would be hard to tell the difference between "#:" comments that are supposed to describe the enclosing object vs "#:" comments that are supposed to describe a variable assignment. E.g., I think people would do things like:

| def __init__(self, foo):
| """This is a constructor of some sort."""
| ...there may be other code
|
| #: :warning: the current implementation only allows
| #: positive numbers
| val = floor(log(num) / log(10)) + 1
|
| ...

or:

| class A:
| "..."
| ... other code
|
| #: :warning: ...
| x = 123

Where it's unclear whether whether that warning applies to the constructor function or to the 'val' variable.

> Some tags (note, bug, warning, todo) are really best placed next the code to be documented; precondition and postcondition would be nice close to an assert etc.

True, but I'm not sure how to reconcile this with the ability to use "#:" comments to describe variables.