Documentation should be concise, focused, and maintainable. Follow these principles: 1. Keep examples short and demonstrate one concept at a time 2. Avoid redundant documentation across related items
Documentation should be concise, focused, and maintainable. Follow these principles:
Good example:
/// A mutex guard for accessing protected data.
///
/// See [`Mutex`] for more usage examples.
#[must_use = "if unused the Mutex will immediately unlock"]
pub struct MutexGuard<'a, T: ?Sized + 'a> {
/// The underlying mutex reference
lock: &'a Mutex<T>,
}
Problematic example:
/// A mutex guard for accessing protected data.
/// This implements RAII pattern for mutex locking.
/// When dropped, it automatically unlocks the mutex.
///
/// # Examples
///
/// ```
/// // Long example duplicating documentation from Mutex
/// let mutex = Mutex::new(0);
/// let guard = mutex.lock();
/// *guard = 2;
/// // Many more lines...
/// ```
pub struct MutexGuard<'a, T: ?Sized + 'a> {
lock: &'a Mutex<T>, // Undocumented field
}
Enter the URL of a public GitHub repository