jsdoc-tag-ordering

ESLint rule to enforce that JSDoc tags follow a specified ordering.

Usage

var rule = require( '@stdlib/_tools/eslint/rules/jsdoc-tag-ordering' );

rule

ESLint rule to enforce that JSDoc tags follow a specified ordering. By default, tags have to appear in the following order:

  • @private
  • @module
  • @namespace
  • @constructor
  • @constant
  • @function
  • @name
  • @memberof
  • @readonly
  • @type
  • @param
  • @throws
  • @returns
  • @default
  • @see
  • @example

To change the default tag ordering, set the order option of the rule.

Bad:

/**
* Calculates the square root of a number.
*
* @param {NonNegativeNumber} x - input number
* @returns {number} x squared
* @throws {RangeError} x must be a non-negative number
*
* @example
* var y = square( 2.0 );
* // returns 4.0
*/
function sqrt( x ) {
    if ( x < 0 ) {
        throw new RangeError( 'argument must be a non-negative number. Value: '+x );
    }
    return Math.sqrt( x );
}

Good:

/**
* Calculates the square root of a number.
*
* @param {NonNegativeNumber} x - input number
* @throws {RangeError} x must be a non-negative number
* @returns {number} x squared
*
* @example
* var y = sqrt( 4.0 );
* // returns 2.0
*/
function sqrt( x ) {
    if ( x < 0 ) {
        throw new RangeError( 'argument must be a non-negative number. Value: '+x );
    }
    return Math.sqrt( x );
}

Examples

var Linter = require( 'eslint' ).Linter;
var rule = require( '@stdlib/_tools/eslint/rules/jsdoc-tag-ordering' );

var linter = new Linter();
var result;
var code;

code = [
    '/**',
    '* Squares a number.',
    '* ',
    '* @returns {number} x squared',
    '* @param {number} x - input number',
    '*',
    '* @examples',
    '* var y = square( 2.0 );',
    '* // returns 4.0',
    '*/',
    'function square( x ) {',
    '  return x*x;',
    '}'
].join( '\n' );

linter.defineRule( 'jsdoc-tag-ordering', rule );

result = linter.verify( code, {
    'rules': {
        'jsdoc-tag-ordering': 'error'
    }
});
console.log( result );
/* =>
    [
        {
            'ruleId': 'jsdoc-tag-ordering',
            'severity': 2,
            'message': '"@param" tag should not follow "@returns',
            'line': 1,
            'column': 1,
            'nodeType': null,
            'source': '/**',
            'endLine': 10,
            'endColumn': 3
        }
    ]
*/