Documentation Generator

[turbolent]

Issue To Be Solved

It would be nice to have a tool that generates human-readable documentation for Cadence programs.

Suggest A Solution

Most pieces to build such a tool are in place:

• The AST is well-defined and can be serialized to a well-defined JSON format if needed (i.e. the tool could be potentially written in a language other than Go)
• The parser parses documentation comments ("docstrings"; line comments starting with /// and block comments starting with /**) for all declarations

The tool's main task would be to traverse the AST and generate e.g. Markdown, HTML, etc.

To generate the output, the documentation comments need to be written in a specific format/syntax. AFAIK there is no standard for this across programming languages. I think it would be best to adopt something that exists, I don't think it's necessary to reinvent the wheel here.

Inspiration:

• Swift: Markdown-based, with certain keywords like "Parameters"
• Solidity's NatSpec: Purely specific keywords/"tags" (@ prefix)
• Kotlin's KDoc syntax: Mix of Markdown and specific keywords/"tags" (@ prefix)
• Rust: also uses Markdown, but e.g. does not have a standardized way to refer to parameters
• Elixir: Markdown-based

Choosing a Markdown-based format has the benefit that it e.g. allows adding sections, example code blocks, etc.

Definition of Done

• Implement tool
• Tests
• Documentation

[SupunS]

This is now available through the following PRs:

• Add Cadence documentation generator #927
• Add function docs formatting support #938
• Add documentation for the Cadence documentation generator #1003
• Add wasm generation for docgen tool #1005
• Add npm package for the docgen-tool #1008

I'll close this issue since the all tasks mentioned here are covered.

We can open new git-issues for any feature/improvement requests.