diff --git a/bin/documentation.js b/bin/documentation.js index 5bd322670..9ecd0ff16 100755 --- a/bin/documentation.js +++ b/bin/documentation.js @@ -4,15 +4,14 @@ 'use strict'; -var yargs = require('yargs'), - commands = require('../lib/commands'); +var yargs = require('yargs'), commands = require('../lib/commands'); var argv = yargs .command(commands.serve) .command(commands.build) .command(commands.lint) .command(commands.readme) - .fail(function (msg, error) { + .fail(function(msg, error) { if (error) { throw error; } else { @@ -21,10 +20,11 @@ var argv = yargs return yargs.exit(1); } }) - .version(function () { + .version(function() { return require('../package').version; }) - .usage(`Usage: + .usage( + `Usage: # generate markdown docs for index.js and files it references $0 build index.js -f md @@ -46,13 +46,15 @@ var argv = yargs # build docs for all values exported by index.js $0 build --document-exported index.js -`) +` + ) .recommendCommands() - .help() - .argv; + .help().argv; if (argv.private) { - console.error('--private is deprecated, please use the --access (or -a) option instead'); + console.error( + '--private is deprecated, please use the --access (or -a) option instead' + ); console.error('for example: -a public -a private -a protected -a undefined'); } diff --git a/default_theme/assets/anchor.js b/default_theme/assets/anchor.js index 47d871ad4..476a8f9ab 100644 --- a/default_theme/assets/anchor.js +++ b/default_theme/assets/anchor.js @@ -6,13 +6,18 @@ function AnchorJS(options) { 'use strict'; - this.options = options || {}; this._applyRemainingDefaultOptions = function(opts) { - this.options.icon = this.options.hasOwnProperty('icon') ? opts.icon : '\ue9cb'; // Accepts characters (and also URLs?), like '#', '¶', '❡', or '§'. - this.options.visible = this.options.hasOwnProperty('visible') ? opts.visible : 'hover'; // Also accepts 'always' - this.options.placement = this.options.hasOwnProperty('placement') ? opts.placement : 'right'; // Also accepts 'left' + this.options.icon = this.options.hasOwnProperty('icon') + ? opts.icon + : '\ue9cb'; // Accepts characters (and also URLs?), like '#', '¶', '❡', or '§'. + this.options.visible = this.options.hasOwnProperty('visible') + ? opts.visible + : 'hover'; // Also accepts 'always' + this.options.placement = this.options.hasOwnProperty('placement') + ? opts.placement + : 'right'; // Also accepts 'left' this.options.class = this.options.hasOwnProperty('class') ? opts.class : ''; // Accepts any class name. }; @@ -20,17 +25,17 @@ function AnchorJS(options) { this.add = function(selector) { var elements, - elsWithIds, - idList, - elementID, - i, - roughText, - tidyText, - index, - count, - newTidyText, - readableID, - anchor; + elsWithIds, + idList, + elementID, + i, + roughText, + tidyText, + index, + count, + newTidyText, + readableID, + anchor; this._applyRemainingDefaultOptions(this.options); @@ -55,7 +60,6 @@ function AnchorJS(options) { }); for (i = 0; i < elements.length; i++) { - if (elements[i].hasAttribute('id')) { elementID = elements[i].getAttribute('id'); } else { @@ -65,12 +69,13 @@ function AnchorJS(options) { // spaces with hyphens, truncate to 32 characters, and make toLowerCase. // // Example string: // '⚡⚡⚡ Unicode icons are cool--but they definitely don't belong in a URL fragment.' - tidyText = roughText.replace(/[^\w\s-]/gi, '') // ' Unicode icons are cool--but they definitely dont belong in a URL fragment' - .replace(/\s+/g, '-') // '-Unicode-icons-are-cool--but-they-definitely-dont-belong-in-a-URL-fragment' - .replace(/-{2,}/g, '-') // '-Unicode-icons-are-cool-but-they-definitely-dont-belong-in-a-URL-fragment' - .substring(0, 64) // '-Unicode-icons-are-cool-but-they-definitely-dont-belong-in-a-URL' - .replace(/^-+|-+$/gm, '') // 'Unicode-icons-are-cool-but-they-definitely-dont-belong-in-a-URL' - .toLowerCase(); // 'unicode-icons-are-cool-but-they-definitely-dont-belong-in-a-url' + tidyText = roughText + .replace(/[^\w\s-]/gi, '') // ' Unicode icons are cool--but they definitely dont belong in a URL fragment' + .replace(/\s+/g, '-') // '-Unicode-icons-are-cool--but-they-definitely-dont-belong-in-a-URL-fragment' + .replace(/-{2,}/g, '-') // '-Unicode-icons-are-cool-but-they-definitely-dont-belong-in-a-URL-fragment' + .substring(0, 64) // '-Unicode-icons-are-cool-but-they-definitely-dont-belong-in-a-URL' + .replace(/^-+|-+$/gm, '') // 'Unicode-icons-are-cool-but-they-definitely-dont-belong-in-a-URL' + .toLowerCase(); // 'unicode-icons-are-cool-but-they-definitely-dont-belong-in-a-url' // Compare our generated ID to existing IDs (and increment it if needed) // before we add it to the page. @@ -121,7 +126,8 @@ function AnchorJS(options) { anchor.style.marginLeft = '-1em'; anchor.style.paddingRight = '0.5em'; elements[i].insertBefore(anchor, elements[i].firstChild); - } else { // if the option provided is `right` (or anything else). + } else { + // if the option provided is `right` (or anything else). anchor.style.paddingLeft = '0.375em'; elements[i].appendChild(anchor); } @@ -131,8 +137,7 @@ function AnchorJS(options) { }; this.remove = function(selector) { - var domAnchor, - elements = document.querySelectorAll(selector); + var domAnchor, elements = document.querySelectorAll(selector); for (var i = 0; i < elements.length; i++) { domAnchor = elements[i].querySelector('.anchorjs-link'); if (domAnchor) { @@ -149,30 +154,26 @@ function AnchorJS(options) { } var style = document.createElement('style'), - linkRule = - ' .anchorjs-link {' + - ' opacity: 0;' + - ' text-decoration: none;' + + linkRule = ' .anchorjs-link {' + + ' opacity: 0;' + + ' text-decoration: none;' + ' -webkit-font-smoothing: antialiased;' + - ' -moz-osx-font-smoothing: grayscale;' + + ' -moz-osx-font-smoothing: grayscale;' + ' }', - hoverRule = - ' *:hover > .anchorjs-link,' + - ' .anchorjs-link:focus {' + - ' opacity: 1;' + + hoverRule = ' *:hover > .anchorjs-link,' + + ' .anchorjs-link:focus {' + + ' opacity: 1;' + ' }', - anchorjsLinkFontFace = - ' @font-face {' + - ' font-family: "anchorjs-icons";' + - ' font-style: normal;' + - ' font-weight: normal;' + // Icon from icomoon; 10px wide & 10px tall; 2 empty below & 4 above + anchorjsLinkFontFace = ' @font-face {' + + ' font-family: "anchorjs-icons";' + + ' font-style: normal;' + + ' font-weight: normal;' + // Icon from icomoon; 10px wide & 10px tall; 2 empty below & 4 above ' src: url(data:application/x-font-ttf;charset=utf-8;base64,AAEAAAALAIAAAwAwT1MvMg8SBTUAAAC8AAAAYGNtYXAWi9QdAAABHAAAAFRnYXNwAAAAEAAAAXAAAAAIZ2x5Zgq29TcAAAF4AAABNGhlYWQEZM3pAAACrAAAADZoaGVhBhUDxgAAAuQAAAAkaG10eASAADEAAAMIAAAAFGxvY2EAKACuAAADHAAAAAxtYXhwAAgAVwAAAygAAAAgbmFtZQ5yJ3cAAANIAAAB2nBvc3QAAwAAAAAFJAAAACAAAwJAAZAABQAAApkCzAAAAI8CmQLMAAAB6wAzAQkAAAAAAAAAAAAAAAAAAAABEAAAAAAAAAAAAAAAAAAAAABAAADpywPA/8AAQAPAAEAAAAABAAAAAAAAAAAAAAAgAAAAAAADAAAAAwAAABwAAQADAAAAHAADAAEAAAAcAAQAOAAAAAoACAACAAIAAQAg6cv//f//AAAAAAAg6cv//f//AAH/4xY5AAMAAQAAAAAAAAAAAAAAAQAB//8ADwABAAAAAAAAAAAAAgAANzkBAAAAAAEAAAAAAAAAAAACAAA3OQEAAAAAAQAAAAAAAAAAAAIAADc5AQAAAAACADEARAJTAsAAKwBUAAABIiYnJjQ/AT4BMzIWFxYUDwEGIicmND8BNjQnLgEjIgYPAQYUFxYUBw4BIwciJicmND8BNjIXFhQPAQYUFx4BMzI2PwE2NCcmNDc2MhcWFA8BDgEjARQGDAUtLXoWOR8fORYtLTgKGwoKCjgaGg0gEhIgDXoaGgkJBQwHdR85Fi0tOAobCgoKOBoaDSASEiANehoaCQkKGwotLXoWOR8BMwUFLYEuehYXFxYugC44CQkKGwo4GkoaDQ0NDXoaShoKGwoFBe8XFi6ALjgJCQobCjgaShoNDQ0NehpKGgobCgoKLYEuehYXAAEAAAABAACiToc1Xw889QALBAAAAAAA0XnFFgAAAADRecUWAAAAAAJTAsAAAAAIAAIAAAAAAAAAAQAAA8D/wAAABAAAAAAAAlMAAQAAAAAAAAAAAAAAAAAAAAUAAAAAAAAAAAAAAAACAAAAAoAAMQAAAAAACgAUAB4AmgABAAAABQBVAAIAAAAAAAIAAAAAAAAAAAAAAAAAAAAAAAAADgCuAAEAAAAAAAEADgAAAAEAAAAAAAIABwCfAAEAAAAAAAMADgBLAAEAAAAAAAQADgC0AAEAAAAAAAUACwAqAAEAAAAAAAYADgB1AAEAAAAAAAoAGgDeAAMAAQQJAAEAHAAOAAMAAQQJAAIADgCmAAMAAQQJAAMAHABZAAMAAQQJAAQAHADCAAMAAQQJAAUAFgA1AAMAAQQJAAYAHACDAAMAAQQJAAoANAD4YW5jaG9yanMtaWNvbnMAYQBuAGMAaABvAHIAagBzAC0AaQBjAG8AbgBzVmVyc2lvbiAxLjAAVgBlAHIAcwBpAG8AbgAgADEALgAwYW5jaG9yanMtaWNvbnMAYQBuAGMAaABvAHIAagBzAC0AaQBjAG8AbgBzYW5jaG9yanMtaWNvbnMAYQBuAGMAaABvAHIAagBzAC0AaQBjAG8AbgBzUmVndWxhcgBSAGUAZwB1AGwAYQByYW5jaG9yanMtaWNvbnMAYQBuAGMAaABvAHIAagBzAC0AaQBjAG8AbgBzRm9udCBnZW5lcmF0ZWQgYnkgSWNvTW9vbi4ARgBvAG4AdAAgAGcAZQBuAGUAcgBhAHQAZQBkACAAYgB5ACAASQBjAG8ATQBvAG8AbgAuAAAAAwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==) format("truetype");' + ' }', - pseudoElContent = - ' [data-anchorjs-icon]::after {' + - ' content: attr(data-anchorjs-icon);' + + pseudoElContent = ' [data-anchorjs-icon]::after {' + + ' content: attr(data-anchorjs-icon);' + ' }', - firstStyleEl; + firstStyleEl; style.className = 'anchorjs'; style.appendChild(document.createTextNode('')); // Necessary for Webkit. diff --git a/default_theme/assets/site.js b/default_theme/assets/site.js index 559c65e5f..55ada036f 100644 --- a/default_theme/assets/site.js +++ b/default_theme/assets/site.js @@ -5,48 +5,45 @@ anchors.options.placement = 'left'; anchors.add('h3'); // Filter UI -var tocElements = document.getElementById('toc') - .getElementsByTagName('li'); - -document.getElementById('filter-input') - .addEventListener('keyup', function (e) { - - var i, element, children; - - // enter key - if (e.keyCode === 13) { - // go to the first displayed item in the toc - for (i = 0; i < tocElements.length; i++) { - element = tocElements[i]; - if (!element.classList.contains('display-none')) { - location.replace(element.firstChild.href); - return e.preventDefault(); - } +var tocElements = document.getElementById('toc').getElementsByTagName('li'); + +document.getElementById('filter-input').addEventListener('keyup', function(e) { + var i, element, children; + + // enter key + if (e.keyCode === 13) { + // go to the first displayed item in the toc + for (i = 0; i < tocElements.length; i++) { + element = tocElements[i]; + if (!element.classList.contains('display-none')) { + location.replace(element.firstChild.href); + return e.preventDefault(); } } + } - var match = function () { - return true; - }; + var match = function() { + return true; + }; - var value = this.value.toLowerCase(); + var value = this.value.toLowerCase(); - if (!value.match(/^\s*$/)) { - match = function (element) { - return element.firstChild.innerHTML.toLowerCase().indexOf(value) !== -1; - }; - } + if (!value.match(/^\s*$/)) { + match = function(element) { + return element.firstChild.innerHTML.toLowerCase().indexOf(value) !== -1; + }; + } - for (i = 0; i < tocElements.length; i++) { - element = tocElements[i]; - children = Array.from(element.getElementsByTagName('li')); - if (match(element) || children.some(match)) { - element.classList.remove('display-none'); - } else { - element.classList.add('display-none'); - } + for (i = 0; i < tocElements.length; i++) { + element = tocElements[i]; + children = Array.from(element.getElementsByTagName('li')); + if (match(element) || children.some(match)) { + element.classList.remove('display-none'); + } else { + element.classList.add('display-none'); } - }); + } +}); var toggles = document.getElementsByClassName('toggle-step-sibling'); for (var i = 0; i < toggles.length; i++) { @@ -54,7 +51,9 @@ for (var i = 0; i < toggles.length; i++) { } function toggleStepSibling() { - var stepSibling = this.parentNode.parentNode.parentNode.getElementsByClassName('toggle-target')[0]; + var stepSibling = this.parentNode.parentNode.parentNode.getElementsByClassName( + 'toggle-target' + )[0]; var klass = 'display-none'; if (stepSibling.classList.contains(klass)) { stepSibling.classList.remove(klass); @@ -86,8 +85,11 @@ function toggleSibling() { function showHashTarget(targetId) { var hashTarget = document.getElementById(targetId); // new target is hidden - if (hashTarget && hashTarget.offsetHeight === 0 && - hashTarget.parentNode.parentNode.classList.contains('display-none')) { + if ( + hashTarget && + hashTarget.offsetHeight === 0 && + hashTarget.parentNode.parentNode.classList.contains('display-none') + ) { hashTarget.parentNode.parentNode.classList.remove('display-none'); } } diff --git a/default_theme/index.js b/default_theme/index.js index 537b80d20..1c5347215 100644 --- a/default_theme/index.js +++ b/default_theme/index.js @@ -11,13 +11,16 @@ var fs = require('fs'), LinkerStack = require('../').util.LinkerStack, hljs = require('highlight.js'); -module.exports = function (comments/*: Array */, config/*: DocumentationConfig */) { - - var linkerStack = new LinkerStack(config) - .namespaceResolver(comments, function (namespace) { - var slugger = new GithubSlugger(); - return '#' + slugger.slug(namespace); - }); +module.exports = function( + comments /*: Array */, + config /*: DocumentationConfig */ +) { + var linkerStack = new LinkerStack( + config + ).namespaceResolver(comments, function(namespace) { + var slugger = new GithubSlugger(); + return '#' + slugger.slug(namespace); + }); var formatters = createFormatters(linkerStack.link); @@ -47,13 +50,17 @@ module.exports = function (comments/*: Array */, config/*: Documentatio return section.name; } if (section.returns.length) { - returns = ': ' + - formatters.type(section.returns[0].type); + returns = ': ' + formatters.type(section.returns[0].type); } return prefix + section.name + formatters.parameters(section) + returns; }, md(ast, inline) { - if (inline && ast && ast.children.length && ast.children[0].type === 'paragraph') { + if ( + inline && + ast && + ast.children.length && + ast.children[0].type === 'paragraph' + ) { ast = { type: 'root', children: ast.children[0].children.concat(ast.children.slice(1)) @@ -71,24 +78,44 @@ module.exports = function (comments/*: Array */, config/*: Documentatio } } }; - - sharedImports.imports.renderSectionList = _.template(fs.readFileSync(path.join(__dirname, 'section_list._'), 'utf8'), sharedImports); - sharedImports.imports.renderSection = _.template(fs.readFileSync(path.join(__dirname, 'section._'), 'utf8'), sharedImports); - sharedImports.imports.renderNote = _.template(fs.readFileSync(path.join(__dirname, 'note._'), 'utf8'), sharedImports); - var pageTemplate = _.template(fs.readFileSync(path.join(__dirname, 'index._'), 'utf8'), sharedImports); + sharedImports.imports.renderSectionList = _.template( + fs.readFileSync(path.join(__dirname, 'section_list._'), 'utf8'), + sharedImports + ); + sharedImports.imports.renderSection = _.template( + fs.readFileSync(path.join(__dirname, 'section._'), 'utf8'), + sharedImports + ); + sharedImports.imports.renderNote = _.template( + fs.readFileSync(path.join(__dirname, 'note._'), 'utf8'), + sharedImports + ); + + var pageTemplate = _.template( + fs.readFileSync(path.join(__dirname, 'index._'), 'utf8'), + sharedImports + ); // push assets into the pipeline as well. return new Promise(resolve => { - vfs.src([__dirname + '/assets/**'], { base: __dirname }) - .pipe(concat(function (files) { - resolve(files.concat(new File({ - path: 'index.html', - contents: new Buffer(pageTemplate({ - docs: comments, - config: config - }), 'utf8') - }))); - })); + vfs.src([__dirname + '/assets/**'], { base: __dirname }).pipe( + concat(function(files) { + resolve( + files.concat( + new File({ + path: 'index.html', + contents: new Buffer( + pageTemplate({ + docs: comments, + config: config + }), + 'utf8' + ) + }) + ) + ); + }) + ); }); }; diff --git a/default_theme/test/format_markdown.js b/default_theme/test/format_markdown.js index 403188cc1..d50b71ce0 100644 --- a/default_theme/test/format_markdown.js +++ b/default_theme/test/format_markdown.js @@ -2,85 +2,117 @@ var test = require('tap').test; var remark = require('remark'); var formatMarkdown = require('../lib/format_markdown'); -test('main', function (t) { - t.deepEqual(formatMarkdown(remark().parse('Converts from `Result` to `?Error`')), - '

Converts from Result<T> to ?Error

\n'); +test('main', function(t) { + t.deepEqual( + formatMarkdown(remark().parse('Converts from `Result` to `?Error`')), + '

Converts from Result<T> to ?Error

\n' + ); t.done(); }); -test('type', function (t) { +test('type', function(t) { var formatType = formatMarkdown.type; t.deepEqual(formatType(undefined), ''); - t.deepEqual(formatType({ - type: 'NameExpression', - name: 'Foo' - }), 'Foo'); - - t.deepEqual(formatType({ - type: 'NameExpression', - name: 'Foo' - }, ['Foo']), 'Foo'); + t.deepEqual( + formatType({ + type: 'NameExpression', + name: 'Foo' + }), + 'Foo' + ); - t.deepEqual(formatType({ - type: 'UnionType', - elements: [ + t.deepEqual( + formatType( { type: 'NameExpression', name: 'Foo' }, - { - type: 'NameExpression', - name: 'Bar' - } - ] - }), '(Foo | Bar)'); + ['Foo'] + ), + 'Foo' + ); - t.deepEqual(formatType({ - type: 'AllLiteral' - }), 'Any'); + t.deepEqual( + formatType({ + type: 'UnionType', + elements: [ + { + type: 'NameExpression', + name: 'Foo' + }, + { + type: 'NameExpression', + name: 'Bar' + } + ] + }), + '(Foo | Bar)' + ); - t.deepEqual(formatType({ - type: 'RestType' - }), '...'); + t.deepEqual( + formatType({ + type: 'AllLiteral' + }), + 'Any' + ); - t.deepEqual(formatType({ - type: 'OptionalType', - expression: { - type: 'NameExpression', - name: 'Foo' - } - }), '[Foo]'); + t.deepEqual( + formatType({ + type: 'RestType' + }), + '...' + ); - t.deepEqual(formatType({ - type: 'TypeApplication', - expression: { - type: 'NameExpression', - name: 'Foo' - }, - applications: [{ - type: 'NameExpression', - name: 'Bar' - }] - }), 'Foo<Bar>'); + t.deepEqual( + formatType({ + type: 'OptionalType', + expression: { + type: 'NameExpression', + name: 'Foo' + } + }), + '[Foo]' + ); + + t.deepEqual( + formatType({ + type: 'TypeApplication', + expression: { + type: 'NameExpression', + name: 'Foo' + }, + applications: [ + { + type: 'NameExpression', + name: 'Bar' + } + ] + }), + 'Foo<Bar>' + ); - t.deepEqual(formatType({ - type: 'UndefinedLiteral' - }), 'undefined'); + t.deepEqual( + formatType({ + type: 'UndefinedLiteral' + }), + 'undefined' + ); t.done(); }); -test('autolink', function (t) { +test('autolink', function(t) { var autolink = formatMarkdown.link; t.equal(autolink([], 'Foo'), 'Foo'); - t.equal(autolink(['Foo'], 'Foo'), - 'Foo'); - t.equal(autolink([], 'Array'), - 'Array'); + t.equal(autolink(['Foo'], 'Foo'), 'Foo'); + t.equal( + autolink([], 'Array'), + 'Array' + ); t.equal(autolink([], 'C&O'), 'C&O'); t.done(); diff --git a/default_theme/test/format_parameters.js b/default_theme/test/format_parameters.js index 2c2597532..e59ca5937 100644 --- a/default_theme/test/format_parameters.js +++ b/default_theme/test/format_parameters.js @@ -1,10 +1,15 @@ var test = require('tap').test; var formatParameters = require('../lib/format_parameters'); -test('main', function (t) { +test('main', function(t) { t.deepEqual(formatParameters({}), ''); t.deepEqual(formatParameters({ params: [] }), '()'); t.deepEqual(formatParameters({ params: [{ name: 'foo' }] }), '(foo: )'); - t.deepEqual(formatParameters({ params: [{ name: 'foo', type: { type: 'OptionalType' } }] }), '(foo: [])'); + t.deepEqual( + formatParameters({ + params: [{ name: 'foo', type: { type: 'OptionalType' } }] + }), + '(foo: [])' + ); t.done(); }); diff --git a/default_theme/test/index.js b/default_theme/test/index.js index fa10c2184..a613069b4 100644 --- a/default_theme/test/index.js +++ b/default_theme/test/index.js @@ -2,7 +2,7 @@ var test = require('tap').test; var remark = require('remark'); var theme = require('..'); -test('main', function (t) { +test('main', function(t) { var comments = [ { path: [], @@ -12,16 +12,18 @@ test('main', function (t) { static: [], instance: [] }, - returns: [{ - type: { - type: 'NameExpression', - name: 'Foo' + returns: [ + { + type: { + type: 'NameExpression', + name: 'Foo' + } } - }] + ] } ]; - theme(comments, {}, function (err) { + theme(comments, {}, function(err) { t.ifError(err); t.done(); }); diff --git a/package.json b/package.json index 043ed9112..bd847beaf 100644 --- a/package.json +++ b/package.json @@ -89,7 +89,7 @@ "scripts": { "release": "standard-version", "precommit": "lint-staged --verbose", - "format": "prettier --write '{lib,test}/**/*.js' --single-quote", + "format": "prettier --write '{lib,test,declarations,bin,default_theme}/**/*.js' --single-quote", "doc": "./bin/documentation.js build lib/index.js -f md --access=public > docs/NODE_API.md", "changelog": "standard-changelog -i CHANGELOG.md -w", "self-lint": "node ./bin/documentation.js lint",