docs(functions): add DEPENDENCIES sections to doc headers #168

2026-09-23T02:21:50Z

rootiest commented

2026-09-23 02:21:50 +00:00

Summary

Adds a # DEPENDENCIES section to every function's doc header that has real dependencies to declare, alongside the existing # CLASSIFICATION section — documenting what each function needs for full functionality: other repo functions it calls, and/or external CLI tools it uses (required, or optional-with-graceful-fallback like rm's use of trash).

89 of 114 manual-documented functions (functions/*.fish with # CATEGORY) now carry a DEPENDENCIES section — the ~22 that already had one, plus ~67 newly added. The remaining functions genuinely have none (pure fish logic, or an unguarded/unwhitelisted external tool — see Notes).
Section is placed per the existing canonical header order (CATEGORY, COMPONENT, DEPENDENCIES, CLASSIFICATION, SYNOPSIS, ...), matching docs/manualtools.py's SECTIONS tuple and every pre-existing example.
A dependency already expressed by that function's own uses-shadow(...)/bypasses-shadow(...)/self-limiting(...) CLASSIFICATION tag (e.g. cat.fish calling ls) is not duplicated into DEPENDENCIES — that system already documents the C1 shadow-command relationship (see docs/function-classification-schema.md).
functions/rm.fish gets DEPENDENCIES: trash — the exact case this feature was requested for (enhanced trash-based delete, falls back cleanly to plain rm when trash isn't installed).

Docs

docs/fish-config.md regenerated via python3 docs/build-manual.py --concat -o docs/fish-config.md to pick up the new sections (the man page and Starlight site are left for CI, per CONTRIBUTING.md).
CONTRIBUTING.md's header-label table updated: the DEPENDENCIES row only mentioned "other functions," but ~20 pre-existing examples (and this PR) also use it for external tools — reworded to match actual practice.
docs/verify-manual.py's test_dependencies_resolve broadened to recognize this repo's other existence-check idioms (command -q, command -v, which, not just type -q) and dng2avif.fish's dynamic for cmd in magick ffmpeg avifenc exiftool; type -q $cmd loop — several genuine dependencies (eza, lsd, fastfetch, neofetch, fd, ps, shuf, magick, ffmpeg, avifenc, exiftool, ...) were only ever guarded one of those other ways, not literally via type -q <name>.

Notes

A handful of functions have a real external-tool dependency that isn't guarded by type -q/command -q/command -v/which anywhere in the tree yet (so it can't be cited without breaking test_dependencies_resolve), and were deliberately left out rather than inventing a guard: e.g. nohup (bkg.fish, detach.fish), gitui (gitui.fish), mpv/vlc (play-media.fish), systemd-inhibit (steam-dl.fish, wake-lock.fish), wezterm/konsole (split.fish, spwin.fish, tab.fish), among a few others. Happy to follow up on any of these if you'd like the guard added.

Verification

python3 docs/build-manual.py --concat -o docs/fish-config.md — regenerates cleanly.
python3 docs/verify-manual.py — 84/84 passed, test_dependencies_resolve included, test_render_registry_is_valid_fish_and_round_trips included (this sandbox has fish installed).
fish tests/run-tests.fish — 757/757 assertions passed, exit 0, zero FAIL lines.
fish -n / fish_indent on touched files — all changed .fish files match fish_indent output byte-for-byte; no executable code changed, only comment headers.

Transferred from GitHub mirror PR rootiest/fish-config#3 — closed there to avoid a duplicate; canonical PR lives here.

## Summary Adds a `# DEPENDENCIES` section to every function's doc header that has real dependencies to declare, alongside the existing `# CLASSIFICATION` section — documenting what each function needs for full functionality: other repo functions it calls, and/or external CLI tools it uses (required, or optional-with-graceful-fallback like `rm`'s use of `trash`). - **89 of 114 manual-documented functions** (`functions/*.fish` with `# CATEGORY`) now carry a `DEPENDENCIES` section — the ~22 that already had one, plus ~67 newly added. The remaining functions genuinely have none (pure fish logic, or an unguarded/unwhitelisted external tool — see Notes). - Section is placed per the existing canonical header order (`CATEGORY, COMPONENT, DEPENDENCIES, CLASSIFICATION, SYNOPSIS, ...`), matching `docs/manualtools.py`'s `SECTIONS` tuple and every pre-existing example. - A dependency already expressed by that function's own `uses-shadow(...)`/`bypasses-shadow(...)`/`self-limiting(...)` `CLASSIFICATION` tag (e.g. `cat.fish` calling `ls`) is **not** duplicated into `DEPENDENCIES` — that system already documents the C1 shadow-command relationship (see `docs/function-classification-schema.md`). - `functions/rm.fish` gets `DEPENDENCIES: trash` — the exact case this feature was requested for (enhanced trash-based delete, falls back cleanly to plain `rm` when `trash` isn't installed). ## Docs - `docs/fish-config.md` regenerated via `python3 docs/build-manual.py --concat -o docs/fish-config.md` to pick up the new sections (the man page and Starlight site are left for CI, per `CONTRIBUTING.md`). - `CONTRIBUTING.md`'s header-label table updated: the `DEPENDENCIES` row only mentioned "other functions," but ~20 pre-existing examples (and this PR) also use it for external tools — reworded to match actual practice. - `docs/verify-manual.py`'s `test_dependencies_resolve` broadened to recognize this repo's other existence-check idioms (`command -q`, `command -v`, `which`, not just `type -q`) and `dng2avif.fish`'s dynamic `for cmd in magick ffmpeg avifenc exiftool; type -q $cmd` loop — several genuine dependencies (`eza`, `lsd`, `fastfetch`, `neofetch`, `fd`, `ps`, `shuf`, `magick`, `ffmpeg`, `avifenc`, `exiftool`, ...) were only ever guarded one of those other ways, not literally via `type -q <name>`. ## Notes A handful of functions have a real external-tool dependency that isn't guarded by `type -q`/`command -q`/`command -v`/`which` anywhere in the tree yet (so it can't be cited without breaking `test_dependencies_resolve`), and were deliberately left out rather than inventing a guard: e.g. `nohup` (`bkg.fish`, `detach.fish`), `gitui` (`gitui.fish`), `mpv`/`vlc` (`play-media.fish`), `systemd-inhibit` (`steam-dl.fish`, `wake-lock.fish`), `wezterm`/`konsole` (`split.fish`, `spwin.fish`, `tab.fish`), among a few others. Happy to follow up on any of these if you'd like the guard added. ## Verification - [x] `python3 docs/build-manual.py --concat -o docs/fish-config.md` — regenerates cleanly. - [x] `python3 docs/verify-manual.py` — 84/84 passed, `test_dependencies_resolve` included, `test_render_registry_is_valid_fish_and_round_trips` included (this sandbox has `fish` installed). - [x] `fish tests/run-tests.fish` — 757/757 assertions passed, exit 0, zero `FAIL` lines. - [x] `fish -n` / `fish_indent` on touched files — all changed `.fish` files match `fish_indent` output byte-for-byte; no executable code changed, only comment headers. --- _Transferred from GitHub mirror PR [rootiest/fish-config#3](https://github.com/rootiest/fish-config/pull/3) — closed there to avoid a duplicate; canonical PR lives here._

rootiest added the Kind/Documentation Area/Functions Area/Docs labels 2026-09-23 02:22:02 +00:00

rootiest added 1 commit 2026-09-23 02:22:37 +00:00

docs: add DEPENDENCIES sections to function doc headers fceddfc43f

Documents what each function needs for full functionality -- other
repo functions it calls, and external CLI tools it uses or falls
back gracefully without (e.g. rm/trash, ls/eza+lsd) -- matching the
existing CLASSIFICATION convention's placement and the ~20 functions
that already carried this label.

Also broadens verify-manual.py's dependency-resolution check to
recognize this repo's other existence-check idioms (command -q,
command -v, which -- not just type -q) and dng2avif's dynamic
type -q $cmd loop, since several genuine dependencies (eza, lsd,
fastfetch, fd, ps, ...) are only ever guarded that way.

rootiest force-pushed claude/function-docs-dependencies-bfnnag from fd64335207 to fceddfc43f

2026-09-23 02:22:37 +00:00

Compare

rootiest merged commit 3bbda31eff into main

2026-09-23 02:31:11 +00:00

rootiest deleted branch claude/function-docs-dependencies-bfnnag

2026-09-23 02:31:12 +00:00

rootiest referenced this issue from a commit

2026-09-23 02:40:50 +00:00

fix: guard and document the external tools PR #168 flagged as unguarded

rootiest referenced this pull request

2026-09-23 02:41:00 +00:00