Merge pull request #746 from akinomyoga/refactor-doc-comment

Consistent documentation comments

Author: scop

bash_completion

@@ -173,7 +173,7 @@ dequote()
 # will not unshadow the global variable. Rather, the result will be a local
 # variable in an unset state.
 # Usage: local IFS='|'; _comp_unlocal IFS
-# Param: $* Variable names to be unset
+# @param $* Variable names to be unset
 _comp_unlocal()
 {
     if ((BASH_VERSINFO[0] >= 5)) && shopt -q localvar_unset; then
@@ -187,13 +187,13 @@ _comp_unlocal()
 
 # Assign variable one scope above the caller
 # Usage: local "$1" && _upvar $1 "value(s)"
-# Param: $1  Variable name to assign value to
-# Param: $*  Value(s) to assign.  If multiple values, an array is
+# @param $1  Variable name to assign value to
+# @param $*  Value(s) to assign.  If multiple values, an array is
 #            assigned, otherwise a single value is assigned.
 # NOTE: For assigning multiple variables, use '_upvars'.  Do NOT
 #       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
+# @see https://fvue.nl/wiki/Bash:_Passing_variables_by_reference
 _upvar()
 {
     echo "bash_completion: $FUNCNAME: deprecated function," \
@@ -213,8 +213,8 @@ _upvar()
 # Available OPTIONS:
 #     -aN  Assign next N values to varname as array
 #     -v   Assign single value to varname
-# Return: 1 if error occurs
-# See: https://fvue.nl/wiki/Bash:_Passing_variables_by_reference
+# @return  1 if error occurs
+# @see https://fvue.nl/wiki/Bash:_Passing_variables_by_reference
 _upvars()
 {
     if ! (($#)); then
@@ -1839,13 +1839,14 @@ _included_ssh_config_files()
 # Also hosts from HOSTFILE (compgen -A hostname) are added, unless
 # BASH_COMPLETION_KNOWN_HOSTS_WITH_HOSTFILE is set to an empty value.
 # Usage: _known_hosts_real [OPTIONS] CWORD
-# Options:  -a             Use aliases from ssh config files
-#           -c             Use `:' suffix
-#           -F configfile  Use `configfile' for configuration settings
-#           -p PREFIX      Use PREFIX
-#           -4             Filter IPv6 addresses from results
-#           -6             Filter IPv4 addresses from results
-# Return: Completions, starting with CWORD, are added to COMPREPLY[]
+# Options:
+#     -a             Use aliases from ssh config files
+#     -c             Use `:' suffix
+#     -F configfile  Use `configfile' for configuration settings
+#     -p PREFIX      Use PREFIX
+#     -4             Filter IPv6 addresses from results
+#     -6             Filter IPv4 addresses from results
+# @return Completions, starting with CWORD, are added to COMPREPLY[]
 _known_hosts_real()
 {
     local configfile flag prefix=""