Merge pull request #947 from scop/docs/remaining-api-changes

docs: function status comments

Author: scop

bash_completion

@@ -747,6 +747,7 @@ _comp_quote_compgen()
 #            completions with `.$1' and the uppercase version of it as file
 #            extension.
 #
+# TODO: rename per API conventions
 _filedir()
 {
     _tilde "${cur-}" || return
@@ -813,6 +814,7 @@ _comp__split_longopt()
 # Complete variables.
 # @return  True (0) if variables were completed,
 #          False (> 0) if not.
+# TODO: rename per API conventions
 _variables()
 {
     if [[ $cur =~ ^(\$(\{[!#]?)?)([A-Za-z0-9_]*)$ ]]; then
@@ -1073,6 +1075,7 @@ _comp_initialize()
 
 # Helper function for _parse_help and _parse_usage.
 # @return True (0) if an option was found, False (> 0) otherwise
+# TODO: rename per API conventions, rework to use vars rather than outputting
 __parse_options()
 {
     local option option2 i
@@ -1114,6 +1117,7 @@ __parse_options()
 # @param $1  command; if "-", read from stdin and ignore rest of args
 # @param $2  command options (default: --help)
 #
+# TODO: rename per API conventions, rework to use vars rather than outputting
 _parse_help()
 {
     local IFS=$' \t\n'
@@ -1154,6 +1158,7 @@ _parse_help()
 # @param $1  command; if "-", read from stdin and ignore rest of args
 # @param $2  command options (default: --usage)
 #
+# TODO: rename per API conventions, rework to use vars rather than outputting
 _parse_usage()
 {
     local IFS=$' \t\n'
@@ -1203,6 +1208,7 @@ _parse_usage()
 
 # This function completes on signal names (minus the SIG prefix)
 # @param $1 prefix
+# TODO: rename per API conventions
 _signals()
 {
     local -a sigs
@@ -1212,6 +1218,7 @@ _signals()
 
 # This function completes on known mac addresses
 #
+# TODO: rename per API conventions
 _mac_addresses()
 {
     local re='\([A-Fa-f0-9]\{2\}:\)\{5\}[A-Fa-f0-9]\{2\}'
@@ -1251,6 +1258,7 @@ _mac_addresses()
 
 # This function completes on configured network interfaces
 #
+# TODO: rename per API conventions
 _configured_interfaces()
 {
     local -a files
@@ -1288,6 +1296,7 @@ _configured_interfaces()
 # -6: IPv6 addresses only
 # -a: All addresses
 #
+# TODO: rename per API conventions
 _ip_addresses()
 {
     local n
@@ -1307,6 +1316,7 @@ _ip_addresses()
 
 # This function completes on available kernels
 #
+# TODO: rename per API conventions
 _kernel_versions()
 {
     _comp_compgen COMPREPLY -W '$(command ls /lib/modules)' -- "$cur"
@@ -1316,6 +1326,7 @@ _kernel_versions()
 # -a: restrict to active interfaces only
 # -w: restrict to wireless interfaces only
 #
+# TODO: rename per API conventions
 _available_interfaces()
 {
     local PATH=$PATH:/sbin
@@ -1334,6 +1345,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
 _ncpus()
 {
     local var=NPROCESSORS_ONLN
@@ -1346,6 +1358,7 @@ _ncpus()
 # @return  True (0) if completion needs further processing,
 #          False (1) if tilde is followed by a valid username, completions are
 #          put in COMPREPLY and no further processing is necessary.
+# TODO: rename per API conventions
 _tilde()
 {
     if [[ ${1-} == \~* && $1 != */* ]]; then
@@ -1381,6 +1394,7 @@ _tilde()
 #    ~foo/*           /home/foo/*
 #
 # @param $1  Name of variable (not the value of the variable) to expand
+# TODO: rename per API conventions
 __expand_tilde_by_ref()
 {
     if [[ ${!1-} == \~* ]]; then
@@ -1390,6 +1404,7 @@ __expand_tilde_by_ref()
 
 # This function expands tildes in pathnames
 #
+# TODO: rename per API conventions
 _expand()
 {
     # Expand ~username type directory specifications.  We want to expand
@@ -1410,6 +1425,7 @@ _expand()
 
 # Process ID related functions.
 # for AIX and Solaris we use X/Open syntax, BSD for others.
+# TODO: rename per API conventions
 if [[ $OSTYPE == *@(solaris|aix)* ]]; then
     # This function completes on process IDs.
     _pids()
@@ -1488,6 +1504,7 @@ fi
 
 # This function completes on user IDs
 #
+# TODO: rename per API conventions
 _uids()
 {
     if type getent &>/dev/null; then
@@ -1502,6 +1519,7 @@ _uids()
 
 # This function completes on group IDs
 #
+# TODO: rename per API conventions
 _gids()
 {
     if type getent &>/dev/null; then
@@ -1520,6 +1538,7 @@ _comp_backup_glob='@(#*#|*@(~|.@(bak|orig|rej|swp|dpkg*|rpm@(orig|new|save))))'
 
 # Complete on xinetd services
 #
+# TODO: rename per API conventions
 _xinetd_services()
 {
     local xinetddir=${_comp__test_xinetd_dir:-/etc/xinetd.d}
@@ -1534,6 +1553,7 @@ _xinetd_services()
 
 # This function completes on services
 #
+# TODO: rename per API conventions
 _services()
 {
     local sysvdirs
@@ -1559,7 +1579,11 @@ _services()
 # This completes on a list of all available service scripts for the
 # 'service' command and/or the SysV init.d directory, followed by
 # that script's available commands
+# This function is in the main bash_completion file rather than in a separate
+# 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
 _service()
 {
     local cur prev words cword comp_args
@@ -1596,6 +1620,7 @@ _comp__init_set_up_service_completions
 
 # This function completes on modules
 #
+# TODO: rename per API conventions (+ include "kernel" in the name)
 _modules()
 {
     local modpath
@@ -1607,6 +1632,7 @@ _modules()
 
 # This function completes on installed modules
 #
+# TODO: rename per API conventions (+ include "kernel" in the name)
 _installed_modules()
 {
     _comp_compgen COMPREPLY -W "$(PATH="$PATH:/sbin" lsmod |
@@ -1620,6 +1646,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
 _usergroup()
 {
     if [[ $cur == *\\\\* || $cur == *:*:* ]]; then
@@ -1664,6 +1691,7 @@ _usergroup()
     fi
 }
 
+# TODO: rename per API conventions
 _allowed_users()
 {
     if _complete_as_root; then
@@ -1674,6 +1702,7 @@ _allowed_users()
     fi
 }
 
+# TODO: rename per API conventions
 _allowed_groups()
 {
     if _complete_as_root; then
@@ -1694,6 +1723,7 @@ _comp_selinux_users()
 # This function completes on valid shells
 #
 # @param $1 chroot to search from
+# TODO: rename per API conventions
 _shells()
 {
     local shell rest
@@ -1704,6 +1734,7 @@ _shells()
 
 # This function completes on valid filesystem types
 #
+# TODO: rename per API conventions
 _fstypes()
 {
     local fss
@@ -1769,6 +1800,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
 _get_first_arg()
 {
     local i
@@ -1787,6 +1819,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
 _count_args()
 {
     local i cword words
@@ -1804,6 +1837,7 @@ _count_args()
 
 # This function completes on PCI IDs
 #
+# TODO: rename per API conventions
 _pci_ids()
 {
     _comp_compgen -a COMPREPLY -W \
@@ -1812,25 +1846,29 @@ _pci_ids()
 
 # This function completes on USB IDs
 #
+# TODO: rename per API conventions
 _usb_ids()
 {
     _comp_compgen -a COMPREPLY -W \
         "$(PATH="$PATH:/sbin" lsusb | awk '{print $6}')" -- "$cur"
 }
 
 # CD device names
+# TODO: rename per API conventions
 _cd_devices()
 {
     _comp_compgen -a COMPREPLY -f -d -X "!*/?([amrs])cd*" -- "${cur:-/dev/}"
 }
 
 # DVD device names
+# TODO: rename per API conventions
 _dvd_devices()
 {
     _comp_compgen -a COMPREPLY -f -d -X "!*/?(r)dvd*" -- "${cur:-/dev/}"
 }
 
 # TERM environment variable values
+# TODO: rename per API conventions
 _terms()
 {
     _comp_compgen -a COMPREPLY -W "$({
@@ -1845,6 +1883,7 @@ _terms()
     } 2>/dev/null)" -- "$cur"
 }
 
+# TODO: rename per API conventions
 _bashcomp_try_faketty()
 {
     if type unbuffer &>/dev/null; then
@@ -1864,6 +1903,7 @@ _bashcomp_try_faketty()
 
 # This function provides simple user@host completion
 #
+# TODO: rename per API conventions
 _user_at_host()
 {
     local cur prev words cword comp_args
@@ -1880,6 +1920,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
 _known_hosts()
 {
     local cur prev words cword comp_args
@@ -1897,6 +1938,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
 _included_ssh_config_files()
 {
     (($# < 1)) &&
@@ -1949,6 +1991,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
 _known_hosts_real()
 {
     local configfile="" flag prefix=""
@@ -2306,6 +2349,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
 _complete_as_root()
 {
     [[ $EUID -eq 0 || ${root_command-} ]]
@@ -2371,6 +2415,7 @@ complete -F _comp_longopt \
 
 declare -Ag _xspecs
 
+# TODO: rename per API conventions
 _filedir_xspec()
 {
     local cur prev words cword comp_args
@@ -2410,6 +2455,7 @@ _filedir_xspec()
     fi
 }
 
+# TODO: rename per API conventions
 _install_xspec()
 {
     local xspec=$1 cmd
@@ -2478,6 +2524,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
 _minimal()
 {
     local cur prev words cword comp_args
@@ -2488,6 +2535,7 @@ _minimal()
 # https://lists.gnu.org/archive/html/bug-bash/2012-01/msg00045.html
 complete -F _minimal ''
 
+# TODO: rename per API conventions
 __load_completion()
 {
     local cmd=$1 cmdname=${1##*/} dir compfile
@@ -2606,6 +2654,7 @@ __load_completion()
 }
 
 # set up dynamic completion loading
+# TODO: rename per API conventions
 _completion_loader()
 {
     # $1=_EmptycmD_ already for empty cmds in bash 4.3, set to it for earlier

completions/_modules

@@ -21,18 +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
 _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
 _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
 _module_avail()
 {
     local modules="$(