diff --git a/PLAN.md b/PLAN.md index 54cd142..8cf83d3 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1,31 +1,336 @@ # Rustdoc Plan -## Files Missing or Incomplete Rustdoc +## Files with Incomplete Rustdoc -This plan tracks public modules, structs, functions, and traits that lack comprehensive `///` documentation comments. Rustdoc should cover: +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: -- 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. +- 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). -### 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`, 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. +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. -### 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. +### Files with Incomplete Rustdoc -### 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. +1. **src/modes/server/pages.rs** + - `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** + - `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** + - `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** + - `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** + - `check_binary_content_allowed()` function: Partial (missing examples). + - `is_content_binary()` function: Partial. + - Overall: Functions lack full error handling docs. + +6. **src/lib.rs** + - Module re-exports and `init_plugins()` function: No docs. + - Overall: Library-level docs are minimal. + +7. **src/services/filter_service.rs** + - `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** + - `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** + - 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** + - `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** + - `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** + - `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** + - `ResponseBuilder` struct: No doc. + - `json()` and `binary()` methods: No docs. + - Overall: Utility without docs. + +14. **src/compression_engine/lz4.rs** + - `CompressionEngineLZ4` struct: No doc. + - `new()` function: No doc. + - Impl `CompressionEngine` methods: No docs. + +15. **src/meta_plugin/magic.rs** (appears to be a duplicate/old version of magic_file.rs) + - `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** + - `CompressionEngineGZip` struct: Partial. + - `new()` function: Partial. + - `AutoFinishGzEncoder` struct: Partial. + - Impl `CompressionEngine` methods: Partial. + +17. **src/modes/server/common.rs** + - Many structs (`ServerConfig`, `AppState`, `ApiResponse`, `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** + - `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** + - Functions (`validate_diff_args`, `fetch_and_validate_items`, `setup_diff_paths_and_compression`): No docs. + +20. **src/modes/get.rs** + - `mode_get()` function: Partial. + - `TeeReader` struct and impl `Read`: No docs. + +21. **src/args.rs** + - 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** + - `FilterParser` struct: No doc. + - `parse_filter_string()` function: No doc. + - Tests: No docs needed. + +23. **src/modes/server/api/mcp.rs** + - `McpRequest` struct: No doc. + - `handle_mcp_request()` function: No doc. + +24. **src/filter_plugin/utils.rs** + - `create_filter_chain()` and `parse_number()` functions: Partial. + +25. **src/modes/list.rs** + - `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** + - `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** + - `MetaService` struct: No doc. + - Methods (`new`, `get_plugins`, `initialize_plugins`, etc.): Partial. + +28. **src/modes/server/mcp/mod.rs** + - Duplicate of mcp.rs; `handle_mcp_request()`: No doc. + +29. **src/modes/generate_config.rs** + - 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** + - `AsyncItemService` struct: Partial. + - Many async methods (`get_item`, `get_item_content`, etc.): Partial or no docs. + +31. **src/modes/status_plugins.rs** + - `mode_status_plugins()` function: Partial. + - Helper builders (`build_meta_plugin_table`, etc.): No docs. + +32. **src/meta_plugin/env.rs** + - `EnvMetaPlugin` struct: No doc. + - `new()` function: Partial. + - Impl `MetaPlugin` methods: No docs. + +33. **src/modes/info.rs** + - `mode_info()` function: Partial. + - `ItemInfo` struct: No doc. + - Helpers (`show_item`, `show_item_structured`): No docs. + +34. **src/modes/server/mcp/server.rs** + - `KeepMcpServer` struct: No doc. + - `new()` and `handle_request()` methods: No docs. + +35. **src/filter_plugin/grep.rs** + - `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** + - `ItemWithMeta` and `ItemWithContent` structs: Partial. + - `meta_as_map()` method: No doc. + +42. **src/modes/common.rs** + - `OutputFormat` enum: No doc. + - `ColumnType` enum: Partial. + - Functions (`get_meta_from_env`, `format_size`, etc.): Partial. + +43. **src/services/error.rs** + - `CoreError` enum: Partial variants. + +44. **src/services/compression_service.rs** + - `CompressionService` struct: Partial. + - Methods (`new`, `get_item_content`, `stream_item_content`): Partial. + +45. **src/services/status_service.rs** + - `StatusService` struct: Partial. + - `generate_status()` method: Partial. + +46. **src/meta_plugin/exec.rs** + - `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.