docs(compat): add more @since and @deprecated versions, some TODOs

Author: scop

bash_completion

@@ -96,6 +96,7 @@ complete -b builtin
 
 # Check if we're running on the given userland
 # @param $1 userland to check for
+# @since 2.12
 _comp_userland()
 {
     local userland=$(uname -s)
@@ -105,6 +106,7 @@ _comp_userland()
 
 # This function sets correct SysV init directories
 #
+# @since 2.12
 _comp_sysvdirs()
 {
     sysvdirs=()
@@ -117,6 +119,7 @@ _comp_sysvdirs()
 
 # This function checks whether we have a given program on the system.
 #
+# @since 2.12
 _comp_have_command()
 {
     # Completions for system administrator commands are installed as well in
@@ -127,6 +130,7 @@ _comp_have_command()
 # This function checks whether a given readline variable
 # is `on'.
 #
+# @since 2.12
 _comp_readline_variable_on()
 {
     [[ $(bind -v) == *$1+([[:space:]])on* ]]
@@ -135,6 +139,7 @@ _comp_readline_variable_on()
 # This function shell-quotes the argument
 # @param    $1  String to be quoted
 # @var[out] ret Resulting string
+# @since 2.12
 _comp_quote()
 {
     ret=\'${1//\'/\'\\\'\'}\'
@@ -194,6 +199,7 @@ _comp_dequote__initialize
 # We allow these parameter expansions as a part of safe strings assuming the
 # referential transparency of the simple parameter expansions and the sane
 # setup of the variables by the user or other frameworks that the user loads.
+# @since 2.12
 _comp_dequote()
 {
     ret=() # fallback value for unsafe word and failglob
@@ -226,6 +232,7 @@ _comp_unlocal()
 #     -v   Assign single value to varname
 # @return  1 if error occurs
 # @see https://fvue.nl/wiki/Bash:_Passing_variables_by_reference
+# @since 2.12
 _comp_upvars()
 {
     if ! (($#)); then
@@ -467,6 +474,7 @@ _comp_split()
 # supposed to replace the existing content of the array by default to allow the
 # caller control whether to replace or append by the option `-a`.
 #
+# @since 2.12
 _comp_compgen()
 {
     local _append=${_comp_compgen__append-}
@@ -722,6 +730,7 @@ _comp__get_cword_at_cursor()
 #
 #    $ _comp_get_words -n : cur prev
 #
+# @since 2.12
 _comp_get_words()
 {
     local exclude="" flag i OPTIND=1
@@ -801,6 +810,7 @@ _comp_get_words()
 # @param $1 current word to complete (cur)
 # @modifies global array $COMPREPLY
 #
+# @since 2.12
 _comp_ltrim_colon_completions()
 {
     local i=${#COMPREPLY[*]}
@@ -830,6 +840,7 @@ _comp_ltrim_colon_completions()
 # - https://www.mail-archive.com/bash-completion-devel@lists.alioth.debian.org/msg01944.html
 # @param $1      Argument to quote
 # @var[out] ret  Quoted result is stored in this variable
+# @since 2.12
 # shellcheck disable=SC2178 # The assignment is not intended for the global "ret"
 _comp_quote_compgen()
 {
@@ -1118,6 +1129,7 @@ _comp_variable_assignments()
 # @return  True (0) if completion needs further processing,
 #          False (> 0) no further processing is necessary.
 #
+# @since 2.12
 _comp_initialize()
 {
     local exclude="" opt_split="" outx errx inx
@@ -1285,6 +1297,7 @@ _comp_compgen_help__parse()
 # When no arguments are specified, `--help` is assumed.
 #
 # @var[in] comp_args[0]
+# @since 2.12
 _comp_compgen_help()
 {
     (($#)) || set -- -- --help
@@ -1316,6 +1329,7 @@ _comp_compgen_help()
 # When no arguments are specified, `--usage` is assumed.
 #
 # @var[in] comp_args[0]
+# @since 2.12
 _comp_compgen_usage()
 {
     (($#)) || set -- -- --usage
@@ -1921,6 +1935,7 @@ _comp_abspath()
 # @param    $1 Command
 # @var[out] ret Resulting string
 # @return   True (0) if command found, False (> 0) if not.
+# @since 2.12
 _comp_realcommand()
 {
     ret=""
@@ -2372,6 +2387,7 @@ _comp__find_original_word()
 # first complete on a command, then complete according to that command's own
 # completion definition.
 #
+# @since 2.12
 _comp_command_offset()
 {
     # rewrite current completion context before invoking
@@ -2489,6 +2505,7 @@ _comp_command_offset()
 # Only intended to be used as a completion function directly associated
 # with a command, not to be invoked from within other completion functions.
 #
+# @since 2.12
 _comp_command()
 {
     # We unset the shell variable `words` locally to tell
@@ -2512,6 +2529,7 @@ _comp_command()
 complete -F _comp_command aoss command "do" else eval exec ltrace nice nohup padsp \
     "then" time tsocks vsound xargs
 
+# @since 2.12
 _comp_root_command()
 {
     local PATH=$PATH:/sbin:/usr/sbin:/usr/local/sbin
@@ -2527,6 +2545,7 @@ _complete_as_root()
     [[ $EUID -eq 0 || ${root_command-} ]]
 }
 
+# @since 2.12
 _comp_longopt()
 {
     local cur prev words cword was_split comp_args
@@ -2846,6 +2865,7 @@ _completion_loader()
 #   `_comp_xfunc_${1//[^a-zA-Z0-9_]/_}_$2' is used for the actual name of the
 #   shell function.
 # @param $3... if any, specifies the arguments that are passed to the xfunc.
+# @since 2.12
 _comp_xfunc()
 {
     local xfunc_name=$2

bash_completion.d/000_bash_completion_compat.bash

@@ -18,9 +18,9 @@ _comp_deprecate_func 2.12 _split_longopt _comp__split_longopt
 _comp_deprecate_func 2.12 __ltrim_colon_completions _comp_ltrim_colon_completions
 
 # Backwards compatibility for compat completions that use have().
-# @deprecated should no longer be used; generally not needed with dynamically
-#             loaded completions, and _comp_have_command is suitable for
-#             runtime use.
+# @deprecated 1.90 should no longer be used; generally not needed with
+#   dynamically loaded completions, and _comp_have_command is suitable for
+#   runtime use.
 # shellcheck disable=SC2317 # available at load time only
 have()
 {
@@ -29,15 +29,15 @@ have()
 }
 
 # This function shell-quotes the argument
-# @deprecated Use `_comp_quote` instead.  Note that `_comp_quote` stores
+# @deprecated 2.12 Use `_comp_quote` instead.  Note that `_comp_quote` stores
 #   the results in the variable `ret` instead of writing them to stdout.
 quote()
 {
     local quoted=${1//\'/\'\\\'\'}
     printf "'%s'" "$quoted"
 }
 
-# @deprecated Use `_comp_quote_compgen`
+# @deprecated 2.12 Use `_comp_quote_compgen`
 quote_readline()
 {
     local ret
@@ -49,7 +49,7 @@ quote_readline()
 # argument specifying the variable name to store the result.
 # @param $1  Argument to quote
 # @param $2  Name of variable to return result to
-# @deprecated Use `_comp_quote_compgen "$1"` instead.  Note that
+# @deprecated 2.12 Use `_comp_quote_compgen "$1"` instead.  Note that
 # `_comp_quote_compgen` stores the result in a fixed variable `ret`.
 _quote_readline_by_ref()
 {
@@ -59,8 +59,8 @@ _quote_readline_by_ref()
 }
 
 # This function shell-dequotes the argument
-# @deprecated Use `_comp_dequote' instead.  Note that `_comp_dequote` stores
-#   the results in the array `ret` instead of writing them to stdout.
+# @deprecated 2.12 Use `_comp_dequote' instead.  Note that `_comp_dequote`
+#   stores the results in the array `ret` instead of writing them to stdout.
 dequote()
 {
     local ret
@@ -79,7 +79,7 @@ dequote()
 #       use multiple '_upvar' calls, since one '_upvar' call might
 #       reassign a variable to be used by another '_upvar' call.
 # @see https://fvue.nl/wiki/Bash:_Passing_variables_by_reference
-# @deprecated  Use `_comp_upvars' instead
+# @deprecated 2.10 Use `_comp_upvars' instead
 _upvar()
 {
     echo "bash_completion: $FUNCNAME: deprecated function," \
@@ -107,7 +107,7 @@ _upvar()
 #     current word (default is 0, previous is 1), respecting the exclusions
 #     given at $1.  For example, `_get_cword "=:" 1' returns the word left of
 #     the current word, respecting the exclusions "=:".
-# @deprecated  Use `_comp_get_words cur' instead
+# @deprecated TODO Use `_comp_get_words cur' instead
 # @see _comp_get_words()
 _get_cword()
 {
@@ -158,7 +158,7 @@ _get_cword()
 # This is a good alternative to `prev=${COMP_WORDS[COMP_CWORD-1]}' because bash4
 # will properly return the previous word with respect to any given exclusions to
 # COMP_WORDBREAKS.
-# @deprecated  Use `_comp_get_words cur prev' instead
+# @deprecated TODO Use `_comp_get_words cur prev' instead
 # @see _comp_get_words()
 #
 _get_pword()
@@ -169,7 +169,7 @@ _get_pword()
 }
 
 # Get real command.
-# @deprecated Use `_comp_realcommand` instead.
+# @deprecated 2.12 Use `_comp_realcommand` instead.
 # Note that `_comp_realcommand` stores the result in the variable `ret`
 # instead of writing it to stdout.
 _realcommand()
@@ -202,7 +202,7 @@ _realcommand()
 # @return  True (0) if completion needs further processing,
 #          False (> 0) no further processing is necessary.
 #
-# @deprecated Use the new interface `_comp_initialize`.  The new interface
+# @deprecated 2.12 Use the new interface `_comp_initialize`.  The new interface
 # supports the same set of options.  The new interface receives additional
 # arguments $1 (command name), $2 (part of current word before the cursor), and
 # $3 (previous word) that are specified to the completion function by Bash.
@@ -234,21 +234,21 @@ _init_completion()
     return "$rc"
 }
 
-# @deprecated Use the variable `_comp_backup_glob` instead.  This is the
+# @deprecated 2.12 Use the variable `_comp_backup_glob` instead.  This is the
 # backward-compatibility name.
 # shellcheck disable=SC2154  # defined in the main "bash_completion"
 _backup_glob=$_comp_backup_glob
 
-# @deprecated use `_comp_cmd_cd` instead.
+# @deprecated 2.12 use `_comp_cmd_cd` instead.
 _cd()
 {
     declare -F _comp_cmd_cd &>/dev/null || __load_completion cd
     _comp_cmd_cd "$@"
 }
 
-# @deprecated Use `_comp_command_offset` instead.  Note that the new interface
-# `_comp_command_offset` is changed to receive an index in `words` instead of
-# that in `COMP_WORDS` as `_command_offset` did.
+# @deprecated 2.12 Use `_comp_command_offset` instead.  Note that the new
+# interface `_comp_command_offset` is changed to receive an index in
+# `words` instead of that in `COMP_WORDS` as `_command_offset` did.
 _command_offset()
 {
     # We unset the shell variable `words` locally to tell
@@ -259,7 +259,7 @@ _command_offset()
     _comp_command_offset "$@"
 }
 
-# @deprecated Use `_comp_compgen -a filedir`
+# @deprecated 2.12 Use `_comp_compgen -a filedir`
 _filedir()
 {
     _comp_compgen -a filedir "$@"
@@ -269,17 +269,17 @@ _filedir()
 # @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.
-# @deprecated Use `_comp_compgen -c CUR tilde [-d]`.  Note that the exit status
-# of `_comp_compgen_tilde` is flipped.  It returns 0 when the tilde completions
-# are attempted, or otherwise 1.
+# @deprecated 2.12 Use `_comp_compgen -c CUR tilde [-d]`.  Note that the exit
+# status of `_comp_compgen_tilde` is flipped.  It returns 0 when the tilde
+# completions are attempted, or otherwise 1.
 _tilde()
 {
     ! _comp_compgen -c "$1" tilde
 }
 
 # Helper function for _parse_help and _parse_usage.
 # @return True (0) if an option was found, False (> 0) otherwise
-# @deprecated Use _comp_compgen_help__parse
+# @deprecated 2.12 Use _comp_compgen_help__parse
 __parse_options()
 {
     local -a _options=()
@@ -290,7 +290,7 @@ __parse_options()
 # Parse GNU style help output of the given command.
 # @param $1  command; if "-", read from stdin and ignore rest of args
 # @param $2  command options (default: --help)
-# @deprecated Use `_comp_compgen_help`.  `COMPREPLY=($(compgen -W
+# @deprecated 2.12 Use `_comp_compgen_help`.  `COMPREPLY=($(compgen -W
 #   '$(_parse_help "$1" ...)' -- "$cur"))` can be replaced with
 #   `_comp_compgen_help [-- ...]`.  Also, `var=($(_parse_help "$1" ...))` can
 #   be replaced with `_comp_compgen -Rv var help [-- ...]`.
@@ -314,7 +314,7 @@ _parse_help()
 # Parse BSD style usage output (options in brackets) of the given command.
 # @param $1  command; if "-", read from stdin and ignore rest of args
 # @param $2  command options (default: --usage)
-# @deprecated Use `_comp_compgen_usage`.  `COMPREPLY=($(compgen -W
+# @deprecated 2.12 Use `_comp_compgen_usage`.  `COMPREPLY=($(compgen -W
 #   '$(_parse_usage "$1" ...)' -- "$cur"))` can be replaced with
 #   `_comp_compgen_usage [-- ...]`. `var=($(_parse_usage "$1" ...))` can be
 #   replaced with `_comp_compgen -Rv var usage [-- ...]`.