Consistent documentation comments

[akinomyoga]

The documentation comments (doc comments) of some functions are not consistent with others. This PR fixes it.

Discussion

Maybe we can also discuss the syntax of doc comments used in bash-completion here. #736 (comment) is a related comment.

• What is the set of directives of the form @xxxxx used in bash-completion?
  • Currently, @param, @see, @deprecated, @return are used in the codebase.
  • Is the current syntax in bash-completion doc comments defined by Javadoc?
  • Is there already any tool to process these doc comments? If not, maybe we can introduce one or may create a simple script to extract these comments.
• Can we introduce @var that is used to mark the variable name referenced or modified by the function?
• @usage might also be useful. Currently, usages are written as Usage: .... in the comment, e.g.,
  

  bash-completion/bash_completion

  Line 181 in 6f1bbda

  # Usage: local "$1" && _upvar $1 "value(s)"

  
  

  bash-completion/bash_completion

  Lines 203 to 204 in 6f1bbda

  	# Usage: local varname [varname ...] &&
  	# _upvars [-v varname value] | [-aN varname [value ...]] ...

• @option might also be useful.

[scop]

I'm not aware of a processor nor a specific set of keywords to use with the @ prefixed markers. They were introduced by someone else a long time ago. They do look a lot like Java/PHP comments.

To me, the most important thing regarding these comment blocks would be to show a "quick help" in editors/IDE's with the info from the comments when hovering over a function, either just as-is, or if there's some structure supported, even better. Personally for shell code I'm using mostly Emacs, and JetBrains IDEs every now and then, and ad hoc vim edits at times, but I'm not aware of a comment/doc format for shell code that would work with any of these (haven't even really looked TBH though). In addition to that, I wouldn't mind a processor that can be run separately to produce e.g. HTML docs, but quite frankly that's not at all that interesting to me.

[akinomyoga]

I'm not aware of a processor nor a specific set of keywords to use with the @ prefixed markers. They were introduced by someone else a long time ago. They do look a lot like Java/PHP comments.

I see, thanks for the information!