Do we have any guidance on creating docs for contract?

[0x-j]

Discord user ID

No response

Describe your question in detail.

Let's say I want to add docs for my move contract, is there an example?
Here's an entry function I'm trying to document. Here's a view function I'm trying to document.

I got a bunch of warnings when running move unit test

warning: invalid documentation comment

What error, if any, are you getting?

No response

What have you tried or looked at? Or how can we reproduce the error?

No response

Which operating system are you using?

macOS

Which SDK or tool are you using? (if any)

TypeScript SDK

Describe your environment or tooling in detail

No response

[gregnazario]

Documenting view functions

Documentation needs to be attached to the item associated. This is a little bit more picky than say with something like Rust.

For view functions

Below is an example of how to use with a view function:

/// My awesome module
module 0x42::example { // double slash can be anywhere

  // Double slash can be anywhere

  /// My awesome constant
  const MY_VALUE: u64 = 5;
   
  /// My awesome error message
  const E_MY_ERROR: u64 = 10;

  #[view]
  /// My awesome view function
  fun show_me_the_money() {
    // ...
  }
}

Comments that will fail

Below here are examples of doc comments /// that will fail

module 0x42::example {

  /// My awesome view function <- must be below the annotation, right above the thing commented
  #[view]
  fun show_me_the_money() {
    // ...
    /// Within a function
  }

  /// Not attached to anything
}

More details on comments

• // Can be used anywhere, denotes a normal comment
• /* */ Can be used anywhere as a block comment
• /// Is a doc comment, can only be used directly above a documentable item (e.g. variable, function, module). All annotations e.g. #[test] must be above the comment
• /** */ Is a doc block comment, similar restrictions to ///

See: https://aptos.dev/move/book/coding-conventions#comments