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

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).
This commit is contained in:
2026-06-05 20:18:49 -04:00
parent 0396d685fd
commit 1341e2559e
108 changed files with 1520 additions and 148 deletions
+24 -2
View File
@@ -1,8 +1,30 @@
# Copyright (C) 2026 Rootiest
# SPDX-License-Identifier: AGPL-3.0-or-later
# Always installs bindings for insert and default mode for simplicity and b/c it has almost no side-effect
# https://gitter.im/fish-shell/fish-shell?at=60a55915ee77a74d685fa6b1
# SYNOPSIS
# fzf_configure_bindings [--directory=<key>] [--git_log=<key>] [--git_status=<key>]
# [--history=<key>] [--processes=<key>] [--variables=<key>] [-h]
#
# DESCRIPTION
# Installs key bindings for fzf.fish in both insert and default vi modes.
# Each binding can be overridden with a custom key or disabled by passing an
# empty string. Only runs in interactive mode.
#
# ARGUMENTS
# --directory=key Override the directory search binding (default: Ctrl-Alt-F)
# --git_log=key Override the git log search binding (default: Ctrl-Alt-L)
# --git_status=key Override the git status binding (default: Ctrl-Alt-S)
# --history=key Override the history search binding (default: Ctrl-R)
# --processes=key Override the processes search binding (default: Ctrl-Alt-P)
# --variables=key Override the variables search binding (default: Ctrl-V)
# -h, --help Show help message
#
# RETURNS
# 0 Bindings installed or help shown
# 22 Invalid option or positional argument provided
#
# EXAMPLE
# fzf_configure_bindings --history=ctrl-h
function fzf_configure_bindings --description "Installs the default key bindings for fzf.fish with user overrides passed as options."
# no need to install bindings if not in interactive mode or running tests
status is-interactive || test "$CI" = true; or return