Rust Tiếng Việt

Doc comments

Doc comments sẽ được Compiler parse thành HTML documentation khi render document bằng cargo doc.

#![allow(unused)]
fn main() {
/// Generate library docs for the following item.
//! Generate library docs for the enclosing item.
}

Doc comments sẽ cực kỳ hữu ích cho project lớn và cần một hệ thống document chính xác và up to date.

//! sẽ generate doc cho crate/mod trong file hiện tại.

#![crate_name = "playground"]

/// A human being is represented here
pub struct Person {
    /// A person must have a name, no matter how much Juliet may hate it
    name: String,
}

impl Person {
    /// Returns a person with the name given them
    ///
    /// # Arguments
    ///
    /// * `name` - A string slice that holds the name of the person
    ///
    /// # Examples
    ///
    /// ```
    /// // You can have rust code between fences inside the comments
    /// // If you pass --test to `rustdoc`, it will even test it for you!
    /// use doc::Person;
    /// let person = Person::new("name");
    /// ```
    pub fn new(name: &str) -> Person {
        Person {
            name: name.to_string(),
        }
    }

    /// Gives a friendly hello!
    ///
    /// Says "Hello, [name]" to the `Person` it is called on.
    pub fn hello(&self) {
        println!("Hello, {}!", self.name);
    }
}

fn main() {
    let john = Person::new("John");

    john.hello();
}

Chúng ta có thể thậm chí comment lại example code hoặc cách sử dụng một function nào đó, code này cũng sẽ được compile và test, đảm bảo được code và document luôn luôn chính xác với nhau, một giải pháp khá thông minh.

#![allow(unused)]
fn main() {
/// Adds one to the number given.
///
/// # Examples
///
/// ```
/// let arg = 5;
/// let answer = my_crate::add_one(arg);
///
/// assert_eq!(6, answer);
/// ```
pub fn add_one(x: i32) -> i32 {
    x + 1
}
}