rustytorch/docs/DOCUMENTATION_STYLE.md

RustyTorch++ Documentation Style Guide

This guide defines documentation standards for the RustyTorch++ project.

Crate-Level Documentation

Every crate should have comprehensive //! documentation in lib.rs:

//! # Crate Name
//!
//! Brief one-line description of what this crate does.
//!
//! ## Features
//!
//! - Feature 1 description
//! - Feature 2 description
//!
//! ## Usage
//!
//! ```rust
//! use rtx_crate::Type;
//!
//! let example = Type::new();
//! ```
//!
//! ## Architecture
//!
//! Describe the main components and how they interact.

Struct/Enum Documentation

/// A brief one-sentence description.
///
/// More detailed description if needed. Explain the purpose
/// and common use cases.
///
/// # Examples
///
/// ```rust
/// let instance = MyStruct::new(42);
/// assert_eq!(instance.value(), 42);
/// ```
pub struct MyStruct {
    /// Description of this field.
    pub field: u32,
}

Method Documentation

impl MyStruct {
    /// Creates a new instance with the given value.
    ///
    /// # Arguments
    ///
    /// * `value` - The initial value for the struct.
    ///
    /// # Returns
    ///
    /// A new `MyStruct` instance.
    ///
    /// # Examples
    ///
    /// ```rust
    /// let s = MyStruct::new(42);
    /// ```
    pub fn new(value: u32) -> Self {
        Self { field: value }
    }

    /// Performs an operation that may fail.
    ///
    /// # Arguments
    ///
    /// * `input` - The input to process.
    ///
    /// # Returns
    ///
    /// The processed result.
    ///
    /// # Errors
    ///
    /// Returns `Error::InvalidInput` if the input is negative.
    /// Returns `Error::Overflow` if the result exceeds `u32::MAX`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// let result = instance.process(10)?;
    /// ```
    pub fn process(&self, input: i32) -> Result<u32, Error> {
        // ...
    }
}

Documentation Sections

Use these sections as appropriate:

Section	When to Use
# Arguments	For functions with non-obvious parameters
# Returns	When return value needs explanation
# Errors	For fallible functions (Result return)
# Panics	If the function can panic
# Examples	Always include for public APIs
# Safety	For unsafe functions

Doc-Tests

• All examples should be runnable (avoid ignore unless necessary)
• Use # prefix to hide setup boilerplate
• Test both success and error paths

/// # Examples
///
/// ```rust
/// # use rtx_tensor::Tensor;
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let tensor = Tensor::zeros([2, 3])?;
/// assert_eq!(tensor.shape(), &[2, 3]);
/// # Ok(())
/// # }
/// ```

Links and Cross-References

Use intra-doc links for cross-referencing:

/// See [`OtherStruct`] for related functionality.
///
/// This implements the [`crate::traits::Compute`] trait.
///
/// For tensor operations, see the [`rtx_tensor`] crate.

Best Practices

1. Start with a verb - "Creates", "Returns", "Computes", "Validates"
2. Be concise - First line should fit in IDE hover tooltips
3. Show, don't tell - Prefer examples over lengthy explanations
4. Document invariants - What must be true before/after calling
5. Update with code - Keep docs in sync with implementation

Lints

The workspace has these documentation lints enabled:

• missing_docs - Warns on undocumented public items
• missing_errors_doc - Warns when # Errors section is missing (deferred)
• missing_panics_doc - Warns when # Panics section is missing (deferred)

Priority Order

Focus documentation efforts in this order:

1. Core crates - rtx-tensor, rtx-runtime, rtx-autograd
2. Production crates - rtx-serving-api, rtx-inference
3. Training crates - rtx-transformers, rtx-distributed
4. Model crates - rtx-vision, rtx-nlg, rtx-multimodal