From 8eb0826843cddca44299b7ac34bc2415154ba9ef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ville=20Skytt=C3=A4?= <ville.skytta@iki.fi>
Date: Mon, 8 May 2023 07:55:42 +0300
Subject: [PATCH 1/4] refactor(cvs): `_cvs_entries` -> `_comp_cmd_cvs__entries`

---
 completions/cvs | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)

diff --git a/completions/cvs b/completions/cvs
index 03fd7457a5d..46a5b492d7a 100644
--- a/completions/cvs
+++ b/completions/cvs
@@ -1,7 +1,6 @@
 # cvs(1) completion                                        -*- shell-script -*-
 
-# TODO: rename per API conventions
-_cvs_entries()
+_comp_cmd_cvs__entries()
 {
     local prefix=${cur%/*}/ IFS=$'\n'
     [[ -e ${prefix-}CVS/Entries ]] || prefix=""
@@ -159,7 +158,7 @@ _comp_cmd_cvs()
             esac
 
             if [[ $cur != -* ]]; then
-                _cvs_entries
+                _comp_cmd_cvs__entries
                 [[ ! $cur ]] && files=(!(CVS)) ||
                     files=($(command ls -d "${cur}"* 2>/dev/null))
                 local f
@@ -201,7 +200,7 @@ _comp_cmd_cvs()
             if [[ $cur == -* ]]; then
                 _comp_cmd_cvs__command_options "$1" "$mode"
             else
-                _cvs_entries
+                _comp_cmd_cvs__entries
                 ((${#entries[@]})) &&
                     _comp_compgen -- -W '"${entries[@]}"'
             fi
@@ -212,7 +211,7 @@ _comp_cmd_cvs()
             if [[ $cur == -* ]]; then
                 _comp_cmd_cvs__command_options "$1" "$mode"
             else
-                _cvs_entries
+                _comp_cmd_cvs__entries
                 ((${#entries[@]})) &&
                     _comp_compgen -- -W '"${entries[@]}"'
             fi
@@ -272,7 +271,7 @@ _comp_cmd_cvs()
                     ((${#COMPREPLY[@]})) &&
                         _comp_compgen -- -W '"${COMPREPLY[@]}"'
                 else
-                    _cvs_entries
+                    _comp_cmd_cvs__entries
                     ((${#entries[@]})) &&
                         _comp_compgen -- -W '"${entries[@]}"'
                 fi
@@ -288,7 +287,7 @@ _comp_cmd_cvs()
                 _comp_cmd_cvs__command_options "$1" "$mode"
                 [[ ${COMPREPLY-} == *= ]] && compopt -o nospace
             else
-                _cvs_entries
+                _comp_cmd_cvs__entries
                 ((${#entries[@]})) &&
                     _comp_compgen -- -W '"${entries[@]}"'
             fi
@@ -297,7 +296,7 @@ _comp_cmd_cvs()
             if [[ $cur == -* ]]; then
                 _comp_cmd_cvs__command_options "$1" "$mode"
             else
-                _cvs_entries
+                _comp_cmd_cvs__entries
                 ((${#entries[@]})) &&
                     _comp_compgen -- -W '"${entries[@]}"'
             fi
@@ -359,7 +358,7 @@ _comp_cmd_cvs()
             ;;
         remove)
             if [[ $cur != -* ]]; then
-                _cvs_entries
+                _comp_cmd_cvs__entries
                 if [[ $prev != -f ]]; then
                     # find out what files are missing
                     for i in "${!entries[@]}"; do
@@ -387,7 +386,7 @@ _comp_cmd_cvs()
             if [[ $cur == -* ]]; then
                 _comp_cmd_cvs__command_options "$1" "$mode"
             else
-                _cvs_entries
+                _comp_cmd_cvs__entries
                 ((${#entries[@]})) &&
                     _comp_compgen -- -W '"${entries[@]}"'
             fi

From 1011aba5e53a03a19870f0ec5c8bff243b04b1e1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ville=20Skytt=C3=A4?= <ville.skytta@iki.fi>
Date: Mon, 8 May 2023 08:00:50 +0300
Subject: [PATCH 2/4] chore: make API TODO comments easier to grep

---
 bash_completion      | 82 ++++++++++++++++++++++----------------------
 completions/_modules |  6 ++--
 completions/_yum     |  4 +--
 completions/bts      |  4 +--
 completions/cvs      |  2 +-
 completions/dict     |  2 +-
 completions/mutt     |  4 +--
 completions/openssl  |  2 +-
 completions/tar      | 30 ++++++++--------
 completions/vpnc     |  2 +-
 completions/xrandr   | 12 +++----
 11 files changed, 75 insertions(+), 75 deletions(-)

diff --git a/bash_completion b/bash_completion
index a5a96c991f9..4dbf2a596cb 100644
--- a/bash_completion
+++ b/bash_completion
@@ -927,7 +927,7 @@ _comp__split_longopt()
 # Complete variables.
 # @return  True (0) if variables were completed,
 #          False (> 0) if not.
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _variables()
 {
     if [[ $cur =~ ^(\$(\{[!#]?)?)([A-Za-z0-9_]*)$ ]]; then
@@ -1347,7 +1347,7 @@ _comp_compgen_usage()
 
 # This function completes on signal names (minus the SIG prefix)
 # @param $1 prefix
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _signals()
 {
     local -a sigs
@@ -1357,7 +1357,7 @@ _signals()
 
 # This function completes on known mac addresses
 #
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _mac_addresses()
 {
     local re='\([A-Fa-f0-9]\{2\}:\)\{5\}[A-Fa-f0-9]\{2\}'
@@ -1397,7 +1397,7 @@ _mac_addresses()
 
 # This function completes on configured network interfaces
 #
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _configured_interfaces()
 {
     local -a files
@@ -1431,7 +1431,7 @@ _configured_interfaces()
 # -6: IPv6 addresses only
 # -a: All addresses
 #
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _ip_addresses()
 {
     local n
@@ -1451,7 +1451,7 @@ _ip_addresses()
 
 # This function completes on available kernels
 #
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _kernel_versions()
 {
     _comp_compgen -- -W '$(command ls /lib/modules)'
@@ -1461,7 +1461,7 @@ _kernel_versions()
 # -a: restrict to active interfaces only
 # -w: restrict to wireless interfaces only
 #
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _available_interfaces()
 {
     local PATH=$PATH:/sbin
@@ -1480,7 +1480,7 @@ _available_interfaces()
 }
 
 # Echo number of CPUs, falling back to 1 on failure.
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _ncpus()
 {
     local var=NPROCESSORS_ONLN
@@ -1529,7 +1529,7 @@ _comp_compgen_tilde()
 #    ~foo/*           /home/foo/*
 #
 # @param $1  Name of variable (not the value of the variable) to expand
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 __expand_tilde_by_ref()
 {
     if [[ ${!1-} == \~* ]]; then
@@ -1539,7 +1539,7 @@ __expand_tilde_by_ref()
 
 # This function expands tildes in pathnames
 #
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _expand()
 {
     # Expand ~username type directory specifications.  We want to expand
@@ -1560,7 +1560,7 @@ _expand()
 
 # Process ID related functions.
 # for AIX and Solaris we use X/Open syntax, BSD for others.
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 if [[ $OSTYPE == *@(solaris|aix)* ]]; then
     # This function completes on process IDs.
     _pids()
@@ -1639,7 +1639,7 @@ fi
 
 # This function completes on user IDs
 #
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _uids()
 {
     if type getent &>/dev/null; then
@@ -1654,7 +1654,7 @@ _uids()
 
 # This function completes on group IDs
 #
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _gids()
 {
     if type getent &>/dev/null; then
@@ -1673,7 +1673,7 @@ _comp_backup_glob='@(#*#|*@(~|.@(bak|orig|rej|swp|dpkg*|rpm@(orig|new|save))))'
 
 # Complete on xinetd services
 #
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _xinetd_services()
 {
     local xinetddir=${_comp__test_xinetd_dir:-/etc/xinetd.d}
@@ -1688,7 +1688,7 @@ _xinetd_services()
 
 # This function completes on services
 #
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _services()
 {
     local sysvdirs
@@ -1718,7 +1718,7 @@ _services()
 # one, because we set it up eagerly as completer for scripts in sysv init dirs
 # below.
 #
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _service()
 {
     local cur prev words cword comp_args
@@ -1755,7 +1755,7 @@ _comp__init_set_up_service_completions
 
 # This function completes on modules
 #
-# TODO: rename per API conventions (+ include "kernel" in the name)
+# TODO:API: rename per conventions (+ include "kernel" in the name)
 _modules()
 {
     local modpath
@@ -1767,7 +1767,7 @@ _modules()
 
 # This function completes on installed modules
 #
-# TODO: rename per API conventions (+ include "kernel" in the name)
+# TODO:API: rename per conventions (+ include "kernel" in the name)
 _installed_modules()
 {
     _comp_compgen -c "$1" -- -W "$(PATH="$PATH:/sbin" lsmod |
@@ -1781,7 +1781,7 @@ _installed_modules()
 #
 # @param $1  If -u, only return users/groups the user has access to in
 #            context of current completion.
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _usergroup()
 {
     if [[ $cur == *\\\\* || $cur == *:*:* ]]; then
@@ -1826,7 +1826,7 @@ _usergroup()
     fi
 }
 
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _allowed_users()
 {
     if _complete_as_root; then
@@ -1837,7 +1837,7 @@ _allowed_users()
     fi
 }
 
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _allowed_groups()
 {
     if _complete_as_root; then
@@ -1858,7 +1858,7 @@ _comp_selinux_users()
 # This function completes on valid shells
 #
 # @param $1 chroot to search from
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _shells()
 {
     local shell rest
@@ -1869,7 +1869,7 @@ _shells()
 
 # This function completes on valid filesystem types
 #
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _fstypes()
 {
     local fss
@@ -1935,7 +1935,7 @@ _comp_realcommand()
 # This function returns the first argument, excluding options
 # @param $1 chars  Characters out of $COMP_WORDBREAKS which should
 #     NOT be considered word breaks. See _comp__reassemble_words.
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _get_first_arg()
 {
     local i
@@ -1954,7 +1954,7 @@ _get_first_arg()
 #     NOT be considered word breaks. See _comp__reassemble_words.
 # @param $2 glob   Options whose following argument should not be counted
 # @param $3 glob   Options that should be counted as args
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _count_args()
 {
     local i cword words
@@ -1972,7 +1972,7 @@ _count_args()
 
 # This function completes on PCI IDs
 #
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _pci_ids()
 {
     _comp_compgen -a -- -W "$(PATH="$PATH:/sbin" lspci -n | awk '{print $3}')"
@@ -1980,28 +1980,28 @@ _pci_ids()
 
 # This function completes on USB IDs
 #
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _usb_ids()
 {
     _comp_compgen -a -- -W "$(PATH="$PATH:/sbin" lsusb | awk '{print $6}')"
 }
 
 # CD device names
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _cd_devices()
 {
     _comp_compgen -ac "${cur:-/dev/}" -- -f -d -X "!*/?([amrs])cd*"
 }
 
 # DVD device names
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _dvd_devices()
 {
     _comp_compgen -ac "${cur:-/dev/}" -- -f -d -X "!*/?(r)dvd*"
 }
 
 # TERM environment variable values
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _terms()
 {
     _comp_compgen -a -- -W "$({
@@ -2016,7 +2016,7 @@ _terms()
     } 2>/dev/null)"
 }
 
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _bashcomp_try_faketty()
 {
     if type unbuffer &>/dev/null; then
@@ -2036,7 +2036,7 @@ _bashcomp_try_faketty()
 
 # This function provides simple user@host completion
 #
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _user_at_host()
 {
     local cur prev words cword comp_args
@@ -2053,7 +2053,7 @@ shopt -u hostcomplete && complete -F _user_at_host talk ytalk finger
 
 # NOTE: Using this function as a helper function is deprecated.  Use
 #       `_known_hosts_real' instead.
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _known_hosts()
 {
     local cur prev words cword comp_args
@@ -2071,7 +2071,7 @@ _known_hosts()
 # Helper function to locate ssh included files in configs
 # This function looks for the "Include" keyword in ssh config files and
 # includes them recursively, adding each result to the config variable.
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _included_ssh_config_files()
 {
     (($# < 1)) &&
@@ -2124,7 +2124,7 @@ _included_ssh_config_files()
 #     -4             Filter IPv6 addresses from results
 #     -6             Filter IPv4 addresses from results
 # @return Completions, starting with CWORD, are added to COMPREPLY[]
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _known_hosts_real()
 {
     local configfile="" flag prefix=""
@@ -2516,7 +2516,7 @@ _comp_root_command()
 complete -F _comp_root_command fakeroot gksu gksudo kdesudo really
 
 # Return true if the completion should be treated as running as root
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _complete_as_root()
 {
     [[ $EUID -eq 0 || ${root_command-} ]]
@@ -2582,7 +2582,7 @@ complete -F _comp_longopt \
 
 declare -Ag _xspecs
 
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _filedir_xspec()
 {
     local cur prev words cword comp_args
@@ -2622,7 +2622,7 @@ _filedir_xspec()
     fi
 }
 
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _install_xspec()
 {
     local xspec=$1 cmd
@@ -2691,7 +2691,7 @@ _install_xspec '!*.@(mp[234c]|og[ag]|@(fl|a)ac|m4[abp]|spx|tta|w?(a)v|wma|aif?(f
 unset -f _install_xspec
 
 # Minimal completion to use as fallback in _completion_loader.
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _minimal()
 {
     local cur prev words cword comp_args
@@ -2702,7 +2702,7 @@ _minimal()
 # https://lists.gnu.org/archive/html/bug-bash/2012-01/msg00045.html
 complete -F _minimal ''
 
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 __load_completion()
 {
     local cmd=$1 cmdname=${1##*/} dir compfile
@@ -2821,7 +2821,7 @@ __load_completion()
 }
 
 # set up dynamic completion loading
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _completion_loader()
 {
     # $1=_EmptycmD_ already for empty cmds in bash 4.3, set to it for earlier
diff --git a/completions/_modules b/completions/_modules
index 6c72a35d700..c208fc27695 100644
--- a/completions/_modules
+++ b/completions/_modules
@@ -21,21 +21,21 @@
 # being sourced before it and thus before the `module' alias has been defined.
 [[ -f /etc/profile.d/modules.sh ]] || return 1
 
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _module_list()
 {
     local modules="$(command sed 's/:/ /g' <<<"$LOADEDMODULES" | sort)"
     compgen -W "$modules" -- "$1"
 }
 
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _module_path()
 {
     local modules="$(command sed 's/:/ /g' <<<"$MODULEPATH" | sort)"
     compgen -W "$modules" -- "$1"
 }
 
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _module_avail()
 {
     local modules="$(
diff --git a/completions/_yum b/completions/_yum
index b2395308c66..17c8b90ae74 100644
--- a/completions/_yum
+++ b/completions/_yum
@@ -18,7 +18,7 @@ _comp_cmd_yum__list()
     fi
 }
 
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _yum_repolist()
 {
     # -d 0 causes repolist to output nothing as of yum 3.2.22:
@@ -29,7 +29,7 @@ _yum_repolist()
             -e 's/[[:space:]].*//p'
 }
 
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _yum_plugins()
 {
     local -a files
diff --git a/completions/bts b/completions/bts
index 23cb5e09b3f..988f1a03d19 100644
--- a/completions/bts
+++ b/completions/bts
@@ -1,7 +1,7 @@
 # bts completion                                      -*- shell-script -*-
 
 # List bug numbers from bugs cache in ~/.devscripts_cache/bts
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _cached_bugs()
 {
     [[ -d $HOME/.devscripts_cache/bts ]] &&
@@ -11,7 +11,7 @@ _cached_bugs()
 }
 
 # List APT source packages prefixed with "src:"
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _src_packages_with_prefix()
 {
     ppn=${cur:4} # partial package name, after stripping "src:"
diff --git a/completions/cvs b/completions/cvs
index 46a5b492d7a..be8ce5c4183 100644
--- a/completions/cvs
+++ b/completions/cvs
@@ -20,7 +20,7 @@ _comp_cmd_cvs__modules()
     fi
 }
 
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _cvs_commands()
 {
     cvs --help-commands 2>&1 | awk '/^(     *|\t)/ { print $1 }'
diff --git a/completions/dict b/completions/dict
index d5ddc6ddbf6..424d77ad70b 100644
--- a/completions/dict
+++ b/completions/dict
@@ -1,6 +1,6 @@
 # dict(1) completion                                       -*- shell-script -*-
 
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _dictdata()
 {
     # shellcheck disable=SC2086
diff --git a/completions/mutt b/completions/mutt
index a77c489d19a..35258c90983 100644
--- a/completions/mutt
+++ b/completions/mutt
@@ -14,7 +14,7 @@ _comp_cmd_mutt__addresses()
 
 # Find muttrc to use
 # @output  muttrc filename
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _muttrc()
 {
     local muttrc=
@@ -82,7 +82,7 @@ _comp_cmd_mutt__get_conffiles__visit()
 # Recursively build list of sourced config files
 # @param $1...  Config file to process
 # @output       List of config files
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _muttconffiles()
 {
     local ret
diff --git a/completions/openssl b/completions/openssl
index 911e88c8246..d9e5882ef3f 100644
--- a/completions/openssl
+++ b/completions/openssl
@@ -25,7 +25,7 @@ _comp_cmd_openssl__sections()
     COMPREPLY=($(compgen -W "$(awk '/\[.*\]/ {print $2}' "$config")" -- "$cur"))
 }
 
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _openssl_digests()
 {
     "$1" dgst -h 2>&1 |
diff --git a/completions/tar b/completions/tar
index 8c91ade8fcb..4e7164cf9ab 100644
--- a/completions/tar
+++ b/completions/tar
@@ -56,7 +56,7 @@
 # `$BASH_COMPLETION_CMD_TAR_INTERNAL_PATHS` environment variable to a non-null
 # value *before sourcing* this completion toggles that the other way around.
 
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 __gtar_parse_help_opt()
 {
     local opttype arg opt separator optvar
@@ -96,7 +96,7 @@ __gtar_parse_help_opt()
     eval "$optvar=\"\$$optvar$separator\"\"$opt\""
 }
 
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 __gtar_parse_help_line()
 {
     local i
@@ -118,7 +118,7 @@ __gtar_parse_help_line()
     done <<<"$1"
 }
 
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 __gnu_tar_parse_help()
 {
     local str line arg
@@ -152,7 +152,7 @@ __gnu_tar_parse_help()
 }
 
 # Hack: parse --warning keywords from tar's error output
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 __gtar_parse_warnings()
 {
     local line
@@ -164,13 +164,13 @@ __gtar_parse_warnings()
 }
 
 # Helper to obtain last character of string.
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 __tar_last_char()
 {
     echo "${1:$((${#1} - 1))}"
 }
 
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 __tar_parse_old_opt()
 {
     local first_word char
@@ -199,7 +199,7 @@ __tar_parse_old_opt()
 }
 
 # Make the analysis of whole command line.
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 __tar_preparse_cmdline()
 {
     local first_arg=set i modes="ctxurdA"
@@ -238,7 +238,7 @@ __tar_preparse_cmdline()
 }
 
 # Generate completions for -f/--file.
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 __tar_file_option()
 {
     local ext="$1"
@@ -256,7 +256,7 @@ __tar_file_option()
 
 # Returns truth if option requires argument.  No equal sign must be pasted.
 # Accepts option in format: 'c', '-c', '--create'
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 __tar_is_argreq()
 {
     local opt
@@ -360,7 +360,7 @@ _comp_cmd_tar__gnu_short_options()
     _comp_compgen -- -W "$generated"
 }
 
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 __tar_try_mode()
 {
     case "$cur" in
@@ -387,7 +387,7 @@ __tar_try_mode()
     return 1
 }
 
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 __tar_adjust_PREV_from_old_option()
 {
     # deal with old style arguments here
@@ -399,7 +399,7 @@ __tar_adjust_PREV_from_old_option()
     fi
 }
 
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 __tar_extract_like_mode()
 {
     local i
@@ -442,7 +442,7 @@ _comp_cmd_tar__try_list_archive()
     fi
 }
 
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 __tar_cleanup_prev()
 {
     if [[ $prev =~ ^-[a-zA-Z0-9?]*$ ]]; then
@@ -451,7 +451,7 @@ __tar_cleanup_prev()
     fi
 }
 
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 __tar_detect_ext()
 {
     local tars='@(@(tar|spkg)?(.@(Z|[bgx]z|bz2|lz?(ma|o)|zst))|t@([abglx]z|b?(z)2|zst)|cbt|gem|xbps)'
@@ -672,7 +672,7 @@ _comp_cmd_tar__gnu()
     fi
 }
 
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 __tar_posix_prev_handle()
 {
     case "$prev" in
diff --git a/completions/vpnc b/completions/vpnc
index 4c9adaeaf67..251e67cdb0a 100644
--- a/completions/vpnc
+++ b/completions/vpnc
@@ -1,6 +1,6 @@
 # bash completion for vpnc                                 -*- shell-script -*-
 
-# TODO: rename per API conventions
+# TODO:API: rename per conventions
 _vpnc()
 {
     local cur prev words cword comp_args
diff --git a/completions/xrandr b/completions/xrandr
index 3464f98d95c..55ce97731d3 100644
--- a/completions/xrandr
+++ b/completions/xrandr
@@ -1,26 +1,26 @@
 # bash completion for xrandr                               -*- shell-script -*-
 
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _comp_cmd_xrandr_outputs()
 {
     "$1" -q 2>/dev/null | awk '/connected/ {print $1}'
 }
 
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _comp_cmd_xrandr_monitors()
 {
     "$1" --listmonitors 2>/dev/null |
         command sed -ne 's/.* [0-9]*: [+\*]*\([^ ]*\).*/\1/p'
 }
 
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _comp_cmd_xrandr_providers()
 {
     "$1" --listproviders 2>/dev/null |
         command sed -ne "s/.*cap:.*$2.* name:\([^ ]*\).*/\1/p"
 }
 
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _comp_cmd_xrandr_modes()
 {
     "$1" -q 2>/dev/null | command sed \
@@ -31,7 +31,7 @@ _comp_cmd_xrandr_modes()
         -e 's/\([^[:space:]]\)[[:space:]].*/\1/'
 }
 
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _comp_cmd_xrandr_all_modes()
 {
     "$1" -q 2>/dev/null | command sed \
@@ -41,7 +41,7 @@ _comp_cmd_xrandr_all_modes()
         -e 's/[[:space:]]*\([^[:space:]]*\)[[:space:]].*/\1/'
 }
 
-# TODO: rename per API conventions, rework to use vars rather than outputting
+# TODO:API: rename per conventions, rework to use vars rather than outputting
 _comp_cmd_xrandr_help()
 {
     "$1" --help 2>/dev/null

From f4fdc13e6aa1fc44f098997798161f60e09cc117 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ville=20Skytt=C3=A4?= <ville.skytta@iki.fi>
Date: Mon, 8 May 2023 08:10:03 +0300
Subject: [PATCH 3/4] chore(apt-cache,ssh): mark some more functions needing
 API work

---
 completions/apt-cache | 3 +++
 completions/ssh       | 1 +
 2 files changed, 4 insertions(+)

diff --git a/completions/apt-cache b/completions/apt-cache
index 91ba2a92bf0..1a6af78bffc 100644
--- a/completions/apt-cache
+++ b/completions/apt-cache
@@ -1,12 +1,14 @@
 # Debian apt-cache(8) completion                           -*- shell-script -*-
 
 # List APT binary packages
+# TODO:API: rework to use vars rather than outputting
 _comp_xfunc_apt_cache_packages()
 {
     apt-cache --no-generate pkgnames "$cur" 2>/dev/null || :
 }
 
 # List APT source packages
+# TODO:API: rework to use vars rather than outputting
 _comp_xfunc_apt_cache_sources()
 {
     compgen -W "$(apt-cache dumpavail |
@@ -14,6 +16,7 @@ _comp_xfunc_apt_cache_sources()
 }
 
 # List APT source packages
+# TODO:API: rework to use vars rather than outputting
 _comp_xfunc_apt_cache_src_packages()
 {
     compgen -W '$(_comp_xfunc_apt_cache_sources "$cur")' -- "$cur"
diff --git a/completions/ssh b/completions/ssh
index 09427e9ee0d..ff8fda3ece6 100644
--- a/completions/ssh
+++ b/completions/ssh
@@ -10,6 +10,7 @@ _comp_cmd_ssh__queries()
     _comp_compgen -ac "${cur,,}" -- -W "$queries help"
 }
 
+# TODO:API:rework to use vars rather than outputting
 _comp_xfunc_ssh_query()
 {
     ${1:-ssh} -Q "$2" 2>/dev/null

From 007e6414fbac0602859ddb8732467965b7959de0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ville=20Skytt=C3=A4?= <ville.skytta@iki.fi>
Date: Mon, 8 May 2023 08:14:54 +0300
Subject: [PATCH 4/4] docs(completions): add `@since` markers to xfuncs

---
 completions/apt-cache  | 3 +++
 completions/apt-get    | 1 +
 completions/asciidoc   | 1 +
 completions/cvs        | 1 +
 completions/iconv      | 1 +
 completions/list_lists | 1 +
 completions/mysql      | 1 +
 completions/python     | 2 ++
 completions/rpm        | 1 +
 completions/ssh        | 6 ++++++
 10 files changed, 18 insertions(+)

diff --git a/completions/apt-cache b/completions/apt-cache
index 1a6af78bffc..3ea95db3456 100644
--- a/completions/apt-cache
+++ b/completions/apt-cache
@@ -2,6 +2,7 @@
 
 # List APT binary packages
 # TODO:API: rework to use vars rather than outputting
+# @since 2.12
 _comp_xfunc_apt_cache_packages()
 {
     apt-cache --no-generate pkgnames "$cur" 2>/dev/null || :
@@ -9,6 +10,7 @@ _comp_xfunc_apt_cache_packages()
 
 # List APT source packages
 # TODO:API: rework to use vars rather than outputting
+# @since 2.12
 _comp_xfunc_apt_cache_sources()
 {
     compgen -W "$(apt-cache dumpavail |
@@ -17,6 +19,7 @@ _comp_xfunc_apt_cache_sources()
 
 # List APT source packages
 # TODO:API: rework to use vars rather than outputting
+# @since 2.12
 _comp_xfunc_apt_cache_src_packages()
 {
     compgen -W '$(_comp_xfunc_apt_cache_sources "$cur")' -- "$cur"
diff --git a/completions/apt-get b/completions/apt-get
index dc63a5cb0af..fef8fdceedb 100644
--- a/completions/apt-get
+++ b/completions/apt-get
@@ -1,5 +1,6 @@
 # Debian apt-get(8) completion                             -*- shell-script -*-
 
+# @since 2.12
 _comp_xfunc_apt_get_installed_packages()
 {
     if [[ -f /etc/debian_version ]]; then
diff --git a/completions/asciidoc b/completions/asciidoc
index 1e0523e001f..8bb47af503f 100644
--- a/completions/asciidoc
+++ b/completions/asciidoc
@@ -1,5 +1,6 @@
 # asciidoc(1) completion                                   -*- shell-script -*-
 
+# @since 2.12
 _comp_xfunc_asciidoc_doctype()
 {
     _comp_compgen -a -- -W 'article book manpage'
diff --git a/completions/cvs b/completions/cvs
index be8ce5c4183..ec3afbf072f 100644
--- a/completions/cvs
+++ b/completions/cvs
@@ -36,6 +36,7 @@ _comp_cmd_cvs__kflags()
     _comp_compgen -- -W 'kv kvl k o b v'
 }
 
+# @since 2.12
 _comp_xfunc_cvs_roots()
 {
     local -a cvsroots=()
diff --git a/completions/iconv b/completions/iconv
index b4dfc040c9a..27b0e9f4658 100644
--- a/completions/iconv
+++ b/completions/iconv
@@ -1,5 +1,6 @@
 # iconv(1) completion                                      -*- shell-script -*-
 
+# @since 2.12
 _comp_xfunc_iconv_charsets()
 {
     COMPREPLY+=($(compgen -X ... -W '$("${1:-iconv}" -l | \
diff --git a/completions/list_lists b/completions/list_lists
index d7b3be847cc..d54bb0a7962 100644
--- a/completions/list_lists
+++ b/completions/list_lists
@@ -1,5 +1,6 @@
 # mailman list_lists completion                            -*- shell-script -*-
 
+# @since 2.12
 _comp_xfunc_list_lists_mailman_lists()
 {
     COMPREPLY=($(compgen -W '$(list_lists -b 2>/dev/null)' -- "$cur"))
diff --git a/completions/mysql b/completions/mysql
index 09701e5afdf..4f7b5bf91af 100644
--- a/completions/mysql
+++ b/completions/mysql
@@ -1,5 +1,6 @@
 # mysql(1) completion                                      -*- shell-script -*-
 
+# @since 2.12
 _comp_xfunc_mysql_character_sets()
 {
     local -a charsets
diff --git a/completions/python b/completions/python
index be042fdc426..2dbd9e7c445 100644
--- a/completions/python
+++ b/completions/python
@@ -1,5 +1,6 @@
 # bash completion for python                               -*- shell-script -*-
 
+# @since 2.12
 _comp_xfunc_python_modules()
 {
     COMPREPLY+=($(compgen -W \
@@ -7,6 +8,7 @@ _comp_xfunc_python_modules()
             2>/dev/null)" -- "$cur"))
 }
 
+# @since 2.12
 _comp_xfunc_python_warning_actions()
 {
     COMPREPLY+=($(compgen -W "ignore default all module once error" \
diff --git a/completions/rpm b/completions/rpm
index 695a00e4428..1841cbf98aa 100644
--- a/completions/rpm
+++ b/completions/rpm
@@ -2,6 +2,7 @@
 
 # helper functions
 
+# @since 2.12
 _comp_xfunc_rpm_installed_packages()
 {
     if [[ -r /var/log/rpmpkgs &&
diff --git a/completions/ssh b/completions/ssh
index ff8fda3ece6..a5fe8735aab 100644
--- a/completions/ssh
+++ b/completions/ssh
@@ -10,6 +10,7 @@ _comp_cmd_ssh__queries()
     _comp_compgen -ac "${cur,,}" -- -W "$queries help"
 }
 
+# @since 2.12
 # TODO:API:rework to use vars rather than outputting
 _comp_xfunc_ssh_query()
 {
@@ -35,6 +36,7 @@ _comp_cmd_ssh__macs()
     _comp_compgen -a -- -W "$macs"
 }
 
+# @since 2.12
 _comp_xfunc_ssh_options()
 {
     # curl --silent https://raw.githubusercontent.com/openssh/openssh-portable/master/ssh_config.5 | awk '$1==".It" && $2=="Cm" && $3!="Host" && $3!="Match" {print "        "$3}' | sort
@@ -215,6 +217,7 @@ _comp_cmd_ssh__suboption()
 # Try to complete -o SubOptions=
 #
 # Returns 0 if the completion was handled or non-zero otherwise.
+# @since 2.12
 _comp_xfunc_ssh_suboption_check()
 {
     # Get prev and cur words without splitting on =
@@ -250,6 +253,7 @@ _comp_cmd_ssh__configfile()
 }
 
 # With $1 set, look for public key files, else private
+# @since 2.12
 # shellcheck disable=SC2120
 _comp_xfunc_ssh_identityfile()
 {
@@ -432,6 +436,7 @@ _comp_cmd_scp__path_esc='[][(){}<>"'"'"',:;^&!$=?`\\|[:space:]]'
 
 # Complete remote files with ssh.  If the first arg is -d, complete on dirs
 # only.  Returns paths escaped with three backslashes.
+# @since 2.12
 # shellcheck disable=SC2120
 _comp_xfunc_ssh_scp_remote_files()
 {
@@ -475,6 +480,7 @@ _comp_deprecate_func _scp_remote_files _comp_xfunc_ssh_scp_remote_files
 # appended after local file/dir completions, and -o nospace retained for
 # others.  If first arg is -d, complete on directory names only.  The next arg
 # is an optional prefix to add to returned completions.
+# @since 2.12
 _comp_xfunc_ssh_scp_local_files()
 {
     local IFS=$'\n'