diff options
| author | Tommaso Negri <me@tommasongr.com> | 2026-10-14 22:13:55 +0200 |
|---|---|---|
| committer | Tommaso Negri <me@tommasongr.com> | 2026-10-14 22:13:55 +0200 |
| commit | ed506be5076c500f19e8a39e89867ee54007577e (patch) | |
| tree | 1e9f8471ef5186f57e1a41080a7d66dd47aec4be /tasks | |
| parent | 8aacd1f753c7ef21a7e1173cc08c5b0a85a94c6b (diff) | |
| download | bar-ed506be5076c500f19e8a39e89867ee54007577e.tar.gz bar-ed506be5076c500f19e8a39e89867ee54007577e.zip | |
improve and clarify documentation
Diffstat (limited to 'tasks')
| -rw-r--r-- | tasks/20261014-192338/TASK.md | 21 |
1 files changed, 20 insertions, 1 deletions
diff --git a/tasks/20261014-192338/TASK.md b/tasks/20261014-192338/TASK.md index b649850..ac79e76 100644 --- a/tasks/20261014-192338/TASK.md +++ b/tasks/20261014-192338/TASK.md @@ -1,6 +1,6 @@ # Align comments and documentation with actual guarantees -- STATUS: OPEN +- STATUS: CLOSED - PRIORITY: 180 - TAGS: review,docs @@ -13,3 +13,22 @@ Approach: Explain concrete contracts simply: source configuration catches Swift Completion checks: Cross-check each claim against code and tests, build DocC with the project's documented workflow, and correct stale symbol links. This task can be revisited after related fixes; do not pre-document functionality that has not landed. Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. + +## Completion + +Updated README and DocC to distinguish compile-time Swift checks from runtime +shell and color behavior, require successful empty stdout for hiding, describe +line parsing and actual stderr/error handling, and explain the limits of the +30-second termination request. Cell and Block comments distinguish identity from +content updates; Cell documents its content-derived ID and BlockView's current +positional rendering. Config and HEX comments describe runtime color parsing, +unsupported-length fallback, partial scanning, and disabled repeating intervals. +Highlighting documentation qualifies prefix stripping and invalid levels against +the current parser. HEX remains implemented and its symbol links remain valid; +Color.hex(_:) is formatted as code because DocC does not emit a linkable page for +that extension member in this catalog. + +Validation: reviewed claims against the current implementations and existing +hover/lifetime tests; `make -C Sources/bar/bar.docc build` completed without +warnings or unresolved symbol links; `swift test` passed all four existing tests; +`git diff --check` passed. Runtime behavior is unchanged. |