Since the initial SNIP-4 proposal, both the Starknet contract syntax and Cairo programming language have radically transformed. It therefore seems worth revisiting the comment/documentation standard.
SNIP-4 established a NatSpec-like documentation style for Cairo v0.TL;DR NatSpec uses tags in the comment block a la @dev, @notice, @param, etc.
The new syntax of Cairo v1+ is in many ways a brand new language with a heavy Rust resemblance. Given the strong Rust influence on the language, it makes sense to me that Cairo should follow a Rust-like documentation approach. Rust’s doc style utilizes markdown in the comment block and does not use tags (see here).
A few projects have already chosen Rust-like comments (at least as of this writing):
Contract documentation refers to an expositional overview of the contract. This may include a description of the contract itself and examples of use. Contract documentation may use the characters //! to communicate that it is contract documentation. This proposal recommends that contract documentation should start at the top of the file.
Shouldn’t we focus on modules instead of contracts? Especially with the upcoming components functionality.
2. SPDX license identifiers
This proposal recommends that every contract includes an SPDX license identifier. For visibility purposes, this proposal also recommends beginning the contract documentation with an SPDX license identifier (which is similar to the recommended Solidity source file layout).
What’s the requirement level of is this recommendation as per RFC2119? SHOULD? OPTIONAL?
Either way, I’m unsure how tightly should we couple licensing and comment standardization.
3. Element documentation
#[starknet::contract]
mod MyContract {
#[storage]
struct Storage {}
/// Returns the sum minus one of `arg1` and `arg2`.
/// `arg1` cannot be zero.
///
/// # Panics
///
/// This function will panic if `arg1` is `0`.
///
/// # Examples
///
/// ```rust
/// let a: felt252 = 2;
/// let b: felt252 = 3;
/// let c: felt252 = sum_minus_one(a, b);
/// assert(c + 1 == a + b, "Should equal a + b");
/// ```
#[external(v0)]
fn sum_minus_one(arg1: felt252, arg2: felt252) -> felt252 {
assert(arg1 != 0, "Cannot be zero");
let sum: felt252 = arg1 + arg2;
// Subtract `1` from the sum
sum - 1
}
}
This is not a suggestion but a comment, I feel like the doc is very long and its beginning can get a bit far away of the function name (or any other element being documented). Is it worth adding a title to the doc section to aid the reader?
