Skip to content

Extend the Miden SDK documentation in the source's doc comments #200

@greenhat

Description

@greenhat

As I mentioned in #177.

Let's extend the Miden SDK docs and directly link to it in the docs.

The benefits of the doc comments:

  1. Available in the IDE to the users.
  2. Available to the AI agents when they are exploring the miden dependency source code.
  3. The code snippets in the doc comments are testable with cargo test --doc which guarantees that they are always up to date.
  4. Lowest risk of being stale.

We can put "getting started" and "tuturial" type of docs on the SDK crates lib.rs level and extensive examples on the individual module (note, account, etc.) level in doc comments so they will be rendered first on the page in the docs.rs before the module API references. In the doc comments for the functions, types (structs, enums) we can also put any extra code examples we like.

I think we can put a reasonably large (few screens) amount of text even on the function/type level. The only limiting factor I see is the IDE UI usually renders it in a relatively small window so the user would have to scroll. So I think we should not limit ourselves in the amount of text we can put in. For the lib.rs and individual module level I don't think we should restrict ourselves at all.

/cc @Keinberger

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions