Skip to main content

Generating Motoko documentation

Beginner
Motoko
Tutorial

mo-doc is a command-line tool for generating documentation for Motoko source code. It processes source files and generates documentation in various formats.

Quickstart​

Download mo-doc from Motoko's GitHub releases page or simply use the binary included in your dfx installation:

$(dfx cache show)/mo-doc [options]

Options​

  • --source <path>: Specifies the directory to search for Motoko source files. Defaults to src.

  • --output <path>: Specifies the directory where the documentation will be generated. Defaults to docs.

  • --format <format>: Specifies the generated format. Should be one of the following:

    • html: Generates HTML format documentation.
    • adoc: Generates AsciiDoc format documentation.
    • plain: Generates Markdown documentation.

    Defaults to html.

  • --help: Shows usage information.

Examples​

  1. Generate HTML documentation from the default source directory (src) and place it in the default output directory (docs):

    mo-doc

  2. Generate AsciiDoc documentation from a specific source directory:

    mo-doc --format plain --source ./motoko-code

  3. Generate Markdown documentation in a custom output directory:

    mo-doc --format adoc --output ./public

Writing doc comments​

mo-doc supports documenting your Motoko code using special block comments (/** */) and line comments (///).

Doc comments can be used to provide explanations for functions, classes, types, modules, variables, and more. They can span multiple lines and may contain rich Markdown formatting:

/// Calculate the factorial of a given positive integer.
/// 
/// Example:
/// ```motoko
/// factorial(0); // => null
/// factorial(3); // => ?6
/// ```
func factorial(n : Nat) : ?Nat {
    // ...
}

Resources​

Check out Motoko's base library source code for additional examples and best practices.

The source code for mo-doc is available in the dfinity/motoko GitHub repository. Contributions are welcome!