Comments in Starknet contracts

Starknet Development
,
#1

Hi,

It would be nice to have a standardized format for comments which can be used for docs, frontend UX in dapps, block explorers etc. We can take inspiration from NatSpec for solidity and vyper.
https://docs.soliditylang.org/en/v0.8.11/natspec-format.html

I do not have a strict solution to follow at this moment, but wanted to start this discussion. Like solidity, we can use something in this format:

# @notice Transfer `amount` tokens from caller to `recipient`
# @dev _transfer has all the checks and logic
# @param recipient The address to transfer to
# @param amount The amount to be transferred
# @return success If the transfer was successful or not
@external
func transfer{
        syscall_ptr : felt*, 
        pedersen_ptr : HashBuiltin*,
        range_check_ptr
    }(recipient: felt, amount: Uint256) -> (success: felt):
    let (sender) = get_caller_address()
    _transfer(sender, recipient, amount)

    # Cairo equivalent to 'return (true)'
    return (1)
end
11 Likes
#2

I agree with this and I just visited the forum to suggest exactly this!

I think natspec like solidity (epytext in python?) is quite easy to learn and I would use that over one of the many formats used in Python (numpy-style, google-style, sphinx-style).

In the future it would be nice for tools to display the documentation alongside functions (e.g. in the explorer or wallet)

5 Likes