From 91fc41f56efde0040634a10cb846d8d44bb8b52a Mon Sep 17 00:00:00 2001 From: Andrew Phillips Date: Thu, 11 Sep 2025 12:14:05 -0300 Subject: [PATCH] docs: remove outdated rustdoc plan --- PLAN.md | 330 -------------------------------------------------------- 1 file changed, 330 deletions(-) diff --git a/PLAN.md b/PLAN.md index e68904d..e69de29 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1,330 +0,0 @@ -# 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: [DONE] - - `default_sort()` and `default_count()` functions: [DONE] - - `add_routes()` function: [DONE] - - `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: [DONE] - - `open()` function: [DONE] - - `insert_item()` function: [DONE] - - `create_item()` function: [DONE] - - `add_tag()` and `add_meta()` functions: [DONE] - - `update_item()` and `delete_item()` functions: [DONE] - - `query_delete_meta()` and `query_upsert_meta()` functions: [DONE] - - `store_meta()` function: [DONE] - - `insert_tag()` and `delete_item_tags()` functions: [DONE] - - `set_item_tags()` function: [DONE] - - `query_all_items()` and `query_tagged_items()` functions: [DONE] - - `get_items()` function: [DONE] - - `get_items_matching()` function: [DONE] - - `get_item_matching()` function: [DONE] - - `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. - -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`, `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** [DONE] - - `CompressionType` enum: No doc. - - `CompressionEngine` trait: Partial. - - Functions (`get_compression_engine`, `default_compression_type`): Partial. - -37. **src/modes/delete.rs** [DONE] - - `mode_delete()` function: Partial. - -38. **src/parser/mod.rs** [DONE] - - 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** [DONE] - - `add_routes()` and `add_docs_routes()` functions: No docs. - -48. **src/compression_engine/none.rs** [DONE] - - `CompressionEngineNone` struct: Partial. - - `new()` function: No doc. - - Impl `CompressionEngine` methods: Partial. - -49. **src/meta_plugin/shell.rs** [DONE] - - `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** [DONE] - - `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 -```