Yorumlar

Tüm programcılar kodlarını anlaşılır kılmaya çalışır, ancak bazen ek açıklama gerekebilir. Bu durumlarda, programcılar kaynak kodlarında derleyicinin yoksayacağı ancak kaynak kodunu okuyanların faydalı bulabileceği yorumlar bırakır.

İşte basit bir yorum:

// hello, world

Cairo'da, özdeş yorum stili bir yorumu iki eğik çizgi ile başlatır ve yorum satırın sonuna kadar devam eder. Tek bir satırın ötesine uzanan yorumlar için, her satırda // eklemeniz gerekir, şöyle ki:

// So we’re doing something complicated here, long enough that we need
// multiple lines of comments to do it! Whew! Hopefully, this comment will
// explain what’s going on.

Yorumlar, kod içeren satırların sonuna da yerleştirilebilir:

fn main() -> felt252 {
    1 + 4 // return the sum of 1 and 4
}

Ancak onları daha sık bu formatta, yorumunun açıkladığı kodun üzerinde ayrı bir satırda göreceksiniz:

fn main() -> felt252 {
    // this function performs a simple addition
    1 + 4
}

Item-level Documentation

Item-level documentation comments refer to specific items such as functions, implementations, traits, etc. They are prefixed with three slashes (///). These comments provide a detailed description of the item, examples of usage, and any conditions that might cause a panic. In case of functions, the comments may also include separate sections for parameter and return value descriptions.

/// Returns the sum of `arg1` and `arg2`.
/// `arg1` cannot be zero.
///
/// # Panics
///
/// This function will panic if `arg1` is `0`.
///
/// # Examples
///
/// ```
/// let a: felt252 = 2;
/// let b: felt252 = 3;
/// let c: felt252 = add(a, b);
/// assert(c == a + b, "Should equal a + b");
/// ```
fn add(arg1: felt252, arg2: felt252) -> felt252 {
    assert(arg1 != 0, 'Cannot be zero');
    arg1 + arg2
}

Module Documentation

Module documentation comments provide an overview of the entire module, including its purpose and examples of use. These comments are meant to be placed above the module they're describing and are prefixed with //!. This type of documentation gives a broad understanding of what the module does and how it can be used.

//! # my_module and implementation
//!
//! This is an example description of my_module and some of its features.
//!
//! # Examples
//!
//! ```
//! mod my_other_module {
//!   use path::to::my_module;
//!
//!   fn foo() {
//!     my_module.bar();
//!   }
//! }
//! ```
mod my_module { // rest of implementation...
}