41 lines
2.0 KiB
Markdown
41 lines
2.0 KiB
Markdown
# Rustdoc Plan
|
|
|
|
## Files Missing or Incomplete Rustdoc
|
|
|
|
This plan tracks public modules, structs, functions, and traits that lack comprehensive `///` documentation comments. Rustdoc should cover:
|
|
|
|
- Module-level docs explaining purpose and usage.
|
|
- Public struct/enum/trait docs with fields/variants.
|
|
- Public function/method docs with params, returns, and examples.
|
|
- Error handling and edge cases where relevant.
|
|
|
|
### High Priority (Core Public API)
|
|
- `src/services/item_service.rs`: Missing docs for `ItemService` methods like `get_item`, `save_item`. Add examples for usage.
|
|
- `src/services/async_item_service.rs`: `AsyncItemService` needs async-specific docs, including blocking task explanations.
|
|
- `src/modes/server/common.rs`: `AppState`, `ApiResponse<T>`, and query structs lack full param/return docs.
|
|
- `src/compression_engine/mod.rs`: `CompressionEngine` trait needs comprehensive docs for all methods.
|
|
- `src/filter_plugin/mod.rs`: `FilterPlugin` trait and `FilterChain` need usage examples.
|
|
|
|
### Medium Priority (Utilities and Helpers)
|
|
- `src/common/status.rs`: `StatusInfo` and related structs need schema docs.
|
|
- `src/db.rs`: All public functions like `open`, `insert_item` need error context and examples.
|
|
- `src/config.rs`: `Settings` and sub-structs need deserialization notes.
|
|
- `src/meta_plugin/mod.rs`: `MetaPlugin` trait methods need more examples; `process_metadata_outputs` lacks cases.
|
|
|
|
### Low Priority (Internal/Helper)
|
|
- `src/services/compression_service.rs`: `CompressionService` methods are simple but need brief docs.
|
|
- `src/services/filter_service.rs`: `FilterService` needs plugin registration docs.
|
|
- `src/modes/common.rs`: Utility functions like `format_size` need inline docs.
|
|
|
|
## Generation Plan
|
|
1. Run `cargo doc --no-deps` to generate and inspect current docs.
|
|
2. Add `///` comments to missing items.
|
|
3. Use `cargo doc --open` to verify.
|
|
4. Ensure all public items are documented before release.
|
|
|
|
## Commands
|
|
```bash
|
|
cargo doc --no-deps # Generate docs without deps
|
|
cargo doc --open # Open generated docs in browser
|
|
```
|