Clarigen can automatically generate contract documentation for you. By default, it includes type definitions for everything in your contract. If your contract includes comments and tags that further describe your contract, that will be included alongside the auto-generated type documentation.

tl;dr:

clarigen docs

Getting started

First, you'll need to configure your docs output.

[docs]
# docs will be generated at `./docs/$file.md`
output = "docs"

Once configured, just run clarigen docs, and Clarigen will generate documentation files for you.

Documentation output

Claridoc will generate a markdown file for each of your contracts under your configured docs.output folder. If your contract name is counter.clar, the file will be counter.md.

You'll also get a README.md file in your docs folder, which is a table of contents with links to each of your contracts.

How to document your contracts

Claridoc assumes a certain format for how you use comments to document your contracts.

Here's an example:

TODO: example

High-level contract description

Adding comments to the top of your contract allow you to provide a description of the contract. Use this area to describe the overall purpose of the contract.

;; The counter contract maintains a single global counter
;; variable. Users can change the counter by calling
;; `increment` and `decrement`.

Documenting Functions

Add comments right above a function to document that function. Any un-tagged comments will be used to show a "description" of the function.

Start a line with @param to document a parameter. The syntax for documenting params is:

@param [param-name]; param description

;; Increment the counter.
;;
;; @returns the new value of the counter
;;
;; @param step; The interval to increase the counter by
(define-public (increment (step uint))
  (let (
    (new-val (+ step (var-get counter)))
  )
  ;; #[allow(unchecked_data)]
  (var-set counter new-val)
  (print { object: "counter", action: "incremented", value: new-val })
  (ok new-val))
)

Tips for documenting contracts

• Use "vanilla" markdown inside of your comments. Claridoc will simply output the "raw" content, which will render as expected in markdown.
• Don't manually add type hints in your documentation. Claridoc will automatically extract types for everything in your contract.
• At the moment, Claridoc has very limited support for tags that you might expect from other documentation generators. Currently, @param is the only tag that is used to generate custom documentation.

Use markdown links to link to other methods and contracts. To link to a function within a contract, use an anchor link.

;; For more info, see [`.staking#stake`](`./staking.md#stake`)