169 lines
3.9 KiB
Markdown
169 lines
3.9 KiB
Markdown
# 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
|