-
Notifications
You must be signed in to change notification settings - Fork 27
Description
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:
- Available in the IDE to the users.
- Available to the AI agents when they are exploring the
midendependency source code. - The code snippets in the doc comments are testable with
cargo test --docwhich guarantees that they are always up to date. - 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