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.
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:
;;(define-publicor any other function is special: what is the function about?A simple parser can then generate an HTML or markdown document that is structured:
All other comments can be read by drilling down inside functions.