Skip to content

Commit 01b34de

Browse files
tmcwtmcw
committed
Add markdown_ast raw AST output mode
1 parent f095485 commit 01b34de

30 files changed

+5278
-121
lines changed

‎lib/format_inline_tags.js

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
var inlineLex = require('jsdoc-inline-lex');
2+
3+
/**
4+
* Format link & tutorial tags with simple code inline tags.
5+
*
6+
* @param {string} text input - typically a description
7+
* @returns {string} markdown-friendly output
8+
* @private
9+
* @example
10+
* formatInlineTags('{@link Foo}'); // "`Foo`"
11+
*/
12+
function formatInlineTags(text) {
13+
var output = '';
14+
var tokens = inlineLex(text);
15+
16+
for (var i = 0; i < tokens.length; i++) {
17+
if (tokens[i].type === 'text') {
18+
output += tokens[i].capture[0];
19+
} else {
20+
output += '`' + tokens[i].capture[1] + '`';
21+
}
22+
}
23+
24+
return output;
25+
}
26+
27+
module.exports = formatInlineTags;

‎lib/output/markdown.js

Lines changed: 5 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -1,114 +1,7 @@
11
'use strict';
22

3-
var extend = require('extend'),
4-
mdast = require('mdast'),
5-
formatType = require('../markdown_format_type'),
6-
toc = require('mdast-toc'),
7-
u = require('unist-builder'),
8-
inlineLex = require('jsdoc-inline-lex');
9-
10-
/**
11-
* Format link & tutorial tags with simple code inline tags.
12-
*
13-
* @param {string} text input - typically a description
14-
* @returns {string} markdown-friendly output
15-
* @private
16-
* @example
17-
* formatInlineTags('{@link Foo}'); // "`Foo`"
18-
*/
19-
function formatInlineTags(text) {
20-
var output = '';
21-
var tokens = inlineLex(text);
22-
23-
for (var i = 0; i < tokens.length; i++) {
24-
if (tokens[i].type === 'text') {
25-
output += tokens[i].capture[0];
26-
} else {
27-
output += '`' + tokens[i].capture[1] + '`';
28-
}
29-
}
30-
31-
return output;
32-
}
33-
34-
function identity(x) {
35-
return x;
36-
}
37-
38-
function paramSection(comment) {
39-
return !!comment.params && u('root', [
40-
u('strong', [u('text', 'Parameters')]),
41-
u('list', { ordered: false }, comment.params.map(function (param) {
42-
return u('listItem', [
43-
u('paragraph', [
44-
u('inlineCode', param.name),
45-
u('text', ' '),
46-
!!param.type && u('strong', [u('text', formatType(param.type))]),
47-
u('text', ' '),
48-
mdast.parse(formatInlineTags(param.description)),
49-
!!param.default && u('root', [
50-
u('text', ' (optional, default '),
51-
u('text', param.default, 'inlineCode'),
52-
u('text', ')')
53-
])
54-
].filter(identity))
55-
]);
56-
}))
57-
]);
58-
}
59-
60-
function propertySection(comment) {
61-
return !!comment.properties && u('root', [
62-
u('strong', [u('text', 'Properties')]),
63-
u('list', { ordered: false },
64-
comment.properties.map(function (property) {
65-
return u('listItem', [
66-
u('paragraph', [
67-
u('inlineCode', property.title),
68-
u('text', ' '),
69-
u('text', [u('text', formatType(property.type))]),
70-
u('text', ' '),
71-
mdast.parse(formatInlineTags(property.description))
72-
])
73-
])
74-
}))
75-
]);
76-
}
77-
78-
function examplesSection(comment) {
79-
return !!comment.examples && u('root', [
80-
u('strong', [u('text', 'Examples')]),
81-
u('root', comment.examples.map(function (example) {
82-
return u('code', { lang: 'javascript' }, example);
83-
}))
84-
]);
85-
}
86-
87-
function returnsSection(comment) {
88-
return !!comment.returns && u('root', comment.returns.map(function (returns) {
89-
return u('paragraph', [
90-
u('text', 'Returns '),
91-
u('strong', [u('text', formatType(returns.type))]),
92-
u('text', ' '),
93-
mdast.parse(formatInlineTags(returns.description))
94-
]);
95-
}));
96-
}
97-
98-
function generate(depth, comment) {
99-
return u('root', [
100-
u('heading', { depth: depth }, [u('text', comment.name)]),
101-
mdast.parse(formatInlineTags(comment.description)),
102-
paramSection(comment),
103-
propertySection(comment),
104-
examplesSection(comment),
105-
returnsSection(comment),
106-
!!comment.members.instance.length &&
107-
u('root', comment.members.instance.map(generate.bind(null, depth + 1))),
108-
!!comment.members.static.length &&
109-
u('root', comment.members.static.map(generate.bind(null, depth + 1))),
110-
].filter(identity));
111-
}
3+
var mdast = require('mdast'),
4+
markdownAST = require('./markdown_ast');
1125

1136
/**
1147
* Formats documentation as
@@ -123,16 +16,7 @@ function generate(depth, comment) {
12316
* @return {undefined} calls callback
12417
*/
12518
module.exports = function (comments, opts, callback) {
126-
127-
opts = opts || {};
128-
129-
if (opts.toc || true) {
130-
mdast.use(toc);
131-
}
132-
133-
var ast = u('root', comments.map(function (comment) {
134-
return generate(1, comment);
135-
}));
136-
137-
return callback(null, mdast.stringify(ast));
19+
markdownAST(comments, opts, function (err, ast) {
20+
return callback(null, mdast.stringify(ast));
21+
});
13822
};

‎lib/output/markdown_ast.js

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
var mdast = require('mdast'),
2+
u = require('unist-builder'),
3+
formatType = require('../markdown_format_type'),
4+
formatInlineTags = require('../format_inline_tags');
5+
6+
function identity(x) {
7+
return x;
8+
}
9+
10+
function commentsToAST(comments, opts, callback) {
11+
function generate(depth, comment) {
12+
function paramSection(comment) {
13+
return !!comment.params && u('root', [
14+
u('strong', [u('text', 'Parameters')]),
15+
u('list', { ordered: false }, comment.params.map(function (param) {
16+
return u('listItem', [
17+
u('paragraph', [
18+
u('inlineCode', param.name),
19+
u('text', ' '),
20+
!!param.type && u('strong', [u('text', formatType(param.type))]),
21+
u('text', ' '),
22+
mdast.parse(formatInlineTags(param.description)),
23+
!!param.default && u('root', [
24+
u('text', ' (optional, default '),
25+
u('text', param.default, 'inlineCode'),
26+
u('text', ')')
27+
])
28+
].filter(identity))
29+
]);
30+
}))
31+
]);
32+
}
33+
34+
function propertySection(comment) {
35+
return !!comment.properties && u('root', [
36+
u('strong', [u('text', 'Properties')]),
37+
u('list', { ordered: false },
38+
comment.properties.map(function (property) {
39+
return u('listItem', [
40+
u('paragraph', [
41+
u('inlineCode', property.title),
42+
u('text', ' '),
43+
u('text', [u('text', formatType(property.type))]),
44+
u('text', ' '),
45+
mdast.parse(formatInlineTags(property.description))
46+
])
47+
])
48+
}))
49+
]);
50+
}
51+
52+
function examplesSection(comment) {
53+
return !!comment.examples && u('root', [
54+
u('strong', [u('text', 'Examples')]),
55+
u('root', comment.examples.map(function (example) {
56+
return u('code', { lang: 'javascript' }, example);
57+
}))
58+
]);
59+
}
60+
61+
function returnsSection(comment) {
62+
return !!comment.returns && u('root', comment.returns.map(function (returns) {
63+
return u('paragraph', [
64+
u('text', 'Returns '),
65+
u('strong', [u('text', formatType(returns.type))]),
66+
u('text', ' '),
67+
mdast.parse(formatInlineTags(returns.description))
68+
]);
69+
}));
70+
}
71+
72+
return u('root', [
73+
u('heading', { depth: depth }, [u('text', comment.name)]),
74+
mdast.parse(formatInlineTags(comment.description)),
75+
paramSection(comment),
76+
propertySection(comment),
77+
examplesSection(comment),
78+
returnsSection(comment),
79+
!!comment.members.instance.length &&
80+
u('root', comment.members.instance.map(generate.bind(null, depth + 1))),
81+
!!comment.members.static.length &&
82+
u('root', comment.members.static.map(generate.bind(null, depth + 1))),
83+
].filter(identity));
84+
}
85+
86+
return callback(null, u('root', comments.map(function (comment) {
87+
return generate(1, comment);
88+
})));
89+
}
90+
91+
module.exports = commentsToAST;

0 commit comments

Comments
 (0)