docs(functions): split RETURNS into EXIT STATUS and stdout RETURNS #77

2026-07-26T20:42:20Z

rootiest commented

2026-07-26 20:42:20 +00:00

Summary

Renamed # RETURNS → # EXIT STATUS across all 83 documented functions/*.fish headers. RETURNS previously conflated fish's $status exit code with genuine stdout/printed output (e.g. rm listed 0/1 as if they were print values).
Reintroduced # RETURNS as a distinct label, applied only to the 15 functions that genuinely print something to stdout, with the printed-content prose split out of the old table.
Updated docs/build-manual.py's ENTRY_HEADS so generated docs render Exit Status: before Returns:.
Updated docs/manualtools.py's SECTIONS constant and the repo's AGENTS.md label order / label-usage guidance to match.
Added two docs/verify-manual.py regression tests: EXIT STATUS bodies must never contain stray stdout/printed language, and Returns: must always render after Exit Status: when both are present.
Regenerated docs/fish-config.md (generated concat artifact).

Test plan

python3 docs/verify-manual.py passes 32/32 (pre-existing WARN about 8 functions lacking # CATEGORY is unrelated and expected)
fish -n on a sample of changed function files (e.g. functions/rm.fish, functions/gi.fish) shows no syntax errors
config-help rm and config-help gi in a fish shell show Exit Status: before Returns:, with Returns: describing only printed stdout content
Spot-check man fish-config (after regenerating docs/fish-config.1) for the same ordering
Confirm no function that prints nothing on success gained a spurious Returns: section

## Summary - Renamed `# RETURNS` → `# EXIT STATUS` across all 83 documented `functions/*.fish` headers. `RETURNS` previously conflated fish's `$status` exit code with genuine stdout/printed output (e.g. `rm` listed `0`/`1` as if they were print values). - Reintroduced `# RETURNS` as a distinct label, applied only to the 15 functions that genuinely print something to stdout, with the printed-content prose split out of the old table. - Updated `docs/build-manual.py`'s `ENTRY_HEADS` so generated docs render `Exit Status:` before `Returns:`. - Updated `docs/manualtools.py`'s `SECTIONS` constant and the repo's `AGENTS.md` label order / label-usage guidance to match. - Added two `docs/verify-manual.py` regression tests: EXIT STATUS bodies must never contain stray stdout/printed language, and Returns: must always render after Exit Status: when both are present. - Regenerated `docs/fish-config.md` (generated concat artifact). ## Test plan - [x] `python3 docs/verify-manual.py` passes 32/32 (pre-existing WARN about 8 functions lacking `# CATEGORY` is unrelated and expected) - [x] `fish -n` on a sample of changed function files (e.g. `functions/rm.fish`, `functions/gi.fish`) shows no syntax errors - [x] `config-help rm` and `config-help gi` in a fish shell show `Exit Status:` before `Returns:`, with `Returns:` describing only printed stdout content - [x] Spot-check `man fish-config` (after regenerating `docs/fish-config.1`) for the same ordering - [x] Confirm no function that prints nothing on success gained a spurious `Returns:` section

rootiest added 1 commit 2026-07-26 20:42:21 +00:00

docs(functions): split RETURNS into EXIT STATUS and stdout RETURNS e651566e14

RETURNS previously conflated fish's $status exit code with genuine
stdout/printed output, e.g. rm listing "0/1" as if they were print
values rather than exit codes. Rename RETURNS to EXIT STATUS across
all 83 documented functions, and reintroduce RETURNS as a distinct
label reserved for the 15 functions that actually print to stdout.

Update build-manual.py's ENTRY_HEADS to render Exit Status before
Returns, manualtools.py's SECTIONS constant, and AGENTS.md's label
order and label-usage guidance to match. Add two verify-manual.py
regression tests: EXIT STATUS bodies must never contain stray
stdout/printed language, and Returns: must always render after
Exit Status: when both are present. Regenerate docs/fish-config.md.

rootiest merged commit b6034114ad into main

2026-07-26 20:44:31 +00:00

rootiest deleted branch docs-exit-status-returns

2026-07-26 20:45:02 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: rootiest/fish-config#77