Potherca/README.md

## README.md

      
    Raw
  

              README.md
            
          
    Documentation block tags conventions for BASH

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!
Available conventions

The following conventions are available:

BASHDoc
Google Function Comments
JavaDoc
jsdoc
LuaDoc
PhpDoc
Ruby YARD
TomDoc
TSDoc
YUIDoc

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.
Full list of tags

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?
Creating a shorter list

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?
What you gain on the swings...

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.
...you lose on the roundabouts

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

The final list of tags.

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

Request for feedback

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:
Types

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

Trapping signals

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)
Unneeded tags

As suggested by @brammittendorff, the tags @version and @since can be removed as that information is better served from git.

  
## bashdoc.txt
BASHDoc - http://sourcemage.org/bashdoc

@param
@Arguments
@Stdout
@Stderr
@Stdin
@return
@Globals
@Type
@Synopsis
@Copyright
@License

## javadoc.txt
JavaDoc - http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#tag

@author
@code{}
@docRoot{}
@deprecated
@exception
@inheritDoc{}
@link{}
@linkplain{}
@literal{}
@param
@return
@see
@serial
@serialData
@serialField
@since
@throws
@value{}
@version

## jsdoc.txt
JsDoc - http://usejsdoc.org/#block-tags

@abstract (synonyms: @virtual)
@access
@alias
@augments (synonyms: @extends)
@author
@borrows
@callback
@class (synonyms: @constructor)
@classdesc
@constant (synonyms: @const)
@constructs
@copyright
@default (synonyms: @defaultvalue)
@deprecated
@description (synonyms: @desc)
@enum
@event
@example
@exports
@external (synonyms: @host)
@file (synonyms: @fileoverview, @overview)
@fires (synonyms: @emits)
@function (synonyms: @func, @method)
@global
@ignore
@implements
@inheritdoc
@inner
@instance
@interface
@kind
@lends
@license
@link{} (synonyms: @linkcode{}, @linkplain{})
@listens
@member (synonyms: @var)
@memberof
@mixes
@mixin
@module
@name
@namespace
@override
@param (synonyms: @arg, @argument)
@private
@property (synonyms: @prop)
@protected
@public
@readonly
@requires
@returns (synonyms: @return)
@see
@since
@static
@summary
@this
@throws (synonyms: @exception)
@todo
@tutorial
@tutorial{}
@type
@typedef
@variation
@version

## phpdoc.txt
PHPDoc - https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md

@api
@author
@copyright
@deprecated
@example
@global
@internal
@license
@method
@package
@param
@property
@return
@see
@since
@throws
@todo
@uses
@var
@version

## tsdoc.txt
TSDoc - https://tsdoc.org/

@alpha
@beta
@decorator
@deprecated
@defaultValue
@eventProperty
@example
@experimental
@inheritDoc
@internal
@label
@link
@override
@packageDocumentation
@param
@privateRemarks
@public
@readonly
@remarks
@returns
@sealed
@see
@throws
@typeParam
@virtual

## yuidoc.txt
YUIDoc - http://yui.github.io/yuidoc/syntax/index.html

@async
@attribute
@author
@beta
@broadcast
@bubbles
@category*
@chainable
@class
@config
@constructor
@contents
@default
@deprecated
@element
@event
@example*
@extends
@extension
@extension_for
@extensionfor
@final
@for
@interface
@main
@method
@module
@namespace
@optional
@param*
@parents
@private
@property
@protected
@readOnly
@required
@requires
@return
@since
@static
@submodule
@throws
@type
@uses*
@writeOnce
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			✅	✅	✅		✅
	BASHDoc - http://sourcemage.org/bashdoc

	@param
	@Arguments
	@Stdout
	@Stderr
	@Stdin
	@return
	@Globals
	@Type
	@Synopsis
	@Copyright
	@License
	JavaDoc - http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#tag

	@author
	@code{}
	@docRoot{}
	@deprecated
	@exception
	@inheritDoc{}
	@link{}
	@linkplain{}
	@literal{}
	@param
	@return
	@see
	@serial
	@serialData
	@serialField
	@since
	@throws
	@value{}
	@version
	JsDoc - http://usejsdoc.org/#block-tags

	@abstract (synonyms: @virtual)
	@access
	@alias
	@augments (synonyms: @extends)
	@author
	@borrows
	@callback
	@class (synonyms: @constructor)
	@classdesc
	@constant (synonyms: @const)
	@constructs
	@copyright
	@default (synonyms: @defaultvalue)
	@deprecated
	@description (synonyms: @desc)
	@enum
	@event
	@example
	@exports
	@external (synonyms: @host)
	@file (synonyms: @fileoverview, @overview)
	@fires (synonyms: @emits)
	@function (synonyms: @func, @method)
	@global
	@ignore
	@implements
	@inheritdoc
	@inner
	@instance
	@interface
	@kind
	@lends
	@license
	@link{} (synonyms: @linkcode{}, @linkplain{})
	@listens
	@member (synonyms: @var)
	@memberof
	@mixes
	@mixin
	@module
	@name
	@namespace
	@override
	@param (synonyms: @arg, @argument)
	@private
	@property (synonyms: @prop)
	@protected
	@public
	@readonly
	@requires
	@returns (synonyms: @return)
	@see
	@since
	@static
	@summary
	@this
	@throws (synonyms: @exception)
	@todo
	@tutorial
	@tutorial{}
	@type
	@typedef
	@variation
	@version
	PHPDoc - https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md

	@api
	@author
	@copyright
	@deprecated
	@example
	@global
	@internal
	@license
	@method
	@package
	@param
	@property
	@return
	@see
	@since
	@throws
	@todo
	@uses
	@var
	@version
	TSDoc - https://tsdoc.org/

	@alpha
	@beta
	@decorator
	@deprecated
	@defaultValue
	@eventProperty
	@example
	@experimental
	@inheritDoc
	@internal
	@label
	@link
	@override
	@packageDocumentation
	@param
	@privateRemarks
	@public
	@readonly
	@remarks
	@returns
	@sealed
	@see
	@throws
	@typeParam
	@virtual
	YUIDoc - http://yui.github.io/yuidoc/syntax/index.html

	@async
	@attribute
	@author
	@beta
	@broadcast
	@bubbles
	@category*
	@chainable
	@class
	@config
	@constructor
	@contents
	@default
	@deprecated
	@element
	@event
	@example*
	@extends
	@extension
	@extension_for
	@extensionfor
	@final
	@for
	@interface
	@main
	@method
	@module
	@namespace
	@optional
	@param*
	@parents
	@private
	@property
	@protected
	@readOnly
	@required
	@requires
	@return
	@since
	@static
	@submodule
	@throws
	@type
	@uses*
	@writeOnce