Skip to content

Instantly share code, notes, and snippets.

@Potherca Potherca/README.md
Created Aug 24, 2019

Embed
What would you like to do?
Searching for a generic documentation block convention

Documentation block conventions

For most languages a single standard for documenting functions and methods in block comments (a.k.a. doc-blocks) has emerged.

There does not seem to be a definitive convention for documenting bash functions and files. Several different conventions exist

The long list

The following conventions are available:

Creating a shorter list

Both TomDoc and the Google Function Comments live in a world totally separated from the other candidates.

The other available candidates (BASHDoc, JavaDoc, JsDoc, PhpDoc, YUIDoc) 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.

Tags

Full list of tags

Each of the conventions has the following amount of tags defined:

  • BASHDoc: 11
  • JavaDoc: 19
  • PHPDoc: 20 (some of which are deprecated)
  • YUIDoc: 45
  • JsDoc: 64

Together this gives a list of more than 100 tags. 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.

Full list of tags
  • @abstract
  • @access
  • @alias
  • @api
  • @arguments
  • @async
  • @attribute
  • @augments
  • @author
  • @beta
  • @borrows
  • @broadcast
  • @bubbles
  • @callback
  • @category
  • @chainable
  • @class
  • @classdesc
  • @code
  • @config
  • @constant
  • @constructor
  • @constructs
  • @contents
  • @copyright
  • @default
  • @deprecated
  • @description
  • @docroot
  • @element
  • @enum
  • @event
  • @example
  • @exception
  • @exports
  • @extends
  • @extension
  • @extensionfor
  • @external
  • @file
  • @final
  • @fires
  • @for
  • @function
  • @global
  • @globals
  • @ignore
  • @implements
  • @inheritdoc
  • @inner
  • @instance
  • @interface
  • @internal
  • @kind
  • @lends
  • @license
  • @link
  • @linkplain
  • @listens
  • @literal
  • @main
  • @member
  • @memberof
  • @method
  • @mixes
  • @mixin
  • @module
  • @name
  • @namespace
  • @optional
  • @override
  • @package
  • @param
  • @parents
  • @private
  • @property
  • @protected
  • @public
  • @readonly
  • @required
  • @requires
  • @return
  • @returns
  • @see
  • @serial
  • @serialdata
  • @serialfield
  • @since
  • @static
  • @stderr
  • @stdin
  • @stdout
  • @submodule
  • @summary
  • @synopsis
  • @this
  • @throws
  • @todo
  • @tutorial
  • @type
  • @typedef
  • @uses
  • @value
  • @var
  • @variation
  • @version
  • @writeonce

A shorter list of tags

Cross-referencing these values each of the conventions has the following amount of tags that are also available in other conventions:

  • BASHDoc: 4
  • JavaDoc: 9
  • PHPDoc: 16
  • YUIDoc: 21
  • JsDoc: 25

This looks like a more workable set of tags.

Sorting through the tags.

Because of BASHDoc having a limited and very language specific scope, it is not counted when cross-referencing.

The following tags are available across all of the remaining conventions:

  • @deprecated
  • @link
  • @param
  • @return
  • @see
  • @throws
  • @version

Because of the nature of bash, I would suggest adding the following tags:

  • @global (when declaring or using global variables)
  • @uses (for sources/includes)

For top-level/document level doc-blocks, the following tags could also be added:

  • @copyright
  • @license

The final list of tags.

This would leave the following list of 10 tags to use:

  • @copyright
  • @deprecated
  • @global (when declaring or using global variables)
  • @license
  • @link
  • @param
  • @return
  • @see
  • @throws
  • @uses (for sources/includes)

Request for feedback

I've asked several developers to peer-review this text and comment with their opinions?

Feedback thus far

Types

As suggested by @mjrider, valid Types need to be defined (for instance for @param).

Besides the suggested STDIN, STDOUT and STDERR, types would be:

  • array
  • boolean
  • integer
  • mixed (any)
  • string

Trapping error

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.

Unneeded tags

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

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
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.