For most languages a single standard for documenting functions and methods in block comments (a.k.a. doc-blocks) has emerged.
For BASH, however, there does not seem to be a definitive convention. Several competing conventions exist, which made me think:
Could a list of doc-block tags be distilled from those used across all (or most) languages?
Time to find out!
The following conventions are available:
Both TomDoc and the Google Function Comments live in a world totally separated from the other candidates. The other available candidates are all rather similar.
To keep things familiar across different languages TomDoc and Google Comments are rejected from the list.
The only major difference between the remaining candidates is the available tags, and some minor syntax details.
Each of the conventions has the following amount of tags:
- BASHDoc: 11
- JavaDoc: 19
- JsDoc: 77 (64 when not counting aliases )
- LuaDoc: 11
- PHPDoc: 20 (some of which are deprecated)
- TSDoc: 25
- YUIDoc: 45
Combined, this gives a list of almost 140 different tags!
Full list of tags
@abstract
@access
@alias
@alpha
@api
@arg
@argument
@Arguments
@async
@attribute
@augments
@author
@beta
@borrows
@broadcast
@bubbles
@callback
@category
@chainable
@class
@classdesc
@code
@config
@constant
@constructor
@constructs
@contents
@copyright
@decorator
@default
@defaultValue
@deprecated
@description
@docRoot
@element
@emits
@enum
@event
@eventProperty
@example
@exception
@experimental
@exports
@extends
@extension
@extension_for
@extensionfor
@external
@field
@file
@fileoverview
@final
@fires
@for
@func
@function
@global
@Globals
@host
@ignore
@implements
@inheritdoc
@inner
@instance
@interface
@internal
@kind
@label
@lends
@license
@link
@linkcode
@linkplain
@listens
@literal
@main
@member
@memberof
@method
@mixes
@mixin
@module
@name
@namespace
@note
@option
@optional
@overload
@override
@overview
@package
@packageDocumentation
@param
@parents
@private
@privateRemarks
@prop
@property
@protected
@public
@raise
@readOnly
@release
@remarks
@required
@requires
@return
@returns
@sealed
@see
@serial
@serialData
@serialField
@since
@static
@Stderr
@Stdin
@Stdout
@submodule
@summary
@Synopsis
@this
@throws
@todo
@tutorial
@type
@typedef
@typeParam
@usage
@uses
@value
@var
@variation
@version
@virtual
@writeOnce
@yield
@yieldparam
@yieldreturn
The properties of a language will, in part, dictate which tags are useful. Although there is most likely a valid reason for each one of the tags, having more than a dozen tags seem undesirable.
So... which tags are most common?
Cross-referencing the full list of values leads to 18 tags that are used in at least 3 different conventions:
Tag | Count | BASH | Lua | Java | Js | PHP | TS | YARD | YUI |
---|---|---|---|---|---|---|---|---|---|
@author |
6 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ||
@class |
3 | ✅ | ✅ | ✅ | |||||
@copyright |
4 | ✅ | ✅ | ✅ | ✅ | ||||
@deprecated |
6 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ||
@example |
5 | ✅ | ✅ | ✅ | ✅ | ✅ | |||
@inheritdoc |
3 | ✅ | ✅ | ✅ | |||||
@license |
3 | ✅ | ✅ | ✅ | |||||
@link |
3 | ✅ | ✅ | ✅ | |||||
@method |
3 | ✅ | ✅ | ✅ | |||||
@param |
8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@property |
3 | ✅ | ✅ | ✅ | |||||
@readOnly |
3 | ✅ | ✅ | ✅ | |||||
@return(s) |
8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@see |
6 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ||
@since |
5 | ✅ | ✅ | ✅ | ✅ | ✅ | |||
@throws |
5 | ✅ | ✅ | ✅ | ✅ | ✅ | |||
@type |
3 | ✅ | ✅ | ✅ | |||||
@version |
4 | ✅ | ✅ | ✅ | ✅ |
That looks like a more workable set of tags!
But, for BASH, is this all we need? Are things missing? Or superfluous?
Because of the nature of bash, I would suggest adding the following tags:
@global
(or@export
) when declaring or using global variables@uses
(or@requires
) for sources/includes
Although both @global
and @requires
are used by two conventions, I prefer @global
. This is mostly because it is a more accurate description of what is going on.
The tags @uses
and @requires
are also both used by two conventions. Here I prefer @uses
as code might only use something occasionally, which would not make it a requirement, but it would still be a dependency.
Several tags can be removed from the shortlist, as they do not really apply in BASH:
@class
@method
@property
@readOnly
@type
Several other can be removed for other reasons:
@inheritdoc
is an instruction for the document generator@link
is more or less the same as@see
(which is more flexible, as it can "link" to other variables and functions, as well as to a URL)@since
and@version
can both be found through version control
This would leave 11 tags to use.
Three for the header (or file-level) doc-block:
@author
@copyright
@license
Eight for general use:
@deprecated
@example
@global
@param
@return
@see
@throws
@uses
I've already asked several developers to peer-review this text and comment with their opinions.
Any thoughts or feedback you might have are most welcome!
Feedback thus far:
As suggested by @mjrider, valid Types might need to be defined (for instance for @param
).
Besides the suggested STDIN
, STDOUT
and STDERR
, other types would be:
- array
- boolean
- integer
- mixed (any)
- string
In BASH a common use-case is to trap
certain events, like errors or user cancel.
This would require a BASH specific @trap
tag. To be more generic (so it could be used) with other languages, @catches
is suggested (to compliment @throws
)
As suggested by @brammittendorff, the tags @version
and @since
can be removed as that information is better served from git.