Extend the Miden SDK documentation in the source's doc comments
- 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
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