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).

functions/_fish_deps_pm_upgrade.fish

@@ -1,8 +1,23 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Upgrade an already-installed package via the system PM.
-# Usage: _fish_deps_pm_upgrade <pkg>
+# SYNOPSIS
+#   _fish_deps_pm_upgrade <pkg>
+#
+# DESCRIPTION
+#   Upgrades an installed package via the detected system package manager,
+#   running with sudo where required. Supports paru, yay, pacman, apt, brew,
+#   pkg, dnf, and yum.
+#
+# ARGUMENTS
+#   pkg  The package name to upgrade
+#
+# RETURNS
+#   0  Package upgraded successfully
+#   1  No supported package manager found
+#
+# EXAMPLE
+#   _fish_deps_pm_upgrade ripgrep
 function _fish_deps_pm_upgrade --argument-names pkg
     set -l pm (_fish_deps_detect_pm)
     if test -z "$pm"