You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**Rule: Use doc test features to ensure examples remain accurate and demonstrate different scenarios.**
42
+
Why: Doc tests are automatically run by `cargo test`, ensuring examples never become outdated. Use different doc test attributes to show various use cases and error conditions.
43
+
44
+
**Run doc tests with:** `cargo test --doc` or `cargo test` (includes all tests)
45
+
46
+
**Doc test best practices:**
47
+
```rust
48
+
/// Parses configuration from various sources.
49
+
///
50
+
/// # Examples
51
+
///
52
+
/// Basic usage:
53
+
/// ```
54
+
/// let config = parse_config("app.toml")?;
55
+
/// assert!(config.port > 0);
56
+
/// # Ok::<(), ConfigError>(())
57
+
/// ```
58
+
///
59
+
/// This example doesn't run but shows the API:
60
+
/// ```no_run
61
+
/// let config = parse_config("/etc/myapp/config.toml")?;
62
+
/// deploy_with_config(config);
63
+
/// # Ok::<(), Box<dyn std::error::Error>>(())
64
+
/// ```
65
+
///
66
+
/// Demonstrating error handling:
67
+
/// ```should_panic
68
+
/// let config = parse_config("nonexistent.toml").unwrap();
**Rule: Every public function, struct, and module must have rustdoc comments.**
70
-
Why: Documentation is part of the API contract. Good docs prevent misuse, reduce support burden, and make your code maintainable. Include examples and error conditions.
112
+
**Rule: Every public function, struct, and module must have rustdoc comments with working code examples.**
113
+
Why: Documentation is part of the API contract. Good docs prevent misuse, reduce support burden, and make your code maintainable. Code examples are automatically tested by `cargo test`, ensuring documentation stays accurate.
71
114
72
-
**Every public item needs rustdoc:**
115
+
**Every public item needs rustdoc with examples:**
73
116
```rust
74
117
/// Represents a user in the system.
75
118
///
76
119
/// # Examples
120
+
///
121
+
/// Creating a valid user:
77
122
/// ```
78
123
/// let user = User::new("alice@example.com", "Alice Smith")?;
0 commit comments