Documentation should clearly explain the purpose, behavior, and relationships between code components using accessible terminology. This helps other developers understand the code without needing to dig into implementations.
Documentation should clearly explain the purpose, behavior, and relationships between code components using accessible terminology. This helps other developers understand the code without needing to dig into implementations.
Key practices:
Example of improved documentation:
/// A tuple length specification.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum TupleLength {
/// A tuple with exactly `n` elements
Fixed(usize),
/// A variable-length tuple with `prefix_len` required elements at the start
/// and `suffix_len` required elements at the end
Variable(usize, usize),
}
/// Return true if this is a type that is always fully static (has no dynamic part;
/// represents a single set of possible values.)
///
/// Note: This function may have false negatives (return false for some static types),
/// but should not have false positives (will never return true for non-static types).
fn is_fully_static(&self) -> bool {
// implementation...
}
When documenting methods that may panic or fail under certain conditions, clearly state these conditions:
/// Get the AST node for this class.
///
/// # Panics
/// Panics if the provided module belongs to a different file than this class.
fn node<'ast>(self, db: &'db dyn Db, module: &'ast ParsedModuleRef) -> &'ast ast::StmtClassDef {
// implementation...
}
Comprehensive documentation reduces the learning curve for new contributors and helps prevent bugs caused by misunderstandings about component behavior.
Enter the URL of a public GitHub repository