Merge pull request 'fix: split dops/docker, fix header doc gaps from Job 3 findings' (#135) from fix/dops-docker-and-header-gaps into main

functions/check_fish_deps.fish

@@ -11,6 +11,9 @@
 #   Backwards-compatibility wrapper that delegates to fish-deps status to
 #   report which fish shell dependencies are installed or missing.
 #
+# EXIT STATUS
+#   Exit status of `fish-deps status`
+#
 # EXAMPLE
 #   check_fish_deps
 function check_fish_deps --description 'Check all fish-related dependencies'

functions/claude-docs.fish

@@ -12,6 +12,9 @@
 #   README.md, ensuring all features and examples are accurate and pruning
 #   obsolete content.
 #
+# EXIT STATUS
+#   Exit status of the `claude` invocation
+#
 # EXAMPLE
 #   claude-docs
 function claude-docs --description 'Claude-code: Sync README with recent changes'

functions/claude-pr.fish

@@ -12,6 +12,9 @@
 #   branch, write a Conventional Commit, run verification, push, and open a
 #   pull request with a manual verification checklist.
 #
+# EXIT STATUS
+#   Exit status of the `claude` invocation
+#
 # EXAMPLE
 #   claude-pr
 function claude-pr --description 'Claude-code: New branch, commit, push, and PR'

functions/cleanup.fish

@@ -11,6 +11,10 @@
 #   Identifies and removes Arch Linux orphan packages using pacman. Logs
 #   package names and versions to ~/.removed_orphans before removal.
 #
+# EXIT STATUS
+#   0        No orphans found, or orphans removed successfully
+#   Nonzero  `sudo pacman -Rns` failed
+#
 # EXAMPLE
 #   cleanup
 function cleanup --description 'Log orphans to ~/.removed_orphans and remove them'

functions/docker.fish

@@ -0,0 +1,41 @@
+# Copyright (C) 2026 Rootiest
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# CATEGORY
+#   12-ai-and-developer-tools
+#
+# DEPENDENCIES
+#   dops
+#
+# SYNOPSIS
+#   docker [subcommand] [args...]
+#
+# DESCRIPTION
+#   Wrapper for docker that intercepts the ps subcommand and redirects it to
+#   the dops function for enhanced container listing. All other subcommands,
+#   and a bare invocation with no subcommand, are passed through to the real
+#   docker binary.
+#
+# ARGUMENTS
+#   subcommand  Docker subcommand (ps is redirected to dops)
+#   args...     Arguments forwarded to docker or dops
+#
+# EXIT STATUS
+#   Exit status of dops (for ps), or of the real docker binary otherwise
+#
+# EXAMPLE
+#   docker ps
+#   docker
+function docker --description 'Execute docker, redirecting ps to the enhanced dops listing'
+    if test -z "$argv[1]"
+        command docker
+        return
+    end
+
+    switch $argv[1]
+        case ps
+            dops $argv[2..-1]
+        case '*'
+            command docker $argv[1..-1]
+    end
+end

functions/dops.fish

@@ -4,27 +4,28 @@
 # CATEGORY
 #   12-ai-and-developer-tools
 #
+# DEPENDENCIES
+#   docker
+#
 # SYNOPSIS
-#   docker [subcommand] [args...]
+#   dops [args...]
 #
 # DESCRIPTION
-#   Wrapper for docker that intercepts the ps subcommand and redirects it to
+#   Enhanced container listing: runs docker ps with a clean custom table
-#   the dops function for enhanced container listing. All other subcommands are
+#   (Names, Image, Status, Ports) instead of docker's noisier default
-#   passed through to the real docker binary.
+#   columns. Extra arguments (e.g. -a) are forwarded to docker ps.
 #
 # ARGUMENTS
-#   subcommand  Docker subcommand (ps is redirected to dops)
+#   args...  Arguments forwarded to `docker ps`
-#   args...     Arguments forwarded to docker or dops
+#
+# EXIT STATUS
+#   Exit status of `docker ps`
 #
 # EXAMPLE
-#   docker ps
+#   dops
-function docker --description 'Execute docker'
+#   dops -a
-    if test -n "$argv[1]"
+function dops --description 'Enhanced, formatted docker ps listing'
-        switch $argv[1]
+    __fish_help_header (status current-function) $argv; and return 0
-            case ps
+
-                dops $argv[2..-1]
+    command docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}' $argv
-            case '*'
-                command docker $argv[1..-1]
-        end
-    end
 end

functions/fast.fish

@@ -33,6 +33,9 @@
 #   Displays a styled message indicating that the fast command is unavailable
 #   and suggests using fast-cli instead.
 #
+# EXIT STATUS
+#   0  Always
+#
 # EXAMPLE
 #   fast
 function fast --description 'Placeholder for future fast utility'

functions/fzf-update.fish

@@ -11,6 +11,10 @@
 #   Installs or upgrades fzf from git HEAD into ~/.fzf. Pulls the latest
 #   changes if ~/.fzf already exists, or clones the repository if not.
 #
+# EXIT STATUS
+#   0        fzf installed or updated successfully
+#   Nonzero  git or the fzf install script failed
+#
 # EXAMPLE
 #   fzf-update
 function fzf-update --description 'Install or upgrade fzf from git HEAD'

functions/gip.fish

@@ -11,6 +11,9 @@
 #   Fetches and prints both the public IPv4 and IPv6 addresses using
 #   icanhazip.com. Shows "Not detected" for any address that times out.
 #
+# EXIT STATUS
+#   0  Always (network failures print "Not detected" instead of failing)
+#
 # EXAMPLE
 #   gip
 function gip --description 'Show all public IP addresses'

functions/gip4.fish

@@ -10,6 +10,9 @@
 # DESCRIPTION
 #   Fetches and prints the machine's public IPv4 address using icanhazip.com.
 #
+# EXIT STATUS
+#   Exit status of curl
+#
 # EXAMPLE
 #   gip4
 function gip4 --wraps='curl' --description 'Get public IPv4 address'

functions/hist.fish

@@ -14,6 +14,10 @@
 #   Searches fish history interactively using fzf, inserts the selected command
 #   into the command line, and copies it to the clipboard via wl-copy.
 #
+# EXIT STATUS
+#   0  Command selected and inserted, or fzf was cancelled
+#   1  Disabled by __fish_config_op_integrations
+#
 # EXAMPLE
 #   hist
 function hist --description 'Search fish history and put it in the prompt'

functions/lD.fish

@@ -14,6 +14,9 @@
 # ARGUMENTS
 #   args...  Arguments forwarded to the listing command
 #
+# EXIT STATUS
+#   Exit status of eza, lsd, or ls, whichever ran
+#
 # EXAMPLE
 #   lD ~/projects
 function lD --description 'List directories only'

functions/limine-edit.fish

@@ -13,6 +13,9 @@
 #   files tracked by sbctl. Combines the edit and sign steps into a single
 #   command.
 #
+# EXIT STATUS
+#   0  Always (individual step failures are not propagated)
+#
 # EXAMPLE
 #   limine-edit
 function limine-edit --description 'Safely edit and re-verify Limine configuration'

functions/lock.fish

@@ -10,6 +10,9 @@
 # DESCRIPTION
 #   Locks the current desktop session using loginctl lock-session.
 #
+# EXIT STATUS
+#   Exit status of `loginctl lock-session`
+#
 # EXAMPLE
 #   lock
 function lock --wraps='loginctl' --description 'alias lock=loginctl'

functions/lsr.fish

@@ -14,6 +14,9 @@
 # ARGUMENTS
 #   args...  Arguments forwarded to the listing command
 #
+# EXIT STATUS
+#   Exit status of eza, lsd, or ls, whichever ran
+#
 # EXAMPLE
 #   lsr ~/projects
 function lsr --description 'Reversed time-sorted listing'

functions/lss.fish

@@ -14,6 +14,9 @@
 # ARGUMENTS
 #   args...  Arguments forwarded to the listing command
 #
+# EXIT STATUS
+#   Exit status of eza, lsd, or ls, whichever ran
+#
 # EXAMPLE
 #   lss ~/downloads
 function lss --description 'Size-sorted listing'

functions/lstree.fish

@@ -14,6 +14,9 @@
 # ARGUMENTS
 #   args...  Arguments forwarded to the listing command
 #
+# EXIT STATUS
+#   Exit status of eza, lsd, or ls, whichever ran
+#
 # EXAMPLE
 #   lstree ~/projects/myapp
 function lstree --description 'Full recursive tree listing'

functions/lt.fish

@@ -14,6 +14,9 @@
 # ARGUMENTS
 #   args...  Arguments forwarded to the listing command
 #
+# EXIT STATUS
+#   Exit status of eza, lsd, or ls, whichever ran
+#
 # EXAMPLE
 #   lt ~/projects
 function lt --description 'Tree listing, depth 2'

functions/ltr.fish

@@ -15,6 +15,9 @@
 # ARGUMENTS
 #   args...  Arguments forwarded to the listing command
 #
+# EXIT STATUS
+#   Exit status of eza, lsd, or ls, whichever ran
+#
 # EXAMPLE
 #   ltr ~/projects
 function ltr --description 'Reversed time-sorted listing'

functions/lx.fish

@@ -14,6 +14,9 @@
 # ARGUMENTS
 #   args...  Arguments forwarded to the listing command
 #
+# EXIT STATUS
+#   Exit status of eza, lsd, or ls, whichever ran
+#
 # EXAMPLE
 #   lx ~/projects
 function lx --description 'Extension-sorted listing'

functions/ports.fish

@@ -11,6 +11,9 @@
 #   Lists all active TCP listeners on the system using lsof, showing
 #   port numbers and addresses without hostname resolution.
 #
+# EXIT STATUS
+#   Exit status of `lsof`
+#
 # EXAMPLE
 #   ports
 function ports --wraps='sudo' --description 'Show active network listeners'

functions/qr.fish

@@ -15,6 +15,9 @@
 # ARGUMENTS
 #   text...  Text to encode; reads from stdin if omitted
 #
+# EXIT STATUS
+#   Exit status of qrencode, or curl if qrencode is unavailable
+#
 # EXAMPLE
 #   qr "https://example.com"
 #   echo "hello" | qr

functions/screensleep.fish

@@ -11,6 +11,9 @@
 #   Turns off the display after a 1-second delay by invoking the KDE
 #   PowerDevil "Turn Off Screen" global shortcut via busctl.
 #
+# EXIT STATUS
+#   Exit status of `busctl`
+#
 # EXAMPLE
 #   screensleep
 function screensleep --description 'Turn off the display using KDE PowerDevil'

functions/sponge_filter_secrets.fish

@@ -31,7 +31,6 @@
 # EXAMPLE
 #   # Register with sponge (done automatically by conf.d/sponge_privacy.fish):
 #   set -U -a sponge_filters sponge_filter_secrets
-
 function sponge_filter_secrets --argument-names command
     # Find all exported variables with security-sensitive names
     set -l sensitive_vars (set --names --export | string match --regex -- \

functions/steam-dl.fish

@@ -11,6 +11,9 @@
 #   Launches Steam with systemd-inhibit to prevent the system from idling
 #   or sleeping during active downloads.
 #
+# EXIT STATUS
+#   Exit status of `steam` (via systemd-inhibit)
+#
 # EXAMPLE
 #   steam-dl
 function steam-dl --description 'Run Steam while inhibiting system sleep'

functions/swapstat.fish

@@ -12,6 +12,9 @@
 #   zRAM compression ratio, zRAM device details (via zramctl), and
 #   active swap priority (via swapon).
 #
+# EXIT STATUS
+#   0  Always
+#
 # EXAMPLE
 #   swapstat
 function swapstat --description 'View colorized zRAM and swappiness status'

functions/tmux-clean.fish

@@ -11,6 +11,9 @@
 #   Kills all detached (unattached) tmux sessions, leaving any currently
 #   attached sessions running.
 #
+# EXIT STATUS
+#   0  Always
+#
 # EXAMPLE
 #   tmux-clean
 function tmux-clean --description 'Kill all tmux sessions except the current one'