Skip to content

Commit 6403834

Browse files
kgrytekgryte
committed
Add README
1 parent e6f3b28 commit 6403834

1 file changed

Lines changed: 179 additions & 0 deletions

File tree

  • lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-markdown-remark

‎lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-markdown-remark/README.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# jsdoc-markdown-remark
2+
3+
> [ESLint rule][eslint-rules] to enforce that JSDoc descriptions are valid Markdown (using [remark][remark]).
4+
5+
<section class="intro">
6+
7+
</section>
8+
9+
<!-- /.intro -->
10+
11+
<section class="usage">
12+
13+
## Usage
14+
15+
```javascript
16+
var rule = require( '@stdlib/_tools/eslint/rules/jsdoc-markdown-remark' );
17+
```
18+
19+
#### rule
20+
21+
[ESLint rule][eslint-rules] to enforce that JSDoc descriptions are valid Markdown (using [remark][remark]). To configure the [remark][remark] processor to lint Markdown, set the `config` option with the lint configuration when enabling the [ESLint rule][eslint-rules].
22+
23+
**Bad**:
24+
25+
<!-- eslint-disable stdlib/jsdoc-markdown-remark -->
26+
27+
```javascript
28+
/**
29+
* Beep.
30+
*
31+
* - Boop.
32+
*
33+
* @returns {string} a value
34+
*
35+
* @example
36+
* var str = beep();
37+
* // returns 'boop'
38+
*/
39+
function beep() {
40+
return 'boop';
41+
}
42+
```
43+
44+
**Good**:
45+
46+
```javascript
47+
/**
48+
* Beep.
49+
*
50+
* - Boop.
51+
*
52+
* @returns {string} a value
53+
*
54+
* @example
55+
* var str = beep();
56+
* // returns 'boop'
57+
*/
58+
function beep() {
59+
return 'boop';
60+
}
61+
```
62+
63+
</section>
64+
65+
<!-- /.usage -->
66+
67+
<section class="examples">
68+
69+
## Examples
70+
71+
```javascript
72+
var Linter = require( 'eslint' ).Linter;
73+
var remarkLint = require( 'remark-lint' );
74+
var noDuplicateHeadings = require( 'remark-lint-no-duplicate-headings' );
75+
var rule = require( '@stdlib/_tools/eslint/rules/jsdoc-markdown-remark' );
76+
77+
var linter = new Linter();
78+
var config;
79+
var result;
80+
var code;
81+
82+
// Generate our source code containing a single lint error (a duplicate heading):
83+
code = [
84+
'/**',
85+
'* Beep boop.',
86+
'*',
87+
'* Some code...',
88+
'*',
89+
'* ```javascript',
90+
'* var f = foo();',
91+
'* ```',
92+
'*',
93+
'* Some LaTeX...',
94+
'*',
95+
'* ```tex',
96+
'* \\frac{1}{2}',
97+
'* ```',
98+
'*',
99+
'* ## Notes',
100+
'*',
101+
'* - First.',
102+
'* - Second.',
103+
'* - Third.',
104+
'*',
105+
'* ## Notes',
106+
'*',
107+
'* This is a repeat section.',
108+
'*',
109+
'* ## References',
110+
'*',
111+
'* - Jane Doe. Science. 2017.',
112+
'*',
113+
'* | x | y |',
114+
'* | 1 | 2 |',
115+
'* | 2 | 1 |',
116+
'*',
117+
'*',
118+
'* @param {string} str - input value',
119+
'* @returns {string} output value',
120+
'*',
121+
'* @example',
122+
'* var out = beep( "boop" );',
123+
'* // returns "beepboop"',
124+
'*/',
125+
'function beep( str ) {',
126+
'\treturn "beep" + str;',
127+
'}'
128+
].join( '\n' );
129+
130+
// Create a remark configuration:
131+
config = {
132+
'plugins': [
133+
[ remarkLint ],
134+
[ noDuplicateHeadings, [ 'error' ] ]
135+
]
136+
};
137+
138+
// Register the ESLint rule:
139+
linter.defineRule( 'jsdoc-markdown-remark', rule );
140+
141+
// Lint the code:
142+
result = linter.verify( code, {
143+
'rules': {
144+
'jsdoc-markdown-remark': [ 'error', {
145+
'config': config
146+
}]
147+
}
148+
});
149+
console.log( result );
150+
/* =>
151+
[
152+
{
153+
'ruleId': 'jsdoc-markdown-remark',
154+
'severity': 2,
155+
'message': '21:1-21:9 error Do not use headings with similar content (15:1) no-duplicate-headings remark-lint',
156+
'line': 1,
157+
'column': 1,
158+
'nodeType': null,
159+
'source': '/**',
160+
'endLine': 41,
161+
'endColumn': 3
162+
}
163+
]
164+
*/
165+
```
166+
167+
</section>
168+
169+
<!-- /.examples -->
170+
171+
<section class="links">
172+
173+
[eslint-rules]: https://eslint.org/docs/developer-guide/working-with-rules
174+
175+
[remark]: https://github.com/wooorm/remark
176+
177+
</section>
178+
179+
<!-- /.links -->

0 commit comments

Comments
 (0)