docs: Replace PLAN.md content with Rustdoc generation plan

Co-authored-by: aider (openai/andrew/openrouter/sonoma-sky-alpha) <aider@aider.chat>

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 items (e.g., structs, enums, traits, functions, or modules that are exported or not prefixed with `_`) lack any doc comment.
-- Public struct/enum/trait docs with fields/variants.
+- Existing doc comments are partial (e.g., missing examples, returns, or errors sections) or inconsistent.
-- Public function/method docs with params, returns, and examples.
+- Private items are ignored unless they are part of a public API (e.g., impl blocks for public traits).
-- Error handling and edge cases where relevant.
 
-### High Priority (Core Public API)
+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.
-- `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)
+### Files with Incomplete Rustdoc
-- `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)
+1. **src/modes/server/pages.rs**
-- `src/services/compression_service.rs`: `CompressionService` methods are simple but need brief docs.
+   - `ListQueryParams` struct: Missing doc comment entirely.
-- `src/services/filter_service.rs`: `FilterService` needs plugin registration docs.
+   - `default_sort()` and `default_count()` functions: No doc comments.
-- `src/modes/common.rs`: Utility functions like `format_size` need inline docs.
+   - `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<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**
+    - `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.