This repository has been archived by the owner on Mar 27, 2024. It is now read-only.
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add codedocs and readme to component page (#111)
- Loading branch information
Showing
124 changed files
with
11,390 additions
and
3,648 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,7 +1,9 @@ | ||
.DS_Store | ||
.env | ||
.nyc_output | ||
coverage | ||
node_modules/ | ||
npm-debug.log | ||
public/ | ||
bower_components/ | ||
.vscode/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
# Snyk (https://snyk.io) policy file, patches or ignores known vulnerabilities. | ||
version: v1.12.0 | ||
# ignores vulnerabilities until expiry date; change duration by modifying expiry date | ||
ignore: | ||
'npm:mem:20180117': | ||
- showdown > yargs > os-locale > mem: | ||
reason: No patch avalible yet and DoS of registry README is not a high risk. | ||
expires: '2018-11-02T17:09:51.357Z' | ||
patch: {} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
'use strict'; | ||
|
||
class Example { | ||
constructor(code, type = '', caption = '') { | ||
this.caption = caption ? `${caption}\n` : ''; // newline to render as <p> with markdown | ||
this.type = type || ''; | ||
this.code = code; | ||
} | ||
} | ||
|
||
module.exports = Example; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,116 @@ | ||
'use strict'; | ||
|
||
const ClassNode = require('./nodes/class'); | ||
const EventNode = require('./nodes/event'); | ||
const FunctionNode = require('./nodes/function'); | ||
const MixinNode = require('./nodes/mixin'); | ||
const NamespaceNode = require('./nodes/namespace'); | ||
const PropertyNode = require('./nodes/property'); | ||
const ModuleNode = require('./nodes/module'); | ||
|
||
/** | ||
* Methods to prepare JsDoc json doclets for display within the registry. | ||
*/ | ||
class JsDoc { | ||
/** | ||
* @param {Object[]} doclets - Raw json doclets generated by JSDoc. | ||
*/ | ||
constructor(doclets) { | ||
this.doclets = doclets; | ||
} | ||
|
||
/** | ||
* @returns {string[]} Kinds of JSDoc doclets which are supported. | ||
*/ | ||
static supportedDoclets() { | ||
return ['class', 'function', 'constant', 'member', 'event', 'namespace', 'mixin', 'module']; | ||
} | ||
|
||
/** | ||
* Format a doclet by removing superfluous properties and adding any custom properties. | ||
* @param {Object} doclet - A raw json doclet generated by JSDoc. | ||
* @returns {Object} Formatted node. | ||
*/ | ||
static formatDoclet(doclet) { | ||
switch (doclet.kind) { | ||
case 'class': | ||
return new ClassNode(doclet); | ||
break; | ||
case 'function': | ||
return new FunctionNode(doclet); | ||
break; | ||
case 'constant': | ||
case 'member': | ||
return new PropertyNode(doclet); | ||
break; | ||
case 'event': | ||
return new EventNode(doclet); | ||
break; | ||
case 'namespace': | ||
return new NamespaceNode(doclet); | ||
break; | ||
case 'mixin': | ||
return new MixinNode(doclet); | ||
break; | ||
case 'module': | ||
return new ModuleNode(doclet); | ||
break; | ||
default: | ||
throw new Error(`JsDoc doclet kind "${doclet.kind}" is not supported by the registry.`); | ||
break; | ||
}; | ||
} | ||
|
||
/** | ||
* @returns {Object[]} Formatted nodes. | ||
*/ | ||
getNodes() { | ||
if (!this._formattedDoclets) { | ||
const supportedDoclets = this.doclets.filter((doclet) => { | ||
const isNotIndicatedPrivate = doclet.name && doclet.name.indexOf('_') !== 0; | ||
const isSupported = doclet.kind && JsDoc.supportedDoclets().includes(doclet.kind); | ||
const isPublic = doclet.access !== 'private'; | ||
const isDocumented = doclet.undocumented !== true; | ||
return isSupported && isPublic && isNotIndicatedPrivate && isDocumented; | ||
}); | ||
|
||
this._formattedDoclets = supportedDoclets.map((doclet) => { | ||
return JsDoc.formatDoclet(doclet); | ||
}); | ||
} | ||
return this._formattedDoclets; | ||
} | ||
|
||
/** | ||
* @returns {Object[]} Formatted nodes. | ||
*/ | ||
getNodesByTypeWithMembers() { | ||
if (!this._formattedDocletsWithMembers) { | ||
this._formattedDocletsWithMembers = JsDoc._addChildNodes(this.getNodes(), {}); | ||
} | ||
return this._formattedDocletsWithMembers; | ||
} | ||
|
||
/** | ||
* Add member nodes to parent nodes. E.g. add function nodes to their corresponding class node. | ||
* @param {Object[]} nodes [{}] - Formatted JSDoc doclets. | ||
* @param {Object|Object[]} parentNodes - Root nodes to add member nodes to (optional). | ||
* @returns {Object[]} Nodes with member nodes grouped by kind e.g. {name: 'Example', type: class, examples: [{}], functions: [{}], properties: [{}]} | ||
* @access private | ||
*/ | ||
static _addChildNodes(nodes, parentNodes = {}) { | ||
parentNodes = Array.isArray(parentNodes) ? parentNodes : [parentNodes]; | ||
const nodesWithMembers = parentNodes.map((parentNode) => { | ||
const memberNodes = nodes.filter((node) => node.memberof === parentNode.longname); | ||
return memberNodes.reduce((parentNode, node) => { | ||
JsDoc._addChildNodes(nodes, node); | ||
parentNode[node.group] = parentNode[node.group] || []; | ||
parentNode[node.group].push(node); | ||
return parentNode; | ||
}, parentNode); | ||
}); | ||
return (nodesWithMembers.length === 1 ? nodesWithMembers[0] : nodesWithMembers); | ||
} | ||
} | ||
|
||
module.exports = JsDoc; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,69 @@ | ||
'use strict'; | ||
|
||
const NavNode = require('../nav-node'); | ||
|
||
/** | ||
* Methods to build a navigation for JSDoc. | ||
*/ | ||
class JsDocNav { | ||
|
||
/** | ||
* @param {JsDoc} JsDoc - Raw json doclets generated by JSDoc. | ||
* @returns {NavNode[]} A navigation composing an array of sub-navigations e.g. [{title, items: [{title, link}]}] | ||
*/ | ||
static createNavigation(JsDoc) { | ||
const nav = []; | ||
const nodes = JsDoc.getNodes(); | ||
// Add important doclets to the root of the nav with subnavs. | ||
// E.g. add classes with funciton and proeprties as a subnav. | ||
const jsDocByTypeWithMembers = JsDoc.getNodesByTypeWithMembers(); | ||
const docletGroups = [ | ||
{ 'name': 'classes', 'subGroups': ['functions', 'properties'] }, | ||
{ 'name': 'modules', 'subGroups': ['classes', 'functions', 'properties'] }]; | ||
docletGroups.forEach(docletGroup => { | ||
if (jsDocByTypeWithMembers[docletGroup.name]) { | ||
jsDocByTypeWithMembers[docletGroup.name].forEach((node) => { | ||
nav.push(createSubNav( | ||
`${node.name}`, | ||
[].concat([node], ...docletGroup.subGroups.map(name => node[name])) | ||
)); | ||
}); | ||
} | ||
}); | ||
// Add events to nav, ignoring their hierarchy. | ||
// I.e. Surface events which are not in the global scope. | ||
const eventNodes = nodes.filter(node => node.kind === 'event'); | ||
if (eventNodes.length > 0) { | ||
nav.push(createSubNav('Events', eventNodes)); | ||
} | ||
// Add global nodes which are not already added to the nav. | ||
const globalNodes = nodes.filter(node => node.memberof === undefined && ['class', 'module', 'events'].includes(node.kind) === false); | ||
if (globalNodes.length > 0) { | ||
nav.push(createSubNav('Global', globalNodes)); | ||
} | ||
return nav; | ||
} | ||
} | ||
|
||
/** | ||
* @param {string} title - The title of the subnav. | ||
* @param {Object[]} nodes - Formatted JS doclets to link to from the sub-navigation. | ||
* @returns {NavNode} A sub-navigation e.g. {title, items: [{title, link}]} | ||
* @access private | ||
*/ | ||
function createSubNav(title, nodes) { | ||
nodes = nodes || []; | ||
const items = nodes.filter(node => node).map((node) => { | ||
let title = `${node.label}: ${node.name}`; | ||
if (node.kind === 'class' && node.memberof === undefined) { | ||
title = 'Constructor & Overview'; | ||
} | ||
if (node.kind === 'module' && node.memberof === undefined) { | ||
title = 'Overview'; | ||
} | ||
return new NavNode(title, `#${node.longname}`); | ||
}); | ||
return new NavNode(title, items); | ||
} | ||
|
||
module.exports = JsDocNav; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,100 @@ | ||
'use strict'; | ||
|
||
const Example = require('../../example'); | ||
const { URL } = require('url'); | ||
|
||
class BaseNode { | ||
constructor(doclet) { | ||
this.name = doclet.name; | ||
this.longname = doclet.longname; | ||
this.kind = doclet.kind; | ||
this.memberof = doclet.memberof; | ||
this.description = this.replaceLinks(doclet.description) || ''; | ||
this.access = doclet.access || ''; | ||
this.virtual = Boolean(doclet.virtual); | ||
this.file = { | ||
path: doclet.meta && doclet.meta.path ? doclet.meta.path : '', | ||
name: doclet.meta && doclet.meta.filename ? doclet.meta.filename : '' | ||
}; | ||
|
||
if (doclet.meta && isNaN(doclet.meta.lineno) === false) { | ||
this.file.lineno = doclet.meta.lineno; | ||
} | ||
if (doclet.meta && isNaN(doclet.meta.columnno) === false) { | ||
this.file.columnno = doclet.meta.columnno; | ||
} | ||
if (doclet.deprecated) { | ||
this.deprecated = this.replaceLinks(doclet.deprecated); | ||
} | ||
} | ||
|
||
replaceLinks(jsDocComment) { | ||
if (typeof jsDocComment !== 'string') { | ||
return jsDocComment; | ||
} | ||
return jsDocComment.replace(/(?:\[(.*)\])?{@link ([^\s|}]*)\s?(?:[|])?([^}]*)}/g, (match, p1, p2, p3) => { | ||
//{@link namepathOrURL} | ||
let href = p2; | ||
let text = null; | ||
//[link text]{@link namepathOrURL} | ||
text = text || p1; | ||
//{@link namepathOrURL|text} | ||
//{@link namepathOrURL text (after the first space)} | ||
text = text || p3; | ||
// If no text show url/namepath. | ||
text = text || href; | ||
// If unable to construct url assume a JSDoc namepath and turn into a hash. | ||
try { | ||
new URL(href); | ||
} catch (error) { | ||
href = `#${href}`; | ||
} | ||
return `[${text}](${href})`; | ||
}); | ||
} | ||
|
||
addExamples(doclet, target = this) { | ||
target.examples = target.examples || []; | ||
if (Array.isArray(doclet.examples)) { | ||
doclet.examples.forEach((example) => { | ||
let code = example; | ||
let caption; | ||
|
||
/** @see https://github.com/jsdoc3/jsdoc/blob/832dfd704a01fc931ef54ef0a02896d89a5ee9ad/templates/default/publish.js#L470 */ | ||
if (example.match(/^\s*<caption>([\s\S]+?)<\/caption>(\s*[\n\r])([\s\S]+)$/i)) { | ||
caption = RegExp.$1; | ||
code = RegExp.$3; | ||
} | ||
|
||
if (typeof code === 'string' && code.length > 1) { | ||
target.examples.push(new Example(code, 'js', caption)); | ||
} | ||
}); | ||
} | ||
} | ||
|
||
addParameters(doclet, target = this) { | ||
target.parameters = target.parameters || []; | ||
if (Array.isArray(doclet.params)) { | ||
doclet.params.forEach((param) => target.parameters.push({ | ||
'name': param.name, | ||
'type': param.type && param.type.names ? param.type.names : [], // param can accept multiple types | ||
'description': param.description || '', | ||
'default': param.hasOwnProperty('defaultvalue') ? param.defaultvalue : '', | ||
'optional': typeof param.optional === 'boolean' ? param.optional : '', | ||
'nullable': typeof param.nullable === 'boolean' ? param.nullable : '' | ||
})); | ||
} | ||
} | ||
|
||
addReturns(doclet, target = this) { | ||
if (doclet.returns) { | ||
target.returns = { | ||
'type': doclet.returns[0] && doclet.returns[0].type && doclet.returns[0].type.names ? doclet.returns[0].type.names : [], // return can be of multiple types | ||
'description': doclet.returns[0] && doclet.returns[0].description || '' | ||
}; | ||
} | ||
} | ||
} | ||
|
||
module.exports = BaseNode; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
'use strict'; | ||
|
||
const BaseNode = require('./base'); | ||
|
||
class ClassNode extends BaseNode { | ||
constructor(doclet) { | ||
super(doclet); | ||
this.group = 'classes'; | ||
this.label = doclet.meta && doclet.meta.code && doclet.meta.code.type === 'ClassDeclaration' ? 'Class' : 'Constructor Function'; | ||
this.description = this.replaceLinks(doclet.classdesc) || ''; | ||
this.extends = doclet.augments || []; | ||
this.fires = doclet.fires || []; | ||
this.constructor = { | ||
'name': doclet.name, | ||
'description': this.replaceLinks(doclet.description) || '', | ||
'parameters': [ | ||
], | ||
'examples': [] | ||
}; | ||
this.addExamples(doclet, this.constructor); | ||
this.addParameters(doclet, this.constructor); | ||
} | ||
}; | ||
|
||
module.exports = ClassNode; |
Oops, something went wrong.