# 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`:

```rust
//! # 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

```rust
/// 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

```rust
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

```rust
/// # 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:

```rust
/// 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