keep/PLAN.md

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 - first 10 items]

   • 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.
2. Add /// comments to missing items.
3. Use cargo doc --open to verify.
4. Ensure all public items are documented before release.

Commands

cargo doc --no-deps  # Generate docs without deps
cargo doc --open     # Open generated docs in browser