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