Summary
Most of the exported (__all__) surface of three core modules lacks docstrings, despite being part of the project's documented public API contract, and this gap isn't caught by CI.
Details
Per docs/api-stability.md, "documented names in the explicitly exported modules... are public as well," making these part of the supported contract:
lib/python/base_cli/history.py — 14 of 19 __all__ members undocumented: build_finished_record (58), utc_now (54), format_timestamp (250), duration_ms (255), display_command (259), parse_positive_int (264), parse_finished_history_record_line (273), optional_string (285), optional_int (289), redact_history_argv (306), redact_history_text (310), compact_optional_path (317), compact_path (323), compact_home_text (327).lib/python/base_cli/command_protocol.py — 5 of 13: CommandProtocolError (28), FieldSpec (33), dumps_record (134), dumps_records (149), loads_records (176).lib/python/base_cli/context.py — 4 of 8: get_current_context (185), set_current_context (167), reset_current_context (173), recover_current_context (180).
tests/test_public_api.py::test_entry_points_have_docstrings only asserts docstrings for 5 hardcoded symbols (App, Context, attach, get_command_app, run_app), so this gap isn't caught by CI and can silently regress further.
Impact
get_current_context() is arguably the single most commonly used helper in the framework (used throughout the README's own examples) and has no docstring; the three core wire-protocol functions (dumps_record/dumps_records/loads_records) are undocumented despite being the serialization contract consumers depend on.
Suggested fix
Add docstrings to the listed functions/classes, and extend test_entry_points_have_docstrings (or add a generic __all__-wide docstring-presence test) so future additions to the public API can't silently regress this.
Summary
Most of the exported (
__all__) surface of three core modules lacks docstrings, despite being part of the project's documented public API contract, and this gap isn't caught by CI.Details
Per
docs/api-stability.md, "documented names in the explicitly exported modules... are public as well," making these part of the supported contract:lib/python/base_cli/history.py— 14 of 19__all__members undocumented:build_finished_record(58),utc_now(54),format_timestamp(250),duration_ms(255),display_command(259),parse_positive_int(264),parse_finished_history_record_line(273),optional_string(285),optional_int(289),redact_history_argv(306),redact_history_text(310),compact_optional_path(317),compact_path(323),compact_home_text(327).lib/python/base_cli/command_protocol.py— 5 of 13:CommandProtocolError(28),FieldSpec(33),dumps_record(134),dumps_records(149),loads_records(176).lib/python/base_cli/context.py— 4 of 8:get_current_context(185),set_current_context(167),reset_current_context(173),recover_current_context(180).tests/test_public_api.py::test_entry_points_have_docstringsonly asserts docstrings for 5 hardcoded symbols (App,Context,attach,get_command_app,run_app), so this gap isn't caught by CI and can silently regress further.Impact
get_current_context()is arguably the single most commonly used helper in the framework (used throughout the README's own examples) and has no docstring; the three core wire-protocol functions (dumps_record/dumps_records/loads_records) are undocumented despite being the serialization contract consumers depend on.Suggested fix
Add docstrings to the listed functions/classes, and extend
test_entry_points_have_docstrings(or add a generic__all__-wide docstring-presence test) so future additions to the public API can't silently regress this.