docs(functions): standardize all function doc blocks to UNIX man-page style #30

2026-06-06T00:19:23Z

rootiest commented

2026-06-06 00:19:23 +00:00

Summary

Replaced all ad-hoc inline comments (single-line descriptions, old ### banners, bare # alias ... lines) between the license header and function declaration in every project-owned functions/*.fish file with standardized UNIX man-page style doc blocks.
All 99 files bearing the # Copyright (C) 2026 Rootiest / SPDX-License-Identifier: AGPL-3.0-or-later headers were processed.
Each block now includes SYNOPSIS, DESCRIPTION, ARGUMENTS (where applicable), RETURNS (where applicable), and EXAMPLE.
No executable shell logic, variable names, or exit codes were modified.
Completes Task #6 from AGENTS.md — Retroactive Function Documentation Standardization.

Manual Verification

Open any updated function file (e.g. functions/rm.fish) and confirm the doc block between the license header and function declaration follows the SYNOPSIS/DESCRIPTION/ARGUMENTS/RETURNS/EXAMPLE format.
Confirm no function has two doc blocks or a mix of old and new format.
Run fish --no-execute functions/<name>.fish on a few files and confirm no parse errors.
Start a new Fish shell and confirm all overridden commands (ls, rm, ping, etc.) still behave as expected.
Confirm AGENTS.md Task #6 checkboxes are all marked [x].

## Summary - Replaced all ad-hoc inline comments (single-line descriptions, old `###` banners, bare `# alias ...` lines) between the license header and `function` declaration in every project-owned `functions/*.fish` file with standardized UNIX man-page style doc blocks. - All 99 files bearing the `# Copyright (C) 2026 Rootiest` / `SPDX-License-Identifier: AGPL-3.0-or-later` headers were processed. - Each block now includes `SYNOPSIS`, `DESCRIPTION`, `ARGUMENTS` (where applicable), `RETURNS` (where applicable), and `EXAMPLE`. - No executable shell logic, variable names, or exit codes were modified. - Completes **Task #6** from `AGENTS.md` — Retroactive Function Documentation Standardization. ## Manual Verification - [x] Open any updated function file (e.g. `functions/rm.fish`) and confirm the doc block between the license header and `function` declaration follows the SYNOPSIS/DESCRIPTION/ARGUMENTS/RETURNS/EXAMPLE format. - [x] Confirm no function has two doc blocks or a mix of old and new format. - [x] Run `fish --no-execute functions/<name>.fish` on a few files and confirm no parse errors. - [x] Start a new Fish shell and confirm all overridden commands (`ls`, `rm`, `ping`, etc.) still behave as expected. - [x] Confirm `AGENTS.md` Task #6 checkboxes are all marked `[x]`.

rootiest added 1 commit 2026-06-06 00:19:24 +00:00

docs(functions): standardize all function doc blocks to UNIX man-page style 1341e2559e

Replace all ad-hoc inline comments between license headers and function
declarations with consistent SYNOPSIS / DESCRIPTION / ARGUMENTS / RETURNS /
EXAMPLE blocks across all 99 project-owned functions/ files. No executable
logic, variable names, or exit codes were modified.

Completes Task #6 from AGENTS.md (Retroactive Function Documentation
Standardization).

rootiest merged commit 0dfd75923d into main

2026-06-06 00:20:17 +00:00

rootiest deleted branch docs/standardize-function-doc-blocks

2026-06-06 00:20:18 +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#30