15.3 自動生成 API 文件（cargo doc）#

cargo doc              # 產生文件到 target/doc
cargo doc --open       # 產生後自動開啟瀏覽器
cargo doc --no-deps    # 只產生自己的 crate，不包含相依套件

/// 將兩個數值相加。
///
/// # 範例
///
/// ```
/// assert_eq!(add(2, 2), 4);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

//! # 堆疊實作
//!
//! 這個模組提供一個以 `Vec` 為基礎的 LIFO 堆疊。
//!
//! ```
//! use stacker::Stack;
//!
//! let mut s = Stack::new();
//! s.push(1);
//! assert_eq!(s.pop(), Some(1));
//! ```

pub struct Stack {
    items: Vec<i32>,
}

/**
 * 計算集合的平均值。
 *
 * 若集合為空則回傳 `None`。
 */
pub fn mean(values: &[f64]) -> Option<f64> {
    if values.is_empty() {
        return None;
    }
    Some(values.iter().sum::<f64>() / values.len() as f64)
}

/// # 警告
///
/// > 這個函式會直接覆寫目標檔案，請在呼叫前確認路徑正確。
pub fn overwrite(path: &str) -> std::io::Result<()> {
    std::fs::write(path, b"")
}

/// # 範例
///
/// 這個範例需要網路連線，因此只編譯不執行。
///
/// ```rust,no_run
/// let resp = reqwest::blocking::get("https://example.com")?.text()?;
/// println!("{resp}");
/// # Ok::<(), reqwest::Error>(())
/// ```
pub fn fetch(url: &str) -> Option<String> {
    None
}

/// 內部使用的快速路徑，不屬於公開 API。
#[doc(hidden)]
pub fn __fast_path_v2(buf: &mut [u8]) -> usize {
    buf.len()
}

/// # 複雜度
///
/// 時間複雜度與空間複雜度皆為 O(n)。

rustdoc --edition 2021 src/lib.rs -o target/doc
rustdoc --test src/lib.rs    # 只執行文件測試

cargo doc --no-deps    # 先本地確認
cargo publish          # 上傳到 crates.io

/// # Safety
///
/// 呼叫者必須保證 `ptr` 指向至少 `len` 個初始化的 `u8`，
/// 且這段記憶體在呼叫期間不會被其他執行緒存取。
///
/// # Panics
///
/// 若 `len` 為零且 `ptr` 為空指標，函式會 panic。
///
/// # Examples
///
/// ```
/// # use stacker::read_first;
/// let data = [1u8, 2, 3];
/// let first = unsafe { read_first(data.as_ptr(), data.len()) };
/// assert_eq!(first, Some(1));
/// ```
pub unsafe fn read_first(ptr: *const u8, len: usize) -> Option<u8> {
    if len == 0 {
        panic!("len must be positive");
    }
    if ptr.is_null() {
        return None;
    }
    Some(*ptr)
}

//! # Stack
//!
//! 一個以 `Vec` 為基礎的後進先出堆疊。
//!
//! 這個型別刻意保持簡單：它不提供迭代器，也不處理 `Sync`。
//! 若你需要這些能力，`Vec` 本身或 [`std::collections::VecDeque`]
//! 通常是更好的選擇。
//!
//! ## 範例
//!
//! ```
//! use stacker::Stack;
//!
//! let mut s = Stack::new();
//! s.push(1);
//! s.push(2);
//! assert_eq!(s.pop(), Some(2));
//! assert_eq!(s.len(), 1);
//! ```

/// 一個後進先出的堆疊。
#[derive(Debug, Default)]
pub struct Stack<T> {
    items: Vec<T>,
}

impl<T> Stack<T> {
    /// 建立一個空的堆疊。
    ///
    /// # Examples
    ///
    /// ```
    /// use stacker::Stack;
    ///
    /// let s: Stack<i32> = Stack::new();
    /// assert!(s.is_empty());
    /// ```
    pub fn new() -> Self {
        Stack { items: Vec::new() }
    }

    /// 將一個值放上堆疊頂端。
    ///
    /// # Examples
    ///
    /// ```
    /// use stacker::Stack;
    ///
    /// let mut s = Stack::new();
    /// s.push("hello");
    /// ```
    pub fn push(&mut self, value: T) {
        self.items.push(value);
    }

    /// 取出堆疊頂端的值，若堆疊為空則回傳 `None`。
    ///
    /// # Examples
    ///
    /// ```
    /// use stacker::Stack;
    ///
    /// let mut s = Stack::new();
    /// assert_eq!(s.pop(), None);
    /// s.push(1);
    /// assert_eq!(s.pop(), Some(1));
    /// ```
    pub fn pop(&mut self) -> Option<T> {
        self.items.pop()
    }

    /// 回傳堆疊中元素的數量。
    pub fn len(&self) -> usize {
        self.items.len()
    }

    /// 若堆疊中沒有任何元素則回傳 `true`。
    pub fn is_empty(&self) -> bool {
        self.items.is_empty()
    }
}