Revisiting the Comment Standard: NatSpec or Rust

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):

Meanwhile NatSpec is used with:

NatSpec or Rust?

So what do you prefer? Stick with NatSpec? Move to Rust-like comments? Create Cairo’s own “DaddySpec” standard? Sound off!

I am 100% for Rust like doc!!!
I think we could even leverage cargo doc tooling maybe

This is definitely something we’ll welcome being built-into Scarb! Because I believe everyone would appreciate having scarb doc :slight_smile:

100% behind rust-like doc. It’d be great to have it built into Scarb too :slight_smile:

+1 for Rust-like comments!

Great initiative and writeup! Really liked it :slight_smile:

Some comments on the SNIP-8 proposal:

1. Contract documentation

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

mod MyContract {

    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");
    /// ```
    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?