42 lines
1.7 KiB
Markdown
42 lines
1.7 KiB
Markdown
|
# Add Missing Rust Documentation
|
||
|
|
|
||
|
|
Run cargo clippy to identify items missing documentation, then add appropriate doc comments to all flagged items.
|
||
|
|
|
||
|
|
## Instructions
|
||
|
|
|
||
|
|
1. Run `cargo clippy --all-targets` to find missing documentation warnings
|
||
|
|
2. Parse the output to identify all items (functions, structs, enums, modules, etc.) that need documentation
|
||
|
|
3. For each missing doc comment:
|
||
|
|
- Read the relevant file to understand the context
|
||
|
|
- Add appropriate /// doc comments for public items
|
||
|
|
- Add appropriate //! module-level doc comments where needed
|
||
|
|
- Follow Rust documentation conventions:
|
||
|
|
- First line is a brief summary (imperative mood: "Creates", "Returns", not "Create", "Return")
|
||
|
|
- Add "# Errors" section for functions returning Result
|
||
|
|
- Add "# Panics" section if function can panic
|
||
|
|
- Add "# Examples" for complex public APIs
|
||
|
|
- Use #[must_use] attribute where appropriate
|
||
|
|
4. After adding all documentation, run cargo clippy again to verify no missing docs warnings remain
|
||
|
|
5. Report summary of what was documented
|
||
|
|
|
||
|
|
## Documentation Style Guidelines
|
||
|
|
|
||
|
|
- Modules (//!): Describe the module's purpose and main types/functions
|
||
|
|
- Structs/Enums: Describe what the type represents
|
||
|
|
- Functions/Methods: Describe what it does, parameters, return value
|
||
|
|
- Fields: Document public fields with ///
|
||
|
|
- Keep it concise but informative
|
||
|
|
- Use markdown formatting for code examples
|
||
|
|
|
||
|
|
## Example Output Format
|
||
|
|
|
||
|
|
After completion, report:
|
||
|
|
|
||
|
|
Added documentation to:
|
||
|
|
- Module: src/domain/relay/entity.rs (module-level docs)
|
||
|
|
- Struct: Relay (3 public methods documented)
|
||
|
|
- Function: toggle() at src/domain/relay/entity.rs:XX
|
||
|
|
|
||
|
|
Total: X items documented
|
||
|
|
Clippy warnings resolved: X
|