# 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**
    - 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.
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
```