0xMiden / 0xMiden/docs

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

Open Beginner friendly
#200 1 comment 1 reaction 0 assignees View on GitHub
Dominant language
TypeScript
Stars
10
Forks
50
Avg merge
22d 23h
Merged PRs (30d)
1

Description

As I mentioned in https://github.com/0xMiden/docs/issues/177.

Let's extend the [Miden SDK docs](https://docs.rs/miden/latest/miden/) 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

Contributor guide

Open the contributing guide

Research direction

Look at the Miden SDK crates, starting with the `lib.rs` file for top-level documentation and module-level files like `note` and `account`. Use `cargo doc --open` to see the current rendered docs. Add doc comments with examples, ensuring they are testable with `cargo test --doc`. Focus on linking these updates to the main documentation site.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.