346 lines
14 KiB
Markdown
346 lines
14 KiB
Markdown
# Rustdoc Plan
|
|
|
|
## Files with Incomplete Rustdoc
|
|
|
|
Based on the provided code files, several contain incomplete or missing Rustdoc comments (i.e., `///` documentation blocks) for public structs, enums, traits, functions, and modules. Rustdoc is considered "incomplete" here if:
|
|
|
|
- Public items (e.g., structs, enums, traits, functions, or modules that are exported or not prefixed with `_`) lack any doc comment.
|
|
- Existing doc comments are partial (e.g., missing examples, returns, or errors sections) or inconsistent.
|
|
- Private items are ignored unless they are part of a public API (e.g., impl blocks for public traits).
|
|
|
|
Private helpers (e.g., internal `fn` without `pub`) are not flagged, as they don't require doc comments for rustdoc generation. I focused on public-facing code. Below is a summary by file, listing the incomplete items. Files with fully documented public APIs (or no public items) are omitted.
|
|
|
|
### Files with Incomplete Rustdoc
|
|
|
|
1. **src/modes/server/pages.rs** [DONE]
|
|
- `ListQueryParams` struct: Missing doc comment entirely.
|
|
- `default_sort()` and `default_count()` functions: No doc comments.
|
|
- `add_routes()` function: Partial doc (missing examples or errors).
|
|
- `list_items()` function: No doc comment.
|
|
- `build_item_list()` function: No doc comment.
|
|
- `style_css()` function: No doc comment.
|
|
- `show_item()` function: No doc comment.
|
|
- `build_item_details()` function: No doc comment.
|
|
- Overall: The file has some inline comments but lacks comprehensive rustdoc for the public API.
|
|
|
|
2. **src/db.rs** [DONE]
|
|
- `Item`, `Tag`, and `Meta` structs: Partial docs (fields documented, but missing overall struct description or examples).
|
|
- `open()` function: Good doc, but missing error examples.
|
|
- `insert_item()` function: Partial (missing full error details).
|
|
- `create_item()` function: Partial.
|
|
- `add_tag()` and `add_meta()` functions: No docs.
|
|
- `update_item()` and `delete_item()` functions: No docs.
|
|
- `query_delete_meta()` and `query_upsert_meta()` functions: No docs.
|
|
- `store_meta()` function: Partial.
|
|
- `insert_tag()` and `delete_item_tags()` functions: No docs.
|
|
- `set_item_tags()` function: Partial.
|
|
- `query_all_items()` and `query_tagged_items()` functions: Partial.
|
|
- `get_items()` function: No doc.
|
|
- `get_items_matching()` function: Partial.
|
|
- `get_item_matching()` function: Partial.
|
|
- `get_item()` and `get_item_last()` functions: Partial.
|
|
- `get_item_tags()` and `get_item_meta()` functions: Partial.
|
|
- `get_item_meta_name()` and `get_item_meta_value()` functions: Partial.
|
|
- `get_tags_for_items()` and `get_meta_for_items()` functions: Partial.
|
|
- Overall: Many CRUD functions lack full docs; the module-level doc is good but individual items are inconsistent.
|
|
|
|
3. **src/meta_plugin/read_rate.rs** [DONE]
|
|
- `ReadRateMetaPlugin` struct: Missing doc comment.
|
|
- `new()` function: Partial (missing full param docs).
|
|
- Impl `MetaPlugin` methods (`is_finalized`, `set_finalized`, `finalize`, `update`, `meta_type`, `outputs`, etc.): No docs.
|
|
- Overall: Lacks docs for the public trait impl.
|
|
|
|
4. **src/filter_plugin/head.rs** [DONE]
|
|
- `HeadBytesFilter` and `HeadLinesFilter` structs: No docs.
|
|
- `new()` functions: Partial.
|
|
- Impl `FilterPlugin` methods (`filter`, `clone_box`, `options`): No docs.
|
|
- Overall: No rustdoc at all for public impl.
|
|
|
|
5. **src/common/binary_detection.rs** [DONE]
|
|
- `check_binary_content_allowed()` function: Partial (missing examples).
|
|
- `is_content_binary()` function: Partial.
|
|
- Overall: Functions lack full error handling docs.
|
|
|
|
6. **src/lib.rs** [DONE]
|
|
- Module re-exports and `init_plugins()` function: No docs.
|
|
- Overall: Library-level docs are minimal.
|
|
|
|
7. **src/services/filter_service.rs** [DONE]
|
|
- `FilterService` struct: Partial doc.
|
|
- `new()`, `create_filter_chain()`, `filter_data()`, `process_with_filter()` methods: Partial or missing.
|
|
- `register_filter_plugin()` and `get_available_filter_plugins()` functions: Partial.
|
|
- Overall: Global registry lacks docs.
|
|
|
|
8. **src/services/item_service.rs** [DONE]
|
|
- `ItemService` struct: Partial.
|
|
- Many methods (`get_item`, `get_item_content`, `get_item_content_info`, `find_item`, `list_items`, `delete_item`, `save_item`, `save_item_from_mcp`, `get_compression_service`, `get_data_path`): Partial or no docs.
|
|
- `FilteringReader` struct and impl `Read`: No docs.
|
|
- Overall: Extensive but inconsistent docs.
|
|
|
|
9. **src/config.rs** [DONE]
|
|
- Enums (`ColumnAlignment`, `ContentArrangement`, `TableStyle`, `TableColor`, `TableAttribute`): Partial or no docs.
|
|
- Structs (`TableConfig`, `ColumnConfig`, `ServerConfig`, `CompressionPluginConfig`, `MetaPluginConfig`, `Settings`): Partial.
|
|
- `new()` method on `Settings`: Partial.
|
|
- Helper methods (`get_server_password`, `server_password`, etc.): No docs.
|
|
- Overall: Config structs need better field-level docs.
|
|
|
|
10. **src/meta_plugin/text.rs** [DONE]
|
|
- `TextMetaPlugin` struct: No doc.
|
|
- `new()` function: No doc.
|
|
- Many helper functions (`count_text_stats`, `perform_binary_detection`, etc.): No docs.
|
|
- Impl `MetaPlugin` methods: No docs.
|
|
- Overall: Complex logic with no rustdoc.
|
|
|
|
11. **src/compression_engine/program.rs** [DONE]
|
|
- `ProgramReader` and `ProgramWriter` structs: Partial (missing full impl docs).
|
|
- `CompressionEngineProgram` struct: Partial.
|
|
- `new()` function: Partial.
|
|
- Impl `CompressionEngine` methods: Partial.
|
|
- Overall: Good but incomplete for trait methods.
|
|
|
|
12. **src/meta_plugin/read_time.rs** [DONE]
|
|
- `ReadTimeMetaPlugin` struct: No doc.
|
|
- `new()` function: Partial.
|
|
- Impl `MetaPlugin` methods: No docs.
|
|
- Overall: Similar to read_rate.rs.
|
|
|
|
13. **src/modes/server/api/common.rs** [DONE]
|
|
- `ResponseBuilder` struct: No doc.
|
|
- `json()` and `binary()` methods: No docs.
|
|
- Overall: Utility without docs.
|
|
|
|
14. **src/compression_engine/lz4.rs** [DONE]
|
|
- `CompressionEngineLZ4` struct: No doc.
|
|
- `new()` function: No doc.
|
|
- Impl `CompressionEngine` methods: No docs.
|
|
|
|
15. **src/meta_plugin/magic.rs** [DONE]
|
|
- `MagicFileMetaPlugin` struct: No doc.
|
|
- `new()` function: Partial.
|
|
- Helper functions (`get_magic_result`, `process_magic_types`): No docs.
|
|
- Impl `MetaPlugin` methods: No docs.
|
|
|
|
16. **src/compression_engine/gzip.rs** [DONE]
|
|
- `CompressionEngineGZip` struct: Partial.
|
|
- `new()` function: Partial.
|
|
- `AutoFinishGzEncoder` struct: Partial.
|
|
- Impl `CompressionEngine` methods: Partial.
|
|
|
|
17. **src/modes/server/common.rs** [DONE]
|
|
- Many structs (`ServerConfig`, `AppState`, `ApiResponse<T>`, `ItemInfoListResponse`, etc.): Partial or no docs.
|
|
- Functions (`check_auth`, `logging_middleware`, `create_auth_middleware`): Partial.
|
|
- Overall: API structs need better schema/docs.
|
|
|
|
18. **src/meta_plugin/user.rs** [DONE]
|
|
- `UserMetaPlugin` struct: Partial.
|
|
- `new()` function: Partial.
|
|
- Helper functions (`get_current_username`, `get_current_groupname`): No docs.
|
|
- Impl `MetaPlugin` methods: Partial.
|
|
|
|
19. **src/modes/diff.rs** [DONE]
|
|
- Functions (`validate_diff_args`, `fetch_and_validate_items`, `setup_diff_paths_and_compression`): No docs.
|
|
|
|
20. **src/modes/get.rs** [DONE]
|
|
- `mode_get()` function: Partial.
|
|
- `TeeReader` struct and impl `Read`: No docs.
|
|
|
|
21. **src/args.rs** [DONE]
|
|
- Structs (`Args`, `ModeArgs`, `ItemArgs`, `OptionsArgs`, `NumberOrString`): Partial.
|
|
- Impl `FromStr` for `NumberOrString`: No doc.
|
|
- `validate()` method on `Args`: No doc.
|
|
|
|
22. **src/parser/filter_parser.rs** [DONE]
|
|
- `FilterParser` struct: No doc.
|
|
- `parse_filter_string()` function: No doc.
|
|
- Tests: No docs needed.
|
|
|
|
23. **src/modes/server/api/mcp.rs** [DONE]
|
|
- `McpRequest` struct: No doc.
|
|
- `handle_mcp_request()` function: No doc.
|
|
|
|
24. **src/filter_plugin/utils.rs** [DONE]
|
|
- `create_filter_chain()` and `parse_number()` functions: Partial.
|
|
|
|
25. **src/modes/list.rs** [DONE]
|
|
- `mode_list()` function: Partial.
|
|
- `ListItem` struct: No doc.
|
|
- Helper functions (`apply_color`, `apply_attribute`, `show_list_structured`): No docs.
|
|
|
|
26. **src/filter_plugin/mod.rs** [DONE]
|
|
- `FilterOption` struct: Partial.
|
|
- `FilterPlugin` trait: Partial.
|
|
- `FilterChain` struct and methods: Partial.
|
|
- `FilterType` enum: No doc.
|
|
- `parse_filter_string()` function: Partial.
|
|
- Helper functions (`create_filter_with_options`, etc.): No docs.
|
|
|
|
27. **src/services/meta_service.rs** [DONE]
|
|
- `MetaService` struct: No doc.
|
|
- Methods (`new`, `get_plugins`, `initialize_plugins`, etc.): Partial.
|
|
|
|
28. **src/modes/server/mcp/mod.rs** [DONE]
|
|
- Duplicate of mcp.rs; `handle_mcp_request()`: No doc.
|
|
|
|
29. **src/modes/generate_config.rs** [DONE]
|
|
- Structs (`DefaultConfig`, etc.): No docs.
|
|
- `mode_generate_config()` function: No doc.
|
|
- Helper `convert_outputs_to_string_map()`: No doc.
|
|
|
|
30. **src/services/async_item_service.rs** [DONE]
|
|
- `AsyncItemService` struct: Partial.
|
|
- Many async methods (`get_item`, `get_item_content`, etc.): Partial or no docs.
|
|
|
|
31. **src/modes/status_plugins.rs** [DONE]
|
|
- `mode_status_plugins()` function: Partial.
|
|
- Helper builders (`build_meta_plugin_table`, etc.): No docs.
|
|
|
|
32. **src/meta_plugin/env.rs** [DONE]
|
|
- `EnvMetaPlugin` struct: No doc.
|
|
- `new()` function: Partial.
|
|
- Impl `MetaPlugin` methods: No docs.
|
|
|
|
33. **src/modes/info.rs** [DONE]
|
|
- `mode_info()` function: Partial.
|
|
- `ItemInfo` struct: No doc.
|
|
- Helpers (`show_item`, `show_item_structured`): No docs.
|
|
|
|
34. **src/modes/server/mcp/server.rs** [DONE]
|
|
- `KeepMcpServer` struct: No doc.
|
|
- `new()` and `handle_request()` methods: No docs.
|
|
|
|
35. **src/filter_plugin/grep.rs** [DONE]
|
|
- `GrepFilter` struct: Partial.
|
|
- `new()` function: Partial.
|
|
- Impl `FilterPlugin` methods: No docs.
|
|
|
|
36. **src/compression_engine.rs**
|
|
- `CompressionType` enum: No doc.
|
|
- `CompressionEngine` trait: Partial.
|
|
- Functions (`get_compression_engine`, `default_compression_type`): Partial.
|
|
|
|
37. **src/modes/delete.rs**
|
|
- `mode_delete()` function: Partial.
|
|
|
|
38. **src/parser/mod.rs**
|
|
- Re-exports: No docs needed.
|
|
|
|
39. **src/meta_plugin/hostname.rs**
|
|
- `HostnameMetaPlugin` struct: Partial.
|
|
- `new()` function: Partial.
|
|
- Helper `get_hostname()`: Partial.
|
|
- Impl `MetaPlugin` methods: Partial.
|
|
|
|
40. **src/filter_parser.rs** (duplicate of filter_parser.rs)
|
|
- Same issues as above.
|
|
|
|
41. **src/services/types.rs** [DONE]
|
|
- `ItemWithMeta` and `ItemWithContent` structs: Partial.
|
|
- `meta_as_map()` method: No doc.
|
|
|
|
42. **src/modes/common.rs** [DONE]
|
|
- `OutputFormat` enum: No doc.
|
|
- `ColumnType` enum: Partial.
|
|
- Functions (`get_meta_from_env`, `format_size`, etc.): Partial.
|
|
|
|
43. **src/services/error.rs** [DONE]
|
|
- `CoreError` enum: Partial variants.
|
|
|
|
44. **src/services/compression_service.rs** [DONE]
|
|
- `CompressionService` struct: Partial.
|
|
- Methods (`new`, `get_item_content`, `stream_item_content`): Partial.
|
|
|
|
45. **src/services/status_service.rs** [DONE]
|
|
- `StatusService` struct: Partial.
|
|
- `generate_status()` method: Partial.
|
|
|
|
46. **src/meta_plugin/exec.rs** [DONE]
|
|
- `MetaPluginExec` struct: Partial.
|
|
- `new()` function: Partial.
|
|
- Impl `MetaPlugin` methods: Partial.
|
|
|
|
47. **src/modes/server/api/mod.rs**
|
|
- `add_routes()` and `add_docs_routes()` functions: No docs.
|
|
|
|
48. **src/compression_engine/none.rs**
|
|
- `CompressionEngineNone` struct: Partial.
|
|
- `new()` function: No doc.
|
|
- Impl `CompressionEngine` methods: Partial.
|
|
|
|
49. **src/meta_plugin/shell.rs**
|
|
- `ShellMetaPlugin` struct: No doc.
|
|
- `new()` function: Partial.
|
|
- Impl `MetaPlugin` methods: No docs.
|
|
|
|
50. **src/common/status.rs**
|
|
- Structs (`FilterPluginInfo`, `StatusInfo`, etc.): No docs.
|
|
- `generate_status_info()` function: Partial.
|
|
|
|
51. **src/plugins.rs**
|
|
- `ProgramWriter` struct: Partial.
|
|
- Impl `Write`: No doc.
|
|
|
|
52. **src/modes/server/api/status.rs**
|
|
- `handle_status()` function: No doc.
|
|
|
|
53. **src/filter_plugin/tail.rs**
|
|
- `TailBytesFilter` and `TailLinesFilter` structs: Partial.
|
|
- `new()` functions: Partial.
|
|
- Impl `FilterPlugin` methods: No docs.
|
|
|
|
54. **src/meta_plugin/mod.rs**
|
|
- `MetaData` and `MetaPluginResponse` structs: Partial.
|
|
- `BaseMetaPlugin` struct: Partial.
|
|
- `MetaPluginType` enum: No doc.
|
|
- `process_metadata_outputs()` function: Partial.
|
|
- `MetaPlugin` trait: Partial.
|
|
- Registry and functions: Partial.
|
|
|
|
55. **src/meta_plugin/keep_pid.rs**
|
|
- `KeepPidMetaPlugin` struct: No doc.
|
|
- `new()` function: Partial.
|
|
- Impl `MetaPlugin` methods: No docs.
|
|
|
|
56. **src/filter_plugin/exec.rs**
|
|
- `ExecFilter` struct: Partial.
|
|
- `new()` function: Partial.
|
|
- Impl `FilterPlugin` methods: No docs.
|
|
|
|
57. **src/modes/save.rs**
|
|
- `validate_save_args()` function: Partial.
|
|
- `TeeReader` struct and impl `Read`: No docs.
|
|
- `mode_save()` function: Partial.
|
|
|
|
58. **src/modes/server/api/item.rs**
|
|
- Many handler functions (`handle_list_items`, `handle_post_item`, etc.): Partial or no docs.
|
|
- Helpers (`check_binary_content_allowed`, etc.): No docs.
|
|
|
|
59. **src/filter_plugin/skip.rs**
|
|
- `SkipBytesFilter` and `SkipLinesFilter` structs: Partial.
|
|
- `new()` functions: Partial.
|
|
- Impl `FilterPlugin` methods: No docs.
|
|
|
|
60. **src/common/is_binary.rs**
|
|
- `is_binary()` function: Partial.
|
|
- Helpers (`has_binary_signature`, `looks_like_utf16`, etc.): No docs.
|
|
|
|
61. **src/services/mod.rs**
|
|
- Re-exports: No docs needed.
|
|
|
|
### Summary
|
|
- **Most Affected Areas**: Service structs/impls (e.g., item_service.rs, filter_service.rs), meta_plugin modules (many lack trait impl docs), compression_engine modules, and API handlers (server/api).
|
|
- **Common Issues**: Missing `@returns`, `@examples`, or `@errors` in existing partial docs; entire public traits/impls undocumented.
|
|
- **Recommendations**: Add `cargo doc --no-deps` to check generation. Focus on public APIs first. Use `#[deny(missing_docs)]` in Cargo.toml for enforcement.
|
|
- **Files Without Issues**: Cargo.toml, filter.pest (grammar), main.rs (minimal), some small utils like plugins.rs.
|
|
|
|
## 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
|
|
```
|