Define a documentation standard

[pors]

As we want contracts to be read and understood as easy as possible, it would be nice to support an improved documentation system for Clarity. Think pydoc or something similar.

Proposal for a very simple and effective doc standard:

• comments are still ;;
• use markdown in comments
• the comment at the top is special: what is the contract about?
• comments above constants / variables / maps are special: what do they store?
• comments below a (define-public or any other function is special: what is the function about?

A simple parser can then generate an HTML or markdown document that is structured:

• Contract name (how?)
• Description
• Each constant / variable / map with a description
• All functions with a description

All other comments can be read by drilling down inside functions.