jsdoc-markdown-remark

ESLint rule to lint JSDoc descriptions using remark.

Usage

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

rule

ESLint rule to enforce that JSDoc descriptions are valid Markdown (using remark). To configure the remark processor to lint Markdown, set the config option with the lint configuration when enabling the ESLint rule.

Bad:

/**
* Beep.
*
*     - Boop.
*
* @returns {string} a value
*
* @example
* var str = beep();
* // returns 'boop'
*/
function beep() {
    return 'boop';
}

Good:

/**
* Beep.
*
* -   Boop.
*
* @returns {string} a value
*
* @example
* var str = beep();
* // returns 'boop'
*/
function beep() {
    return 'boop';
}

Examples

var Linter = require( 'eslint' ).Linter;
var remarkLint = require( 'remark-lint' );
var noDuplicateHeadings = require( 'remark-lint-no-duplicate-headings' );
var rule = require( '@stdlib/_tools/eslint/rules/jsdoc-markdown-remark' );

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

// Generate our source code containing a single lint error (a duplicate heading):
code = [
    '/**',
    '* Beep boop.',
    '*',
    '* Some code...',
    '*',
    '* ```javascript',
    '* var f = foo();',
    '* ```',
    '*',
    '* Some LaTeX...',
    '*',
    '* ```tex',
    '* \\frac{1}{2}',
    '* ```',
    '*',
    '* ## Notes',
    '*',
    '* -   First.',
    '* -   Second.',
    '* -   Third.',
    '*',
    '* ## Notes',
    '*',
    '* This is a repeat section.',
    '*',
    '* ## References',
    '*',
    '* -   Jane Doe. Science. 2017.',
    '*',
    '* | x | y |',
    '* | 1 | 2 |',
    '* | 2 | 1 |',
    '*',
    '*',
    '* @param {string} str - input value',
    '* @returns {string} output value',
    '*',
    '* @example',
    '* var out = beep( "boop" );',
    '* // returns "beepboop"',
    '*/',
    'function beep( str ) {',
    '\treturn "beep" + str;',
    '}'
].join( '\n' );

// Create a remark configuration:
config = {
    'plugins': [
        [ remarkLint ],
        [ noDuplicateHeadings, [ 'error' ] ]
    ]
};

// Register the ESLint rule:
linter.defineRule( 'jsdoc-markdown-remark', rule );

// Lint the code:
result = linter.verify( code, {
    'rules': {
        'jsdoc-markdown-remark': [ 'error', {
            'config': config
        }]
    }
});
console.log( result );
/* =>
    [
        {
            'ruleId': 'jsdoc-markdown-remark',
            'severity': 2,
            'message': '21:1-21:9  error    Do not use headings with similar content (15:1)  no-duplicate-headings  remark-lint',
            'line': 1,
            'column': 1,
            'nodeType': null,
            'source': '/**',
            'endLine': 41,
            'endColumn': 3
        }
    ]
*/