Start Coding

Subjects

JAVASCRIPTHTMLCSSPYTHONSQLJAVACPPCSHARPPHPTYPESCRIPTCRUBYGOSWIFTKOTLINRUSTRBASHSCALAOBJECTIVE-CDARTPERLLUAMATLABXMLJSONMARKDOWNASSEMBLYLATEXYAMLSOLIDITYBLOCKCHAIN

Topics

Rust Basics

Introduction to RustInstalling RustRust SyntaxRust VariablesRust Data TypesRust ConstantsRust FunctionsRust CommentsRust OperatorsRust Control Flow

Ownership and Borrowing

Rust Ownership ConceptRust ReferencesRust Borrowing RulesRust LifetimesRust Move SemanticsRust Copy Types

Rust Structs and Enums

Rust StructsRust MethodsRust Associated FunctionsRust EnumsRust Pattern MatchingRust Option EnumRust Result Enum

Rust Collections

Rust VectorsRust StringsRust Hash MapsRust ArraysRust SlicesRust Iterators

Rust Error Handling

Rust Panic!Rust Result<T, E>Rust Propagating ErrorsRust Custom Error TypesRust Unwrap and Expect

Rust Generics and Traits

Rust Generic TypesRust Generic FunctionsRust Trait DefinitionsRust Trait ImplementationsRust Trait BoundsRust Associated Types

Rust Modules and Packages

Rust Module SystemRust CratesRust WorkspacesRust Use KeywordRust Visibility RulesRust External Dependencies

Rust Concurrency

Rust ThreadsRust Message PassingRust Shared StateRust Sync and Send TraitsRust Atomic TypesRust Mutex and RwLock

Rust Advanced Topics

Rust Unsafe CodeRust Advanced TraitsRust Advanced TypesRust MacrosRust FFI (Foreign Function Interface)Rust Asynchronous Programming

Rust Testing and Documentation

Rust Unit TestsRust Integration TestsRust Documentation TestsRust Benchmark TestsRust Documentation Comments

Rust Ecosystem

Rust Cargo Package ManagerRust Standard LibraryRust Community and ResourcesRust Popular CratesRust Web DevelopmentRust Systems Programming

Rust Documentation Tests

Documentation tests are a unique and powerful feature in Rust that allow developers to write and run tests directly within their code documentation. This ensures that code examples remain accurate and functional as the codebase evolves.

Purpose and Benefits

The primary purpose of documentation tests is to maintain the quality and correctness of code examples in your documentation. They offer several benefits:

  • Ensure code examples are always up-to-date
  • Catch errors in documentation before they reach users
  • Serve as additional unit tests for your codebase
  • Encourage developers to write clear, concise examples

Writing Documentation Tests

To write a documentation test in Rust, you simply include a code example in your doc comments using the triple backtick syntax. Here's a basic example:


/// Adds two numbers and returns the result.
///
/// # Examples
///
/// ```
/// let result = my_crate::add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

In this example, the code within the triple backticks will be executed as a test when you run cargo test.

Advanced Features

Rust's documentation tests support several advanced features:

1. Hiding Lines from Documentation

You can hide certain lines from the generated documentation while still including them in the test by adding a # at the beginning of the line:


/// ```
/// # use my_crate::MyStruct;
/// let my_struct = MyStruct::new();
/// assert!(my_struct.is_valid());
/// ```

2. Specifying Failure

If you want to demonstrate that certain code should fail, you can use the should_panic attribute:


/// ```should_panic
/// // This code should panic
/// panic!("This is an example of a failing test");
/// ```

Best Practices

  • Keep examples concise and focused on demonstrating specific functionality
  • Use realistic variable names and values in your examples
  • Include both successful and error cases where appropriate
  • Run cargo test regularly to ensure all documentation tests pass

Integration with Rust's Testing Framework

Documentation tests are fully integrated with Rust's testing framework. They run alongside your unit tests and integration tests when you execute cargo test. This seamless integration ensures that your documentation remains accurate and your code examples stay functional.

Conclusion

Documentation tests are a powerful tool in the Rust ecosystem, bridging the gap between documentation and code. By leveraging this feature, you can maintain high-quality documentation that always reflects the current state of your codebase. As you continue your Rust journey, consider exploring related topics such as documentation comments and benchmark tests to further enhance your Rust development skills.