 + ')
');
}
// title
if (this._title) {
const $title = $('title');
const original = $title.text();
$title.text(`${original} | ${this._title}`);
}
// repository
if (this._repository) {
if (this._repository.indexOf('https://github.com/') === 0) {
const style = 'style="position:relative; top:3px;"';
$('header').append(``);
} else {
$('header').append(`Repository`);
}
}
// meta tag
this._addMetaTag($);
ev.data.content = $.html();
}
_getRepositoryURL(packageObj) {
if (!packageObj.repository) return null;
let url = packageObj.repository.url || packageObj.repository;
if (typeof url !== 'string') return null;
if (url.indexOf('git@github.com:') === 0) { // url: git@github.com:foo/bar.git
const matched = url.match(/^git@github\.com:(.*)\.git$/);
return `https://github.com/${matched[1]}`;
} else if (url.match(/^[\w\d\-_]+\/[\w\d\-_]+$/)) { // url: foo/bar
return `https://github.com/${url}`;
} else if (url.match(/^git\+https:\/\/github.com\/.*\.git$/)) { // git+https://github.com/foo/bar.git
const matched = url.match(/^git\+(https:\/\/github.com\/.*)\.git$/);
return matched[1];
} else if (url.match(/(https?:\/\/.*$)/)) { // other url
const matched = url.match(/(https?:\/\/.*$)/);
return matched[1];
}
return null;
}
_getAuthor(packageObj) {
if (!packageObj.author) return null;
if (typeof packageObj.author === 'string') {
return packageObj.author;
} else {
return packageObj.author.url || packageObj.author.name;
}
}
_addMetaTag($) {
const metaProps = [];
// normal
if (this._description){
metaProps.push({name: 'description', content: this._description});
}
// og tag http://ogp.me/#metadata
if (this._title && this._image && this._site){
metaProps.push({property: 'og:type', content: 'website'});
metaProps.push({property: 'og:url', content: this._site});
metaProps.push({property: 'og:site_name', content: this._title});
metaProps.push({property: 'og:title', content: this._title});
metaProps.push({property: 'og:image', content: this._image});
if (this._description) metaProps.push({property: 'og:description', content: this._description});
if (this._author) metaProps.push({property: 'og:author', content: this._author});
}
// twitter card https://dev.twitter.com/cards/types/summary
if (this._title && this._description){
metaProps.push({property: 'twitter:card', content: 'summary'});
metaProps.push({property: 'twitter:title', content: this._title});
metaProps.push({property: 'twitter:description', content: this._description});
if (this._image) metaProps.push({property: 'twitter:image', content: this._image});
if (this._site && this._site.indexOf('https://twitter.com/') === 0) {
const twitterName = this._site.replace('https://twitter.com/', '@');
metaProps.push({property: 'twitter:site', content: twitterName});
metaProps.push({property: 'twitter:creator', content: twitterName});
}
}
const $head = $('head');
for (const metaProp of metaProps) {
const prop = Object.keys(metaProp).map((key) => `${key}="${metaProp[key]}"`).join(' ');
const metaTag = ``;
$head.append(metaTag);
}
}
}
module.exports = new Plugin();
================================================
FILE: esdoc-brand-plugin/test/esdoc.json
================================================
{
"source": "./test/src",
"destination": "./test/out",
"excludes": ["\\.test\\.js$"],
"package": "./test/package.json",
"plugins": [
{"name": "./test/misc/publish-html-mock-plugin.js"},
{"name": "./src/Plugin.js", "option": {"logo": "./test/misc/logo.png", "image": "https://esdoc.org/manual/asset/image/logo.png"}}
]
}
================================================
FILE: esdoc-brand-plugin/test/init.js
================================================
const path = require('path');
const fs = require('fs');
const ESDocCLI = require('esdoc/out/src/ESDocCLI.js').default;
function cli() {
const cliPath = path.resolve('./node_modules/esdoc/out/ESDocCLI.js');
const argv = ['node', cliPath, '-c', './test/esdoc.json'];
const cli = new ESDocCLI(argv);
cli.exec();
global.docs = JSON.parse(fs.readFileSync('./test/out/index.json').toString());
}
cli();
================================================
FILE: esdoc-brand-plugin/test/misc/publish-html-mock-plugin.js
================================================
exports.onPublish = function(ev) {
const html = `
## Feature
- Generates detailed document.
- Measures document coverage.
- Integrate test codes into documentation.
- [ESDoc Hosting Service](https://doc.esdoc.org)
## Demo
- [ESDoc](https://esdoc.org/esdoc) is self-hosting 😄
## License
MIT
## Author
[Ryo Maruyama@h13i32maru](https://twitter.com/h13i32maru)
================================================
FILE: esdoc-integrate-manual-plugin/test/manual/tutorial.md
================================================
# Tutorial
this is tutorial.
================================================
FILE: esdoc-integrate-manual-plugin/test/manual/usage1.md
================================================
# Usage
```sh
esdoc -c esdoc.json
```
``esdoc.json``
```json
{
"source": "./src",
"destination": "./doc"
}
```
================================================
FILE: esdoc-integrate-manual-plugin/test/manual/usage2.md
================================================
# Usage2
this is usage2
## h2 in usage2
this is h2 in usage2
### h3 in usage2
this is h2 in usage3
================================================
FILE: esdoc-integrate-manual-plugin/test/src/Dummy.js
================================================
export default class TestDummy {}
================================================
FILE: esdoc-integrate-manual-plugin/test/util.js
================================================
const fs = require('fs');
exports.find = function(key, ...values) {
if (values.length === 1) {
return global.docs.find((doc) => {
if (typeof values[0] === 'string') return doc[key] === values[0];
if (values[0] instanceof RegExp) return doc[key].match(values[0]);
});
}
const results = [];
for (const value of values) {
const result = global.docs.find(doc => {
if (typeof value === 'string') return doc[key] === value;
if (value instanceof RegExp) return doc[key].match(value);
});
results.push(result);
}
return results;
};
exports.file = function (filePath) {
return fs.readFileSync(filePath).toString();
};
================================================
FILE: esdoc-integrate-test-plugin/CHANGELOG.md
================================================
# Changelog
## 1.0.0 (2017-07-30)
- Release
================================================
FILE: esdoc-integrate-test-plugin/LICENSE
================================================
The MIT License (MIT)
Copyright (c) 2015 Ryo Maruyama
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
================================================
FILE: esdoc-integrate-test-plugin/README.md
================================================
# ESDoc Integrate Test Plugin
## Install
```bash
npm install esdoc-integrate-test-plugin
```
## Config
```json
{
"source": "./src",
"destination": "./docs",
"plugins": [
{
"name": "esdoc-integrate-test-plugin",
"option": {
"source": "./test/",
"interfaces": ["describe", "it", "context", "suite", "test"],
"includes": ["(spec|Spec|test|Test)\\.js$"],
"excludes": ["\\.config\\.js$"]
}
}
]
}
```
- `source` is required
- `interfaces` default is `["describe", "it", "context", "suite", "test"]`
- `includes` default is `["(spec|Spec|test|Test)\\.js$"]`
- `excludes` default is `["\\.config\\.js$"]`
## LICENSE
MIT
## Author
[Ryo Maruyama@h13i32maru](https://github.com/h13i32maru)
================================================
FILE: esdoc-integrate-test-plugin/package.json
================================================
{
"name": "esdoc-integrate-test-plugin",
"version": "1.0.0",
"description": "A integrate test plugin for ESDoc",
"author": "h13i32maru",
"homepage": "https://github.com/esdoc/esdoc-plugins",
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/esdoc/esdoc-plugins"
},
"devDependencies": {
"esdoc": "latest",
"mocha": "2.5.3"
},
"engines": {
"node": ">= 6.0.0"
},
"scripts": {
"test": "rm -rf ./test/out && mocha --require ./test/init.js $(find test/ -regex '.*.test.js$') -R spec"
},
"keywords": [
"esdoc",
"test",
"plugin"
],
"files": [
"src",
"README.md"
],
"main": "src/Plugin.js"
}
================================================
FILE: esdoc-integrate-test-plugin/src/Plugin.js
================================================
const assert = require('assert');
const path = require('path');
const fs = require('fs');
const TestDocFactory = require('./TestDocFactory');
// hack
const ESParser = require('esdoc/out/src/Parser/ESParser').default;
const InvalidCodeLogger = require('esdoc/out/src/Util/InvalidCodeLogger').default;
const PathResolver = require('esdoc/out/src/Util/PathResolver').default;
const ASTUtil = require('esdoc/out/src/Util/ASTUtil').default;
class Plugin {
onHandleDocs(ev) {
this._docs = ev.data.docs;
this._option = ev.data.option;
this._exec();
}
_exec() {
this._setDefault();
const docs = this._generateDocs();
this._docs.push(...docs);
}
_setDefault() {
if (!this._option) return;
const option = this._option;
assert(option.source);
if (!option.interfaces) option.interfaces = ['describe', 'it', 'context', 'suite', 'test'];
if (!option.includes) option.includes = ['(spec|Spec|test|Test)\\.js$'];
if (!option.excludes) option.excludes = ['\\.config\\.js$'];
}
/**
* Generate document from test code.
*/
_generateDocs() {
const option = this._option;
const results = [];
if (!option) return results;
const includes = option.includes.map((v) => new RegExp(v));
const excludes = option.excludes.map((v) => new RegExp(v));
const sourceDirPath = path.resolve(option.source);
this._walk(option.source, (filePath)=>{
const relativeFilePath = path.relative(sourceDirPath, filePath);
let match = false;
for (const reg of includes) {
if (relativeFilePath.match(reg)) {
match = true;
break;
}
}
if (!match) return;
for (const reg of excludes) {
if (relativeFilePath.match(reg)) return;
}
console.log(`parse: ${filePath}`);
const temp = this._traverse(option.interfaces, option.source, filePath);
if (!temp) return;
results.push(...temp.results);
// todo: enable work
// asts.push({filePath: `test${path.sep}${relativeFilePath}`, ast: temp.ast});
});
return results;
}
/**
* walk recursive in directory.
* @param {string} dirPath - target directory path.
* @param {function(entryPath: string)} callback - callback for find file.
* @private
*/
_walk(dirPath, callback) {
const entries = fs.readdirSync(dirPath);
for (const entry of entries) {
const entryPath = path.resolve(dirPath, entry);
const stat = fs.statSync(entryPath);
if (stat.isFile()) {
callback(entryPath);
} else if (stat.isDirectory()) {
this._walk(entryPath, callback);
}
}
}
/**
* traverse doc comment in test code file.
* @param {string[]} interfaces - test interface names.
* @param {string} inDirPath - root directory path.
* @param {string} filePath - target test code file path.
* @returns {Object} return document info that is traversed.
* @property {DocObject[]} results - this is contained test code.
* @property {AST} ast - this is AST of test code.
* @private
*/
_traverse(interfaces, inDirPath, filePath) {
let ast;
try {
ast = ESParser.parse(filePath);
} catch (e) {
InvalidCodeLogger.showFile(filePath, e);
return null;
}
const pathResolver = new PathResolver(inDirPath, filePath);
const factory = new TestDocFactory(interfaces, ast, pathResolver);
ASTUtil.traverse(ast, (node, parent)=>{
try {
factory.push(node, parent);
} catch (e) {
InvalidCodeLogger.show(filePath, node);
throw e;
}
});
return {results: factory.results, ast: ast};
}
}
module.exports = new Plugin();
================================================
FILE: esdoc-integrate-test-plugin/src/TestDoc.js
================================================
// hack: depends on esdoc internal class
const AbstractDoc = require('esdoc/out/src/Doc/AbstractDoc').default;
const ParamParser = require('esdoc/out/src/Parser/ParamParser').default;
/**
* Doc Class from test code file.
*/
class TestDoc extends AbstractDoc {
/**
* apply own tag.
* @private
*/
_apply() {
super._apply();
this._$testTarget();
Reflect.deleteProperty(this._value, 'export');
Reflect.deleteProperty(this._value, 'importPath');
Reflect.deleteProperty(this._value, 'importStyle');
}
/** use name property of self node. */
_$kind() {
super._$kind();
this._value.kind = 'test';
}
/** set name and testId from special esdoc property. */
_$name() {
super._$name();
this._value.name = this._node._esdocTestName;
this._value.testId = this._node._esdocTestId;
}
/** set memberof to use parent test nod and file path. */
_$memberof() {
super._$memberof();
const chain = [];
let parent = this._node.parent;
while (parent) {
if (parent._esdocTestName) chain.push(parent._esdocTestName);
parent = parent.parent;
}
const filePath = this._pathResolver.filePath;
if (chain.length) {
this._value.memberof = `${filePath}~${chain.reverse().join('.')}`;
this._value.testDepth = chain.length;
} else {
this._value.memberof = filePath;
this._value.testDepth = 0;
}
}
/** set describe by using test node arguments. */
_$desc() {
super._$desc();
if (this._value.description) return;
this._value.description = this._node.arguments[0].value;
}
/** for @testTarget. */
_$testTarget() {
const values = this._findAllTagValues(['@test', '@testTarget']);
if (!values) return;
this._value.testTargets = [];
for (const value of values) {
const {typeText} = ParamParser.parseParamValue(value, true, false, false);
this._value.testTargets.push(typeText);
}
}
_$test() {
// alias of testTarget
}
}
module.exports = TestDoc;
================================================
FILE: esdoc-integrate-test-plugin/src/TestDocFactory.js
================================================
const assert = require('assert');
const TestDoc = require('./TestDoc');
const TestFileDoc = require('./TestFileDoc');
// hack: depends on ESDoc internal class
const CommentParser = require('esdoc/out/src/Parser/CommentParser').default;
const already = Symbol('already');
/**
* Test doc factory class.
* @example
* let factory = new TestDocFactory('mocha', ast, pathResolver);
* factory.push(node, parentNode);
* let results = factory.results;
*/
class TestDocFactory {
/**
* get unique id.
* @returns {number} unique id.
* @private
*/
static _getUniqueId() {
if (!this._sequence) /** @type {number} */ this._sequence = 0;
return this._sequence++;
}
/**
* @type {DocObject[]}
*/
get results() {
return [...this._results];
}
/**
* create instance.
* @param {string[]} interfaces - test interface names.
* @param {AST} ast - AST of test code.
* @param {PathResolver} pathResolver - path resolver of test code.
*/
constructor(interfaces, ast, pathResolver) {
/** @type {string} */
this._interfaces = interfaces;
/** @type {AST} */
this._ast = ast;
/** @type {PathResolver} */
this._pathResolver = pathResolver;
/** @type {DocObject[]} */
this._results = [];
// file doc
const doc = new TestFileDoc(ast, ast, pathResolver, []);
this._results.push(doc.value);
}
/**
* push node, and factory process the node.
* @param {ASTNode} node - target node.
* @param {ASTNode} parentNode - parent node of target node.
*/
push(node, parentNode) {
if (node[already]) return;
node[already] = true;
Reflect.defineProperty(node, 'parent', {value: parentNode});
this._push(node);
}
/**
* push node as mocha test code.
* @param {ASTNode} node - target node.
* @private
*/
_push(node) {
if (node.type !== 'ExpressionStatement') return;
const expression = node.expression;
if (expression.type !== 'CallExpression') return;
if (!this._interfaces.includes(expression.callee.name)) return;
expression[already] = true;
Reflect.defineProperty(expression, 'parent', {value: node});
let tags = [];
if (node.leadingComments && node.leadingComments.length) {
const comment = node.leadingComments[node.leadingComments.length - 1];
tags = CommentParser.parse(comment);
}
const uniqueId = this.constructor._getUniqueId();
expression._esdocTestId = uniqueId;
expression._esdocTestName = expression.callee.name + uniqueId;
const testDoc = new TestDoc(this._ast, expression, this._pathResolver, tags);
this._results.push(testDoc.value);
}
}
module.exports = TestDocFactory;
================================================
FILE: esdoc-integrate-test-plugin/src/TestFileDoc.js
================================================
// hack: depends on esdoc internal class
const FileDoc = require('esdoc/out/src/Doc/FileDoc').default;
/**
* Doc class for test code file.
*/
class TestFileDoc extends FileDoc {
/** set ``testFile`` to kind. */
_$kind() {
this._value.kind = 'testFile';
}
}
module.exports = TestFileDoc;
================================================
FILE: esdoc-integrate-test-plugin/test/esdoc.json
================================================
{
"source": "./test/src",
"destination": "./test/out",
"excludes": ["\\.test\\.js$"],
"plugins": [
{
"name": "./src/Plugin.js",
"option": {
"source": "./test/test",
"excludes": ["\\.test\\.js$"]
}
}
]
}
================================================
FILE: esdoc-integrate-test-plugin/test/init.js
================================================
const path = require('path');
const fs = require('fs');
const ESDocCLI = require('esdoc/out/src/ESDocCLI.js').default;
function cli() {
const cliPath = path.resolve('./node_modules/esdoc/out/ESDocCLI.js');
const argv = ['node', cliPath, '-c', './test/esdoc.json'];
const cli = new ESDocCLI(argv);
cli.exec();
global.docs = JSON.parse(fs.readFileSync('./test/out/index.json').toString());
}
cli();
================================================
FILE: esdoc-integrate-test-plugin/test/src/Dummy.js
================================================
export default class Dummy {
}
================================================
FILE: esdoc-integrate-test-plugin/test/test/Test.js
================================================
/**
* @test {TestTarget1}
*/
describe('describe/', ()=>{
/**
* @test {TestTarget2}
*/
it('describe/it', ()=>{});
/**
* @test {TestTarget3}
*/
describe('describe/describe/', ()=>{
/**
* @test {TestTarget4}
*/
it('describe/describe/it', ()=>{});
});
/**
* @test {TestTarget5}
*/
context('describe/context/', ()=>{
/**
* @test {TestTarget6}
*/
it('describe/context/it', ()=>{});
});
});
/**
* @test {TestTarget7}
*/
suite('suite/', ()=>{
/**
* @test {TestTarget8}
*/
test('suite/test', ()=>{});
/**
* @test {TestTarget9}
*/
suite('suite/suite/', ()=>{
/**
* @test {TestTarget10}
*/
test('suite/suite/test', ()=>{});
})
});
================================================
FILE: esdoc-integrate-test-plugin/test/test/Test.test.js
================================================
const assert = require('assert');
const {find} = require('../util');
describe('test/Test.js:', ()=>{
it('has describe/', ()=>{
const doc = find('longname', 'test/Test.js~describe0');
assert.equal(doc.testId, 0);
assert.equal(doc.testDepth, 0);
assert.equal(doc.description, 'describe/');
assert.deepEqual(doc.testTargets, ['TestTarget1']);
});
it('has describe/it', ()=>{
const doc = find('longname', 'test/Test.js~describe0.it1');
assert.equal(doc.testId, 1);
assert.equal(doc.testDepth, 1);
assert.equal(doc.description, 'describe/it');
assert.deepEqual(doc.testTargets, ['TestTarget2']);
});
it('has describe/describe', ()=>{
const doc = find('longname', 'test/Test.js~describe0.describe2');
assert.equal(doc.testId, 2);
assert.equal(doc.testDepth, 1);
assert.equal(doc.description, 'describe/describe/');
assert.deepEqual(doc.testTargets, ['TestTarget3']);
});
it('has describe/describe/it', ()=>{
const doc = find('longname', 'test/Test.js~describe0.describe2.it3');
assert.equal(doc.testId, 3);
assert.equal(doc.testDepth, 2);
assert.equal(doc.description, 'describe/describe/it');
assert.deepEqual(doc.testTargets, ['TestTarget4']);
});
it('has describe/context/it', ()=>{
const doc = find('longname', 'test/Test.js~describe0.context4.it5');
assert.equal(doc.testId, 5);
assert.equal(doc.testDepth, 2);
assert.equal(doc.description, 'describe/context/it');
assert.deepEqual(doc.testTargets, ['TestTarget6']);
});
it('has suite/', ()=>{
const doc = find('longname', 'test/Test.js~suite6');
assert.equal(doc.testId, 6);
assert.equal(doc.testDepth, 0);
assert.equal(doc.description, 'suite/');
assert.deepEqual(doc.testTargets, ['TestTarget7']);
});
it('has suite/test', ()=>{
const doc = find('longname', 'test/Test.js~suite6.test7');
assert.equal(doc.testId, 7);
assert.equal(doc.testDepth, 1);
assert.equal(doc.description, 'suite/test');
assert.deepEqual(doc.testTargets, ['TestTarget8']);
});
it('has suite/suite/', ()=>{
const doc = find('longname', 'test/Test.js~suite6.suite8');
assert.equal(doc.testId, 8);
assert.equal(doc.testDepth, 1);
assert.equal(doc.description, 'suite/suite/');
assert.deepEqual(doc.testTargets, ['TestTarget9']);
});
it('has suite/suite/test', ()=>{
const doc = find('longname', 'test/Test.js~suite6.suite8.test9');
assert.equal(doc.testId, 9);
assert.equal(doc.testDepth, 2);
assert.equal(doc.description, 'suite/suite/test');
assert.deepEqual(doc.testTargets, ['TestTarget10']);
});
});
================================================
FILE: esdoc-integrate-test-plugin/test/util.js
================================================
const fs = require('fs');
exports.find = function(key, ...values) {
if (values.length === 1) {
return global.docs.find((doc) => {
if (typeof values[0] === 'string') return doc[key] === values[0];
if (values[0] instanceof RegExp) return doc[key].match(values[0]);
});
}
const results = [];
for (const value of values) {
const result = global.docs.find(doc => {
if (typeof value === 'string') return doc[key] === value;
if (value instanceof RegExp) return doc[key].match(value);
});
results.push(result);
}
return results;
};
exports.file = function (filePath) {
return fs.readFileSync(filePath).toString();
};
================================================
FILE: esdoc-jsx-plugin/CHANGELOG.md
================================================
# Changelog
## 1.0.0 (2017-07-30)
- Release
================================================
FILE: esdoc-jsx-plugin/LICENSE
================================================
The MIT License (MIT)
Copyright (c) 2015 Ryo Maruyama
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
================================================
FILE: esdoc-jsx-plugin/README.md
================================================
# ESDoc JSX Plugin
## Install
```bash
npm install esdoc-jsx-plugin
```
## Config
```json
{
"source": "./src",
"destination": "./doc",
"plugins": [
{"name": "esdoc-jsx-plugin", "option": {"enable": true}}
]
}
```
- `enable` is default `true`
## LICENSE
MIT
## Author
[Ryo Maruyama@h13i32maru](https://github.com/h13i32maru)
================================================
FILE: esdoc-jsx-plugin/package.json
================================================
{
"name": "esdoc-jsx-plugin",
"version": "1.0.0",
"description": "A JSX plugin for ESDoc",
"author": "h13i32maru",
"homepage": "https://github.com/esdoc/esdoc-plugins",
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/esdoc/esdoc-plugins"
},
"devDependencies": {
"esdoc": "latest",
"mocha": "2.5.3"
},
"engines": {
"node": ">= 6.0.0"
},
"scripts": {
"test": "rm -rf ./test/out && mocha --require ./test/init.js $(find test/ -regex '.*.test.js$') -R spec"
},
"keywords": [
"esdoc",
"jsx",
"plugin"
],
"files": [
"src",
"README.md"
],
"main": "src/Plugin.js"
}
================================================
FILE: esdoc-jsx-plugin/src/Plugin.js
================================================
class Plugin {
onHandleCodeParser(ev) {
const option = ev.data.option || {};
const plugins = ev.data.parserOption.plugins;
if (!('enable' in option)) option.enable = true;
if (option.enable) plugins.push('jsx');
}
}
module.exports = new Plugin();
================================================
FILE: esdoc-jsx-plugin/test/esdoc.json
================================================
{
"source": "./test/src",
"destination": "./test/out",
"excludes": ["\\.test\\.js$"],
"plugins": [
{"name": "./src/Plugin.js"}
]
}
================================================
FILE: esdoc-jsx-plugin/test/init.js
================================================
const path = require('path');
const fs = require('fs');
const ESDocCLI = require('esdoc/out/src/ESDocCLI.js').default;
function cli() {
const cliPath = path.resolve('./node_modules/esdoc/out/ESDocCLI.js');
const argv = ['node', cliPath, '-c', './test/esdoc.json'];
const cli = new ESDocCLI(argv);
cli.exec();
global.docs = JSON.parse(fs.readFileSync('./test/out/index.json').toString());
}
cli();
================================================
FILE: esdoc-jsx-plugin/test/src/MyClass.js
================================================
export default class MyClass {
method(){
return Sorry, this documentation does not provide source code.
================================================ FILE: esdoc-publish-html-plugin/src/Builder/template/identifiers.html ================================================
| Name | Type | Attribute | Description |
"+a+""; b=b.firstChild;f&&L(b,f,!0);M({j:d,m:f,h:b,l:1,a:null,i:null,c:null,g:null});return b.innerHTML},prettyPrint:E.prettyPrint=function(a,d){function f(){for(var b=E.PR_SHOULD_USE_CONTINUATION?c.now()+250:Infinity;p
| File | Identifier | Document |
|
|
version since | |
| Description | Identifier |
') inCode = true;
else if (char5 === '') inCode = false;
if (inSQuote || inCode || inWQuote) continue;
if (char1 === '.') {
if (char2 === ' ' || char2 === '\n' || char2 === '<') {
len = i + 1;
break;
}
} else if (char1 === '\n' && char2 === '\n') {
len = i + 1;
break;
}
}
let result = desc.substr(0, len);
if (asMarkdown) {
result = markdown(result);
}
return result;
}
/**
* convert markdown text to html.
* @param {string} text - markdown text.
* @param {boolean} [breaks=false] if true, break line. FYI gfm is not breaks.
* @return {string} html.
*/
export function markdown(text, breaks = false) {
// original render does not support multi-byte anchor
const renderer = new marked.Renderer();
renderer.heading = function (text, level) {
const id = escapeURLHash(text);
return `${escape(code)}${escape(code)}`;
}
});
return compiled;
}
/**
* get UTC date string.
* @param {Date} date - target date object.
* @returns {string} UTC date string(yyyy-mm-dd hh:mm:ss)
*/
export function dateForUTC(date) {
function pad(num, len) {
const count = Math.max(0, len - `${num}`.length);
return '0'.repeat(count) + num;
}
const year = date.getUTCFullYear();
const month = pad(date.getUTCMonth() + 1, 2);
const day = pad(date.getUTCDay() + 1, 2);
const hours = pad(date.getUTCHours(), 2);
const minutes = pad(date.getUTCMinutes(), 2);
const seconds = pad(date.getUTCSeconds(), 2);
return `${year}-${month}-${day} ${hours}:${minutes}:${seconds} (UTC)`;
}
/**
* parse ``@example`` value.
* ``@example`` value can have ``
## Feature
- Generates detailed document.
- Measures document coverage.
- Integrate test codes into documentation.
- [ESDoc Hosting Service](https://doc.esdoc.org)
## Demo
- [ESDoc](https://esdoc.org/esdoc) is self-hosting 😄
## License
MIT
## Author
[Ryo Maruyama@h13i32maru](https://twitter.com/h13i32maru)
================================================
FILE: esdoc-publish-html-plugin/test/fixture/manual/tutorial.md
================================================
# Tutorial
this is tutorial.
================================================
FILE: esdoc-publish-html-plugin/test/fixture/manual/usage1.md
================================================
# Usage
```sh
esdoc -c esdoc.json
```
``esdoc.json``
```json
{
"source": "./src",
"destination": "./doc"
}
```
================================================
FILE: esdoc-publish-html-plugin/test/fixture/manual/usage2.md
================================================
# Usage2
this is usage2
## h2 in usage2
this is h2 in usage2
### h3 in usage2
this is h2 in usage3
================================================
FILE: esdoc-publish-html-plugin/test/fixture/package.json
================================================
{
"name": "esdoc-test-fixture",
"version": "1.2.3",
"private": true,
"description": "this is esdoc-publish-html-plugin fixture",
"author": {
"name": "h13i32maru",
"url": "http://h13i32maru.jp"
},
"homepage": "http://esdoc.org",
"repository": {
"type": "git",
"url": "https://github.com/esdoc/esdoc"
},
"main": "./src/Class/Definition.js"
}
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Abstract/Definition.js
================================================
/**
* this is TestAbstractDefinition.
*/
export default class TestAbstractDefinition {
/**
* this is abstract method1.
* @abstract
*/
method1(){}
/**
* this is abstract method2.
* @abstract
*/
method2(){}
}
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Abstract/Override.js
================================================
import TestAbstractDefinition from './Definition';
/**
* this is TestAbstractOverride
*/
export default class TestAbstractOverride extends TestAbstractDefinition {
/**
* this is override method1.
* @override
*/
method1(){}
/**
* this is override method2 with automatically detection.
*/
method2(){}
}
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Access/Class.js
================================================
/**
* this is TestAccessClassPublic.
* @public
*/
export default class TestAccessClassPublic {}
/**
* this is TestAccessClassProtected.
* @protected
*/
export class TestAccessClassProtected {}
/**
* this is TestAccessClassPrivate.
* @private
*/
export class TestAccessClassPrivate {}
/**
* this is TestAccessClassAutoPrivate.
*/
export class _TestAccessClassAutoPrivate {}
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Access/Function.js
================================================
/**
* this is testAccessFunctionPublic.
* @public
*/
export default function testAccessFunctionPublic(){}
/**
* this is testAccessFunctionProtected.
* @protected
*/
export function testAccessFunctionProtected(){}
/**
* this is testAccessFunctionPrivate.
* @private
*/
export function testAccessFunctionPrivate(){}
/**
* this is testAccessFunctionAutoPrivate.
*/
export function _testAccessFunctionAutoPrivate(){}
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Access/Method.js
================================================
/**
* this is TestAccessMethod.
*/
export default class TestAccessMethod {
/**
* this is method1.
* @public
*/
method1(){}
/**
* this is method2.
* @protected
*/
method2(){}
/**
* this is method3.
* @private
*/
method3(){}
/**
* this is _method4.
*/
_method4(){}
}
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Access/Property.js
================================================
/**
* this is TestAccessProperty.
*/
export default class TestAccessProperty {
constructor() {
/**
* this is p1.
* @public
* @type {number}
*/
this.p1 = 123;
/**
* this is p2.
* @protected
* @type {number}
*/
this.p2 = 123;
/**
* this is p3.
* @private
* @type {number}
*/
this.p3 = 123;
/**
* this is _p4.
* @type {number}
*/
this._p4 = 123;
}
}
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Access/Variable.js
================================================
/**
* this is testAccessVariablePublic.
* @type {number}
* @public
*/
export const testAccessVariablePublic = 123;
/**
* this is testAccessVariableProtected.
* @type {number}
* @protected
*/
export const testAccessVariableProtected = 123;
/**
* this is testAccessVariablePrivate.
* @type {number}
* @private
*/
export const testAccessVariablePrivate = 123;
/**
* this is _testAccessVariableAutoPrivate.
* @type {number}
*/
export const _testAccessVariableAutoPrivate = 123;
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Async/Function.js
================================================
/**
* this is testAsyncFunction.
*/
export default async function testAsyncFunction(){}
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Async/Method.js
================================================
/**
* this is TestAsyncMethod.
*/
export default class TestAsyncMethod {
/**
* this is async method1.
*/
async method1(){}
}
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Class/Definition.js
================================================
/**
* this is TestClassDefinition.
*/
export default class TestClassDefinition {
/**
* this is static method1.
*/
static method1(){
/**
* this is static p1.
* @type {number}
*/
this.p1 = 123;
}
/**
* this is get value1.
* @type {number}
*/
get value1(){}
/**
* this is set value2.
* @type {number}
*/
set value2(v){}
/**
* this is constructor.
*/
constructor(){
/**
* this is p1.
* @type {number}
*/
this.p1 = 123;
}
/**
* this is method1.
*/
method1(){}
}
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/ClassProperty/Definition.js
================================================
/**
* this is TestClassPropertyDefinition.
* @todo test `Access`, `Deprecated`, `Desc`, `Duplication`, `Example`, `Experimental`, `Guess`, `Ignore`, `Link`, `See`, `Since`, `Todo` and `Version`.
*/
export default class TestClassPropertyDefinition {
/**
* this is static p1.
* @type {number}
*/
static p1 = 123;
/**
* this is p1.
* @type {number}
*/
p1 = 123;
}
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Computed/Method.js
================================================
/**
* this is TestComputedMethod
*/
export default class TestComputedMethod {
/**
* this is foo.
*/
['foo'](){}
/**
* this is iterator.
*/
[Symbol.iterator]() { }
/**
* this is [foo].
*/
[foo](){}
/**
* this is [foo.bar.baz].
*/
[foo.bar.baz](){}
/**
* this is [foo + bar].
*/
[foo + bar](){}
/**
* this is [foo.p + bar].
*/
[foo.p + bar](){}
/**
* this is [foo()].
*/
[foo()](){}
/**
* this is [foo.bar()].
*/
[foo.bar()](){}
/**
* this is [`${foo}`].
*/
[`${foo}`](){}
/**
* this is *[foo.bar]
*/
*[foo.bar](){}
}
/**
* @ignore
*/
const foo = '';
/**
* @ignore
*/
const bar = '';
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Computed/Property.js
================================================
/**
* this is TestComputedProperty
*/
export default class TestComputedProperty {
/**
* this is constructor.
*/
constructor(){
/**
* this is foo.
* @type {number}
*/
this['foo'] = 123;
/**
* this is iterator.
* @type {number}
*/
this[Symbol.iterator] = 123;
/**
* this is [foo].
* @type {number}
*/
this[foo] = 123;
/**
* this is [foo.bar].
* @type {number}
*/
this[foo.bar] = 123;
/**
* this is [foo.bar.baz].
* @type {number}
*/
this[foo.bar.baz] = 123;
/**
* this is [foo + bar].
* @type {number}
*/
this[foo + bar] = 123;
/**
* this is [foo.p + bar].
* @type {number}
*/
this[foo.p + bar] = 123;
/**
* this is [foo()].
* @type {number}
*/
this[foo()] = 123;
/**
* this is [foo.bar()].
* @type {number}
*/
this[foo.bar()] = 123;
/**
* this is [`${foo}`].
* @type {number}
*/
this[`${foo}`] = 123;
}
}
/**
* @ignore
*/
const foo = '';
/**
* @ignore
*/
const bar = '';
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Decorator/Definition.js
================================================
/**
* this is TestDecoratorDefinition.
*/
@testDecoratorAnnotation1
export default class TestDecoratorDefinition {
/**
* this is static method1.
*/
@testDecoratorAnnotation1
static method1(){}
/**
* this is get value1.
* @type {number}
*/
@testDecoratorAnnotation1
get value1(){}
/**
* this is set value2.
* @type {number}
*/
@testDecoratorAnnotation1
set value2(v){}
/**
* this is method1.
*/
@testDecoratorAnnotation1
@testDecoratorAnnotation2(true)
method1(){}
}
/**
* this is testDecoratorAnnotation1.
*/
export function testDecoratorAnnotation1(){}
/**
* this is testDecoratorAnnotation2.
*/
export function testDecoratorAnnotation2(){}
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Deprecated/Class.js
================================================
/**
* this is TestDeprecatedClass.
* @deprecated this is deprecated.
*/
export default class TestDeprecatedClass {
constructor() {
/**
* this is p1.
* @type {number}
* @deprecated
*/
this.p1 = 123;
}
/**
* this is method1.
* @deprecated
*/
method1(){}
}
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Deprecated/Function.js
================================================
/**
* this is testDeprecatedFunction.
* @deprecated
*/
export default function testDeprecatedFunction(){}
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Deprecated/Variable.js
================================================
/**
* this is testDeprecatedVariable.
* @deprecated
*/
export const testDeprecatedVariable = 123;
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Desc/Class.js
================================================
/**
* @desc this is TestDescClass.
*/
export default class TestDescClass {
/**
* @desc this is constructor.
*/
constructor() {
/**
* @desc this is p1.
* @type {number}
*/
this.p1 = 123;
}
/**
* @desc this is method1.
*/
method1(){}
}
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Desc/Function.js
================================================
/**
* @desc this is testDescFunction.
*/
export default function testDescFunction(){}
================================================
FILE: esdoc-publish-html-plugin/test/fixture/src/Desc/Markdown.js
================================================
/**
* this is TestDescMarkdown.
*
* ```html
* 
## Install
```bash
npm install esdoc-publish-markdown-plugin
```
## Config
```json
{
"source": "./src",
"destination": "./doc",
"plugins": [
{
"name": "esdoc-publish-markdown-plugin",
"option": {
"filename":"README.md"
}
}
]
}
```
## LICENSE
MIT
## Author
[Ryo Maruyama@h13i32maru](https://github.com/h13i32maru)
================================================
FILE: esdoc-publish-markdown-plugin/misc/index.md
================================================
# Class
## `MyClass`
this is MyClass
### `constructor()`
this is constructor
### `member1: number`
this is member1.
### `member2: string`
this is member2.
### `method1(p1: ...number): boolean`
this is method1.
| Name | Type | Attribute | Description |
| --- | --- | --- | --- |
| p1 | ...number | | this is p1 |
### `method2(p1: number)`
this is method2.
| Name | Type | Attribute | Description |
| --- | --- | --- | --- |
| p1 | number | optional: true, default: 10 | this is p1 |
# Function
## `myFunction(p1: number): string`
this is myFunction
| Name | Type | Attribute | Description |
| --- | --- | --- | --- |
| p1 | number | | this is p1. |
================================================
FILE: esdoc-publish-markdown-plugin/package.json
================================================
{
"name": "esdoc-publish-markdown-plugin",
"version": "1.0.0",
"description": "A publish markdown plugin for ESDoc [PoC]",
"author": "h13i32maru",
"homepage": "https://github.com/esdoc/esdoc-plugins",
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/esdoc/esdoc-plugins"
},
"dependencies": {
"ice-cap": "0.0.4",
"to-markdown": "3.0.4"
},
"devDependencies": {
"esdoc": "latest",
"mocha": "2.5.3"
},
"engines": {
"node": ">= 6.0.0"
},
"scripts": {
"test": "rm -rf ./test/out && mocha --require ./test/init.js $(find test/ -regex '.*.test.js$') -R spec"
},
"keywords": [
"esdoc",
"markdown",
"plugin"
],
"files": [
"src",
"README.md"
],
"main": "src/Plugin.js"
}
================================================
FILE: esdoc-publish-markdown-plugin/src/AbstractBuilder.js
================================================
const path = require('path');
const fs = require('fs');
class AbstractBuilder {
constructor(docs) {
this._docs = docs;
}
makeHTML() {
return '';
}
_findAll(cond = {}) {
const keys = Object.keys(cond);
return this._docs.filter((doc) =>{
for (const key of keys) if (doc[key] !== cond[key]) return false;
return true;
});
}
_find(cond = {}) {
return this._findAll(cond)[0];
}
_makeSignature(doc) {
if (['constructor', 'method', 'function'].includes(doc.kind)) {
let params = [];
if (doc.params) params = doc.params.map(param => `${param.name}: ${param.types.join('|')}`);
const type = doc.return ? `: ${doc.return.types.join('|')}` : '';
return `\`${doc.name}(${params.join(', ')})${type}\``;
}
if (['member', 'variable'].includes(doc.kind)) {
const type = doc.type ? doc.type.types.join('|') : '*';
return `\`${doc.name}: ${type}\``;
}
}
_makeParamAttribute(param) {
const attrs = [];
if (param.nullable !== null) attrs.push(`nullable: ${param.nullable}`);
if (param.optional) attrs.push('optional: true');
if (param.defaultValue) attrs.push(`default: ${param.defaultValue}`);
return attrs.join(', ');
}
_readTemplate(fileName) {
const filePath = path.resolve(__dirname, `./template/${fileName}`);
return fs.readFileSync(filePath, {encoding: 'utf-8'});
}
}
module.exports = AbstractBuilder;
================================================
FILE: esdoc-publish-markdown-plugin/src/ClassBuilder.js
================================================
const AbstractBuilder = require('./AbstractBuilder');
const IceCap = require('ice-cap').default;
class ClassBuilder extends AbstractBuilder {
makeHTML() {
const docs = this._findAll({kind: 'class'});
const outputs = [];
for (const doc of docs) {
const ice = new IceCap(this._readTemplate('class.html'));
this._applyBody(doc, ice);
this._applyConstructor(doc, ice);
this._applyMember(doc, ice);
this._applyMethod(doc, ice);
outputs.push(ice.html);
}
return outputs.join('\n');
}
_applyBody(classDoc, ice) {
ice.text('className', `\`${classDoc.name}\``);
ice.text('classDesc', classDoc.description);
}
_applyConstructor(classDoc, ice) {
const constructorDoc = this._find({kind: 'constructor', memberof: classDoc.longname});
if (constructorDoc) {
ice.text('constructorSignature', this._makeSignature(constructorDoc));
ice.text('constructorDesc', constructorDoc.description);
}
}
_applyMember(classDoc, ice) {
const memberDocs = this._findAll({kind: 'member', memberof: classDoc.longname});
ice.loop('member', memberDocs, (index, doc, ice) =>{
ice.text('memberSignature', this._makeSignature(doc));
ice.text('memberDesc', doc.description);
});
}
_applyMethod(classDoc, ice) {
const methodDocs = this._findAll({kind: 'method', memberof: classDoc.longname});
ice.loop('method', methodDocs, (index, doc, ice) =>{
ice.text('methodSignature', this._makeSignature(doc));
ice.text('methodDesc', doc.description);
const params = doc.params || [];
ice.loop('methodParam', params, (index, param, ice) =>{
ice.text('name', param.name);
ice.text('type', param.types.join('|'));
ice.text('attribute', this._makeParamAttribute(param) || ' ');
ice.text('desc', param.description);
});
});
}
}
module.exports = ClassBuilder;
================================================
FILE: esdoc-publish-markdown-plugin/src/FunctionBuilder.js
================================================
const AbstractBuilder = require('./AbstractBuilder');
const IceCap = require('ice-cap').default;
class FunctionBuilder extends AbstractBuilder {
makeHTML() {
const docs = this._docs.filter(doc => doc.kind === 'function');
const outputs = [];
for (const doc of docs) {
const ice = new IceCap(this._readTemplate('function.html'));
this._applyBody(doc, ice);
this._applyParam(doc, ice);
outputs.push(ice.html);
}
return outputs.join('\n');
}
_applyBody(doc, ice) {
ice.text('functionName', this._makeSignature(doc));
ice.text('functionDesc', doc.description);
}
_applyParam(doc, ice) {
const params = doc.params || [];
ice.loop('functionParam', params, (index, param, ice) =>{
ice.text('name', param.name);
ice.text('type', param.types.join('|'));
ice.text('attribute', this._makeParamAttribute(param) || ' ');
ice.text('desc', param.description);
});
}
}
module.exports = FunctionBuilder;
================================================
FILE: esdoc-publish-markdown-plugin/src/Plugin.js
================================================
const toMarkdown = require('to-markdown');
const ClassBuilder = require('./ClassBuilder');
const FunctionBuilder = require('./FunctionBuilder');
class Plugin {
onHandleDocs(ev) {
this._docs = ev.data.docs;
}
onPublish(ev) {
// create builder
const classBuilder = new ClassBuilder(this._docs);
const functionBuilder = new FunctionBuilder(this._docs);
// create html
let html = '';
html += '| Name | Type | Attribute | Description |
| Name | Type | Attribute | Description |
## Install
```bash
npm install esdoc-react-plugin
```
## Config
```json
{
"source": "./src",
"destination": "./doc",
"plugins": [
{"name": "esdoc-standard-plugin"},
{"name": "esdoc-react-plugin"}
]
}
```
## Dependency
- esdoc-standard-plugin
## LICENSE
MIT
## Author
[Ryo Maruyama@h13i32maru](https://github.com/h13i32maru)
================================================
FILE: esdoc-react-plugin/package.json
================================================
{
"name": "esdoc-react-plugin",
"version": "1.0.1",
"description": "A React plugin for ESDoc [PoC]",
"author": "h13i32maru",
"homepage": "https://github.com/esdoc/esdoc-plugins",
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/esdoc/esdoc-plugins"
},
"dependencies": {
"cheerio": "1.0.0-rc.1"
},
"devDependencies": {
"esdoc": "latest",
"esdoc-standard-plugin": "latest",
"mocha": "2.5.3"
},
"engines": {
"node": ">= 6.0.0"
},
"scripts": {
"test": "rm -rf ./test/out && mocha --require ./test/init.js $(find test/ -regex '.*.test.js$') -R spec"
},
"keywords": [
"esdoc",
"react",
"plugin"
],
"files": [
"src",
"README.md"
],
"main": "src/Plugin.js"
}
================================================
FILE: esdoc-react-plugin/src/Plugin.js
================================================
const path = require('path');
const cheerio = require('cheerio');
const ParamParser = require('esdoc/out/src/Parser/ParamParser').default;
const DocBuilder = require('esdoc-publish-html-plugin/out/src/Builder/DocBuilder').default;
class Plugin {
constructor() {
this._docs = null;
this._reactPropsDocs = null;
}
onHandleDocs(ev) {
this._docs = ev.data.docs;
const reactPropsDocs = [];
for (const doc of ev.data.docs) {
if (doc.kind !== 'class') continue;
if (!doc.unknown) continue;
const reactProps = doc.unknown.filter(v => v.tagName === '@reactProps');
if (!reactProps.length) continue;
reactPropsDocs.push({
longname: doc.longname,
fileName: `${doc.longname}.html`,
reactProps: reactProps
});
}
this._reactPropsDocs = reactPropsDocs;
}
onHandleContent(ev) {
const content = ev.data.content;
const fileName = ev.data.fileName;
// only html
if (path.extname(fileName) !== '.html') return;
// find target doc
const doc = this._reactPropsDocs.find(doc => {
const regexp = new RegExp(`${doc.fileName}$`);
if (fileName.match(regexp)) return true;
});
if (!doc) return;
// create esdoc properties from react props
const properties = doc.reactProps.map(reactProp => {
const {typeText, paramName, paramDesc} = ParamParser.parseParamValue(reactProp.tagValue);
return ParamParser.parseParam(typeText, paramName, paramDesc);
});
// hack: create html
const docBuilder = DocBuilder.createDefaultBuilder();
const html = docBuilder._buildProperties(properties, 'React Props:').html;
// append html
const $ = cheerio.load(content);
$('.self-detail.detail').append(html);
ev.data.content = $.html();
}
}
module.exports = new Plugin();
================================================
FILE: esdoc-react-plugin/test/esdoc.json
================================================
{
"source": "./test/src",
"destination": "./test/out",
"excludes": ["\\.test\\.js$"],
"plugins": [
{"name": "esdoc-standard-plugin"},
{"name": "./src/Plugin.js"}
]
}
================================================
FILE: esdoc-react-plugin/test/init.js
================================================
const path = require('path');
const fs = require('fs');
const ESDocCLI = require('esdoc/out/src/ESDocCLI.js').default;
function cli() {
const cliPath = path.resolve('./node_modules/esdoc/out/ESDocCLI.js');
const argv = ['node', cliPath, '-c', './test/esdoc.json'];
const cli = new ESDocCLI(argv);
cli.exec();
global.docs = JSON.parse(fs.readFileSync('./test/out/index.json').toString());
}
cli();
================================================
FILE: esdoc-react-plugin/test/src/MyClass.js
================================================
/**
* This is MyClass.
* @reactProps {!number} prop1 - this is prop1
* @reactProps {string} prop2 - this is prop2
*/
export default class MyClass extends React.Component {
}
/**
* this is NonReactClass
*/
export class NonReactClass {
}
================================================
FILE: esdoc-react-plugin/test/src/MyClass.test.js
================================================
const assert = require('assert');
const {load, text} = require('../util');
describe('test/MyClass.js:', ()=> {
it('has React props', ()=>{
const $ = load('./test/out/class/src/MyClass.js~MyClass.html');
const $table = $('.self-detail.detail [data-ice="properties"]');
assert.equal(text($table, 'tbody tr:nth-child(1)'), 'prop1 number nullable: false this is prop1');
assert.equal(text($table, 'tbody tr:nth-child(2)'), 'prop2 string this is prop2');
});
it('does not have React props', ()=>{
const $ = load('./test/out/class/src/MyClass.js~NonReactClass.html');
const $table = $('.self-detail.detail [data-ice="properties"]');
assert.equal($table.length, 0);
});
});
================================================
FILE: esdoc-react-plugin/test/util.js
================================================
const fs = require('fs');
const cheerio = require('cheerio');
module.exports.load = function(fileName) {
const html = fs.readFileSync(fileName, {encoding: 'utf-8'});
return cheerio.load(html);
};
module.exports.text = function($el, query) {
return $el.find(query).text().replace(/\s+/g, ' ').trim();
};
================================================
FILE: esdoc-standard-plugin/CHANGELOG.md
================================================
# Changelog
## 1.0.0 (2017-07-30)
- Release
================================================
FILE: esdoc-standard-plugin/LICENSE
================================================
The MIT License (MIT)
Copyright (c) 2015 Ryo Maruyama
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
================================================
FILE: esdoc-standard-plugin/README.md
================================================
# ESDoc Standard Plugin
## Install
```bash
npm install esdoc-standard-plugin
```
## Config
```json
{
"source": "./src",
"destination": "./doc",
"plugins": [
{
"name": "esdoc-standard-plugin",
"option": {
"lint": {"enable": true},
"coverage": {"enable": true},
"accessor": {"access": ["public", "protected", "private"], "autoPrivate": true},
"undocumentIdentifier": {"enable": true},
"unexportedIdentifier": {"enable": false},
"typeInference": {"enable": true},
"brand": {
"logo": "./logo.png",
"title": "My Library",
"description": "this is awesome library",
"repository": "https://github.com/foo/bar",
"site": "http://my-library.org",
"author": "https://twitter.com/foo",
"image": "http://my-library.org/logo.png"
},
"manual": {
"index": "./manual/index.md",
"globalIndex": true,
"asset": "./manual/asset",
"files": [
"./manual/overview.md",
"./manual/design.md",
"./manual/installation.md",
"./manual/usage1.md",
"./manual/usage2.md",
"./manual/tutorial.md",
"./manual/configuration.md",
"./manual/example.md",
"./manual/advanced.md",
"./manual/faq.md",
"./CHANGELOG.md"
]
},
"test": {
"source": "./test/",
"interfaces": ["describe", "it", "context", "suite", "test"],
"includes": ["(spec|Spec|test|Test)\\.js$"],
"excludes": ["\\.config\\.js$"]
}
}
}
]
}
```
The `esdoc-standard-plugin` is a glue plugin. The following plugins are used by this.
- [esdoc-lint-plugin](https://github.com/esdoc/esdoc-plugins/tree/master/esdoc-lint-plugin)
- [esdoc-coverage-plugin](https://github.com/esdoc/esdoc-plugins/tree/master/esdoc-coverage-plugin)
- [esdoc-accessor-plugin](https://github.com/esdoc/esdoc-plugins/tree/master/esdoc-accessor-plugin)
- [esdoc-type-inference-plugin](https://github.com/esdoc/esdoc-plugins/tree/master/esdoc-type-inference-plugin)
- [esdoc-external-ecmascript-plugin](https://github.com/esdoc/esdoc-plugins/tree/master/esdoc-external-ecmascript-plugin)
- [esdoc-brand-plugin](https://github.com/esdoc/esdoc-plugins/tree/master/esdoc-brand-plugin)
- [esdoc-undocumented-identifier-plugin](https://github.com/esdoc/esdoc-plugins/tree/master/esdoc-undocumented-identifier-plugin)
- [esdoc-unexported-identifier-plugin](https://github.com/esdoc/esdoc-plugins/tree/master/esdoc-unexported-identifier-plugin)
- [esdoc-integrate-manual-plugin](https://github.com/esdoc/esdoc-plugins/tree/master/esdoc-integrate-manual-plugin)
- [esdoc-integrate-test-plugin](https://github.com/esdoc/esdoc-plugins/tree/master/esdoc-integrate-test-plugin)
- [esdoc-publish-html-plugin](https://github.com/esdoc/esdoc-plugins/tree/master/esdoc-publish-html-plugin)
## LICENSE
MIT
## Author
[Ryo Maruyama@h13i32maru](https://github.com/h13i32maru)
================================================
FILE: esdoc-standard-plugin/package.json
================================================
{
"name": "esdoc-standard-plugin",
"version": "1.0.0",
"description": "A standard plugin for ESDoc",
"author": "h13i32maru",
"homepage": "https://github.com/esdoc/esdoc-plugins",
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/esdoc/esdoc-plugins"
},
"dependencies": {
"esdoc-lint-plugin": "^1.0.0",
"esdoc-coverage-plugin": "^1.0.0",
"esdoc-accessor-plugin": "^1.0.0",
"esdoc-external-ecmascript-plugin": "^1.0.0",
"esdoc-brand-plugin": "^1.0.0",
"esdoc-undocumented-identifier-plugin": "^1.0.0",
"esdoc-unexported-identifier-plugin": "^1.0.0",
"esdoc-publish-html-plugin": "^1.0.0",
"esdoc-type-inference-plugin": "^1.0.0",
"esdoc-integrate-manual-plugin": "^1.0.0",
"esdoc-integrate-test-plugin": "^1.0.0"
},
"devDependencies": {
"esdoc": "latest",
"mocha": "2.5.3"
},
"engines": {
"node": ">= 6.0.0"
},
"scripts": {
"test": "rm -rf ./test/out && mocha --require ./test/init.js $(find test/ -regex '.*.test.js$') -R spec"
},
"keywords": [
"esdoc",
"standard",
"plugin"
],
"files": [
"src",
"README.md"
],
"main": "src/Plugin.js"
}
================================================
FILE: esdoc-standard-plugin/src/Plugin.js
================================================
class Plugin {
onHandlePlugins(ev) {
const option = ev.data.option || {};
const plugins = [
{name: 'esdoc-lint-plugin', option: option.lint},
{name: 'esdoc-coverage-plugin', option: option.coverage},
{name: 'esdoc-accessor-plugin', option: option.accessor},
{name: 'esdoc-type-inference-plugin', option: option.typeInference},
{name: 'esdoc-external-ecmascript-plugin'},
{name: 'esdoc-brand-plugin', option: option.brand},
{name: 'esdoc-undocumented-identifier-plugin', option: option.undocumentIdentifier},
{name: 'esdoc-unexported-identifier-plugin', option: option.unexportedIdentifier},
{name: 'esdoc-integrate-manual-plugin', option: option.manual},
{name: 'esdoc-integrate-test-plugin', option: option.test},
{name: 'esdoc-publish-html-plugin'}
];
const existPluginNames = ev.data.plugins.map(plugin => plugin.name);
for (const plugin of plugins) {
if (existPluginNames.includes(plugin.name)) continue;
if (plugin.option === undefined) delete plugin.option;
ev.data.plugins.push(plugin);
}
}
}
module.exports = new Plugin();
================================================
FILE: esdoc-standard-plugin/test/README.md
================================================
[](https://travis-ci.org/esdoc/esdoc)
[](https://coveralls.io/r/esdoc/esdoc)
# ESDoc Test Fixture
this is ESDoc Test Fixture README.
- item1
- item2
- item3
1st line.
second line.
http://github.com/h13i32maru/esdoc
```javascript
export default class Foo {
static get foo() {}
constructor(p1) {
}
}
var foo = 123;
```
| First Header | Second Header |
| ------------- | ------------- |
| Content Cell | Content Cell |
| Content Cell | Content Cell |
**text**
~~text~~
# text
## text
### text
#### text
##### text
================================================
FILE: esdoc-standard-plugin/test/esdoc.json
================================================
{
"source": "./test/src",
"destination": "./test/out",
"excludes": ["\\.test\\.js$"],
"index": "./test/README.md",
"package": "./test/package.json",
"plugins": [
{
"name": "./src/Plugin.js",
"option": {
"brand": {
"title": "My Library"
},
"manual": {
"files": ["./test/manual/overview.md"]
},
"test": {
"source": "./test/test",
"includes": ["Test.js$"]
}
}
},
{
"name": "./test/spy-plugin.js"
}
]
}
================================================
FILE: esdoc-standard-plugin/test/init.js
================================================
const path = require('path');
const fs = require('fs');
const ESDocCLI = require('esdoc/out/src/ESDocCLI.js').default;
function cli() {
const cliPath = path.resolve('./node_modules/esdoc/out/ESDocCLI.js');
const argv = ['node', cliPath, '-c', './test/esdoc.json'];
const cli = new ESDocCLI(argv);
cli.exec();
global.docs = JSON.parse(fs.readFileSync('./test/out/index.json').toString());
}
cli();
================================================
FILE: esdoc-standard-plugin/test/manual/overview.md
================================================
# This is Overview
fixture
================================================
FILE: esdoc-standard-plugin/test/package.json
================================================
{
"name": "esdoc-test-fixture",
"version": "1.2.3",
"repository": {
"type": "git",
"url": "https://github.com/esdoc/esdoc"
},
"main": "./src/Class/Definition.js"
}
================================================
FILE: esdoc-standard-plugin/test/spy-plugin.js
================================================
exports.onHandlePlugins = function(ev) {
exports.testTargetPlugins = ev.data.plugins;
};
================================================
FILE: esdoc-standard-plugin/test/src/MyClass.js
================================================
export default class MyClass {
/**
* this is invalid param name.
* @param xxx
*/
invalidMeethod(p){}
/**
* @param {number} p
*/
method1(p){}
/**
* @protected
*/
method2(){}
/**
* @private
*/
method3(){}
_method4(p = 1){}
}
================================================
FILE: esdoc-standard-plugin/test/src/Plugin.test.js
================================================
const assert = require('assert');
const path = require('path');
describe('test standard plugin:', ()=>{
it('dynamically load plugins', ()=>{
const plugins = require('../spy-plugin.js').testTargetPlugins;
assert.deepEqual(plugins, [
{name: './src/Plugin.js', option: {
brand: {
title: 'My Library'
},
manual: {
files: ['./test/manual/overview.md']
},
test: {
source: "./test/test",
includes: ["Test.js$"]
}
}},
{name: './test/spy-plugin.js'},
{name: 'esdoc-lint-plugin'},
{name: 'esdoc-coverage-plugin'},
{name: 'esdoc-accessor-plugin'},
{name: 'esdoc-type-inference-plugin'},
{name: 'esdoc-external-ecmascript-plugin'},
{name: 'esdoc-brand-plugin', option: {title: 'My Library'}},
{name: 'esdoc-undocumented-identifier-plugin'},
{name: 'esdoc-unexported-identifier-plugin'},
{name: 'esdoc-integrate-manual-plugin', option: {
coverage: true,
files: ['./test/manual/overview.md']
}},
{name: 'esdoc-integrate-test-plugin', option: {
source: "./test/test",
interfaces: ["describe", "it", "context", "suite", "test"],
includes: ["Test.js$"],
excludes: ["\\.config\\.js$"]
}},
{name: 'esdoc-publish-html-plugin'},
]);
});
});
================================================
FILE: esdoc-standard-plugin/test/test/MyClassTest.js
================================================
const assert = require('assert');
const MyClass = require('../src/MyClass');
/**
* @test {MyClass}
*/
describe('MyClass', ()=>{
it('has MyClass', ()=>{
assert(MyClass)
});
});
================================================
FILE: esdoc-type-inference-plugin/CHANGELOG.md
================================================
# Changelog
## Next
- **Fix**
- Crash if `export default foo = new Foo()` ([#55](https://github.com/esdoc/esdoc-plugins/pull/55)). Thanks [@ushu](https://github.com/ushu)
## 1.0.1 (2017-09-03)
- **Fix**
- Broken if array sparse destructuring ([esdoc/esdoc#394](https://github.com/esdoc/esdoc/pull/394)) Thanks [@technicallyfeasible](https://github.com/technicallyfeasible)
## 1.0.0 (2017-07-30)
- Release
================================================
FILE: esdoc-type-inference-plugin/LICENSE
================================================
The MIT License (MIT)
Copyright (c) 2015 Ryo Maruyama
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
================================================
FILE: esdoc-type-inference-plugin/README.md
================================================
# ESDoc Type Inference Plugin(PoC)
**This is Proof of Concept**
## Install
```bash
npm install esdoc-type-inference-plugin
```
## Config
```json
{
"source": "./src",
"destination": "./doc",
"plugins": [
{"name": "esdoc-type-inference-plugin", "option": {"enable": true}}
]
}
```
- `enable` is default `true`
## LICENSE
MIT
## Author
[Ryo Maruyama@h13i32maru](https://github.com/h13i32maru)
================================================
FILE: esdoc-type-inference-plugin/package.json
================================================
{
"name": "esdoc-type-inference-plugin",
"version": "1.0.1",
"description": "A type inference plugin for ESDoc [PoC]",
"author": "h13i32maru",
"homepage": "https://github.com/esdoc/esdoc-plugins",
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/esdoc/esdoc-plugins"
},
"devDependencies": {
"esdoc": "latest",
"mocha": "2.5.3"
},
"engines": {
"node": ">= 6.0.0"
},
"scripts": {
"test": "rm -rf ./test/out && mocha --require ./test/init.js $(find test/ -regex '.*.test.js$') -R spec"
},
"keywords": [
"esdoc",
"inference",
"plugin"
],
"files": [
"src",
"README.md"
],
"main": "src/Plugin.js"
}
================================================
FILE: esdoc-type-inference-plugin/src/Plugin.js
================================================
const ASTNodeContainer = require('esdoc/out/src/Util/ASTNodeContainer.js').default;
const ASTUtil = require('esdoc/out/src/Util/ASTUtil').default;
class Plugin {
onHandleDocs(ev) {
this._docs = ev.data.docs;
this._option = ev.data.option || {};
if (!('enable' in this._option)) this._option.enable = true;
this._exec();
}
_exec() {
if (!this._option.enable) return this._docs;
this._inferenceMethod();
this._inferenceFunction();
this._inferenceGetter();
this._inferenceSetter();
this._inferenceMember();
this._inferenceVariable();
}
_inferenceMethod() {
const docs = this._docs.filter((doc) => doc.kind === 'method');
for (const doc of docs) {
const node = ASTNodeContainer.getNode(doc.__docId__);
if (!doc.params) doc.params = this._inferenceParam(node);
if (!doc.return) doc.return = this._inferenceReturn(node);
}
}
_inferenceFunction() {
const docs = this._docs.filter((doc) => doc.kind === 'function');
for (const doc of docs) {
const node = ASTNodeContainer.getNode(doc.__docId__);
if (!doc.params) doc.params = this._inferenceParam(node);
if (!doc.return) doc.return = this._inferenceReturn(node);
}
}
_inferenceGetter() {
const docs = this._docs.filter((doc) => doc.kind === 'get');
for (const doc of docs) {
const node = ASTNodeContainer.getNode(doc.__docId__);
if (!doc.type) doc.type = this._inferenceReturn(node);
}
}
_inferenceSetter() {
// todo: infer setter is not working. please implement inference.
// const docs = this._docs.filter((doc) => doc.kind === 'set');
//
// for (const doc of docs) {
// const node = ASTNodeContainer.getNode(doc.__docId__);
// if (!doc.type) doc.type = this._inferenceType(node.right);
// }
}
_inferenceMember() {
const docs = this._docs.filter((doc) => doc.kind === 'member');
for (const doc of docs) {
const node = ASTNodeContainer.getNode(doc.__docId__);
if (!doc.type) doc.type = this._inferenceType(node.right);
}
}
_inferenceVariable() {
const docs = this._docs.filter((doc) => doc.kind === 'variable');
for (const doc of docs) {
if (doc.type) continue;
const node = ASTNodeContainer.getNode(doc.__docId__);
let className;
// e.g. `export default foo = new Foo();`
if (node.type === 'AssignmentExpression') {
if (node.right && node.right.type === 'NewExpression') {
className = node.right.callee.name;
} else {
doc.type = this._inferenceType(node.right);
continue;
}
}
// e.g. `let foo = new Foo();`
if (node.type === 'VariableDeclaration') {
if (node.declarations[0].init.type === 'NewExpression') {
className = node.declarations[0].init.callee.name;
} else {
doc.type = this._inferenceType(node.declarations[0].init);
continue;
}
}
// can not infer className
if (!className) {
doc.type = {types: ['*']};
continue;
}
if (className) {
// infer from same file.
const classDoc = this._docs.find((_doc) =>{
if (_doc.kind === 'class' && _doc.memberof === doc.memberof && _doc.name === className) {
return true;
}
});
if (classDoc) {
doc.type = {types: [classDoc.longname]};
continue;
}
// ambiguous infer from other file
const ambiguousClassDocs = this._docs.filter((_doc) => {
if (_doc.kind === 'class' && _doc.name === className) {
return true;
}
});
if (ambiguousClassDocs.length === 1) {
doc.type = {types: [ambiguousClassDocs[0].longname]};
continue;
}
// can not infer
doc.type = {types: ['*']};
} else {
doc.type = {types: ['*']};
}
}
}
_inferenceParam(node) {
const params = node.params;
const _params = [];
for (let i = 0; i < params.length; i++) {
const param = params[i];
const result = {};
switch (param.type) {
case 'Identifier':
// e.g. func(a){}
result.name = param.name;
result.types = ['*'];
break;
case 'AssignmentPattern':
if (param.left.type === 'Identifier') {
result.name = param.left.name;
} else if (param.left.type === 'ObjectPattern') {
result.name = `objectPattern${i === 0 ? '' : i}`;
} else if (param.left.type === 'ArrayPattern') {
result.name = `arrayPattern${i === 0 ? '' : i}`;
}
result.optional = true;
if (param.right.type.includes('Literal')) {
// e.g. func(a = 10){}
result.types = param.right.value === null ? ['*'] : [typeof param.right.value];
result.defaultRaw = param.right.value;
result.defaultValue = `${result.defaultRaw}`;
} else if (param.right.type === 'ArrayExpression') {
// e.g. func(a = [123]){}
result.types = param.right.elements.length ? [`${typeof param.right.elements[0].value}[]`] : ['*[]'];
result.defaultRaw = param.right.elements.map((elm)=> elm.value);
result.defaultValue = `${JSON.stringify(result.defaultRaw)}`;
} else if (param.right.type === 'ObjectExpression') {
const typeMap = {};
for (const prop of param.left.properties || []) {
typeMap[prop.key.name] = '*';
}
// e.g. func(a = {key: 123}){}
const obj = {};
for (const prop of param.right.properties) {
obj[prop.key.name] = prop.value.value;
typeMap[prop.key.name] = typeof prop.value.value;
}
const types = [];
for (const key of Object.keys(typeMap)) {
types.push(`"${key}": ${typeMap[key]}`);
}
result.types = [`{${types.join(', ')}}`];
result.defaultRaw = obj;
result.defaultValue = `${JSON.stringify(result.defaultRaw)}`;
} else if (param.right.type === 'Identifier') {
// e.g. func(a = value){}
result.types = ['*'];
result.defaultRaw = param.right.name;
result.defaultValue = `${param.right.name}`;
} else {
// e.g. func(a = new Foo()){}, func(a = foo()){}
// CallExpression, NewExpression
result.types = ['*'];
}
break;
case 'RestElement':
// e.g. func(...a){}
result.name = `${param.argument.name}`;
result.types = ['...*'];
result.spread = true;
break;
case 'ObjectPattern': {
const objectPattern = [];
const raw = {};
for (const property of param.properties) {
if (property.type === 'ObjectProperty') {
objectPattern.push(`"${property.key.name}": *`);
raw[property.key.name] = null;
} else if (property.type === 'RestProperty') {
objectPattern.push(`...${property.argument.name}: Object`);
raw[property.argument.name] = {};
}
}
result.name = `objectPattern${i === 0 ? '' : i}`;
result.types = [`{${objectPattern.join(', ')}}`];
result.defaultRaw = raw;
result.defaultValue = `${JSON.stringify(result.defaultRaw)}`;
break;
}
case 'ArrayPattern': {
// e.g. func([a, b = 10]){}
let arrayType = null;
const raw = [];
for (const element of param.elements) {
if (!element) { // case `function([, v]){}
raw.push('undefined');
} else if (element.type === 'Identifier') {
raw.push('null');
} else if (element.type === 'AssignmentPattern') {
if ('value' in element.right) {
if (!arrayType && element.right.value !== null) arrayType = typeof element.right.value;
raw.push(JSON.stringify(element.right.value));
} else {
raw.push('*');
}
}
}
if (!arrayType) arrayType = '*';
result.name = `arrayPattern${i === 0 ? '' : i}`;
result.types = [`${arrayType}[]`];
result.defaultRaw = raw;
result.defaultValue = `[${raw.join(', ')}]`;
break;
}
default:
logger.w('unknown param.type', param);
}
_params.push(result);
}
return _params;
}
_inferenceReturn(node) {
const body = node.body;
const result = {};
const inferenceType = this._inferenceType.bind(this);
ASTUtil.traverse(body, (node, parent, path)=>{
// `return` in Function is not the body's `return`
if (node.type.includes('Function')) {
path.skip();
return;
}
if (node.type !== 'ReturnStatement') return;
if (!node.argument) return;
result.types = inferenceType(node.argument).types;
});
if (result.types) {
return result;
}
return null;
}
_inferenceType(right) {
if (!right) {
return {types: ['*']};
}
if (right.type === 'TemplateLiteral') {
return {types: ['string']};
}
if (right.type === 'NullLiteral') {
return {types: ['*']};
}
if (right.type.includes('Literal')) {
return {types: [typeof right.value]};
}
if (right.type === 'ArrayExpression') {
if (right.elements.length) {
return {types: [`${typeof right.elements[0].value}[]`]};
} else {
return {types: ['*[]']};
}
}
if (right.type === 'ObjectExpression') {
const typeMap = {};
for (const prop of right.properties) {
switch (prop.type) {
case 'ObjectProperty': {
const name = `"${prop.key.name || prop.key.value}"`;
typeMap[name] = prop.value.value ? typeof prop.value.value : '*';
break;
}
case 'ObjectMethod': {
const name = `"${prop.key.name || prop.key.value}"`;
typeMap[name] = 'function';
break;
}
case 'SpreadProperty': {
const name = `...${prop.argument.name}`;
typeMap[name] = 'Object';
break;
}
default: {
const name = `"${prop.key.name || prop.key.value}"`;
typeMap[name] = '*';
}
}
}
const types = [];
for (const key of Object.keys(typeMap)) {
types.push(`${key}: ${typeMap[key]}`);
}
return {types: [`{${types.join(', ')}}`]};
}
return {types: ['*']};
}
}
module.exports = new Plugin();
================================================
FILE: esdoc-type-inference-plugin/test/esdoc.json
================================================
{
"source": "./test/src",
"destination": "./test/out",
"excludes": ["\\.test\\.js$"],
"plugins": [
{"name": "./src/Plugin.js"}
]
}
================================================
FILE: esdoc-type-inference-plugin/test/init.js
================================================
const path = require('path');
const fs = require('fs');
const ESDocCLI = require('esdoc/out/src/ESDocCLI.js').default;
function cli() {
const cliPath = path.resolve('./node_modules/esdoc/out/ESDocCLI.js');
const argv = ['node', cliPath, '-c', './test/esdoc.json'];
const cli = new ESDocCLI(argv);
cli.exec();
global.docs = JSON.parse(fs.readFileSync('./test/out/index.json').toString());
}
cli();
================================================
FILE: esdoc-type-inference-plugin/test/src/Getter.js
================================================
export default class TestGetter {
get getLiteral () {
return 123;
}
get getArray () {
return [123, 456];
}
get getObject() {
return {x1: 123, x2: 'text'};
}
get getTemplateLiteral() {
return `text`;
}
}
================================================
FILE: esdoc-type-inference-plugin/test/src/Getter.test.js
================================================
const assert = require('assert');
const {find} = require('../util');
describe('test/Getter.js:', ()=>{
it('infer type that is literal', ()=>{
const doc = find('longname', 'src/Getter.js~TestGetter#getLiteral');
assert.deepEqual(doc.type, {types: ['number']});
});
it('infer type that is array', ()=>{
const doc = find('longname', 'src/Getter.js~TestGetter#getArray');
assert.deepEqual(doc.type, {types: ['number[]']});
});
it('infer type that is object', ()=>{
const doc = find('longname', 'src/Getter.js~TestGetter#getObject');
assert.deepEqual(doc.type, {types: ['{"x1": number, "x2": string}']});
});
it('infer type that is template literal', ()=>{
const doc = find('longname', 'src/Getter.js~TestGetter#getTemplateLiteral');
assert.deepEqual(doc.type, {types: ['string']});
});
});
================================================
FILE: esdoc-type-inference-plugin/test/src/Member.js
================================================
export default class TestMember {
constructor() {
// literal
this.memberLiteral = 123;
// array
this.memberArray = [123, 456];
// object
this.memberObject = {x1: 123, x2: 'text'};
// template literal
this.memberTemplateLiteral= `text`;
}
}
================================================
FILE: esdoc-type-inference-plugin/test/src/Member.test.js
================================================
const assert = require('assert');
const {find} = require('../util');
describe('test/Member.js:', ()=>{
it('infer type that is literal', ()=>{
const doc = find('longname', 'src/Member.js~TestMember#memberLiteral');
assert.deepEqual(doc.type, {types: ['number']});
});
it('infer type that is array', ()=>{
const doc = find('longname', 'src/Member.js~TestMember#memberArray');
assert.deepEqual(doc.type, {types: ['number[]']});
});
it('infer type that is object', ()=>{
const doc = find('longname', 'src/Member.js~TestMember#memberObject');
assert.deepEqual(doc.type, {types: ['{"x1": number, "x2": string}']});
});
it('infer type that is template literal', ()=>{
const doc = find('longname', 'src/Member.js~TestMember#memberTemplateLiteral');
assert.deepEqual(doc.type, {types: ['string']});
});
});
================================================
FILE: esdoc-type-inference-plugin/test/src/Param.js
================================================
export default class TestParam {
// literal default
methodLiteral(p1 = 123){}
// identifier default
methodIdentifier(p1 = value){}
// new expression default
methodNewExpression(p1 = new Foo()){}
// array default
methodArray(p1 = [123, 456]){}
// array destructuring
methodArrayDestructuring([p1, p2]){}
// array default and destructuring
methodArrayAndDestructuring([p1, p2] = [123, 456]){}
// sparse array destructuring
methodArraySparseDestructuring([, p2]) {}
// object default
methodObject(p1 = {x1: "text", x2: true}){}
// object destructuring
methodObjectDestructuring({x1, x2}){}
// object default and destructuring
methodObjectAndDestructuring({x1, x2} = {x1: 123, x2: "text"}){}
// spread
methodSpread(...p1){}
// array destructuring and partial default
methodArrayDestructuringAndPartialDefault([p1, p2 = 10, p3 = null, p4 = 'text', p5 = v]){}
}
================================================
FILE: esdoc-type-inference-plugin/test/src/Param.test.js
================================================
const assert = require('assert');
const {find} = require('../util');
describe('test/Param.js:', ()=> {
it('infer literal param', ()=>{
const doc = find('longname', 'src/Param.js~TestParam#methodLiteral');
assert.deepEqual(doc.params, [
{
"name": "p1",
"optional": true,
"types": [
"number"
],
"defaultRaw": 123,
"defaultValue": "123"
}
]);
});
it('infer identifier param', ()=>{
const doc = find('longname', 'src/Param.js~TestParam#methodIdentifier');
assert.deepEqual(doc.params, [
{
"name": "p1",
"optional": true,
"types": [
"*"
],
"defaultRaw": "value",
"defaultValue": "value"
}
]);
});
it('infer new expression param', ()=>{
const doc = find('longname', 'src/Param.js~TestParam#methodNewExpression');
assert.deepEqual(doc.params, [
{
"name": "p1",
"optional": true,
"types": [
"*"
]
}
]);
});
it('infer array param', ()=>{
const doc = find('longname', 'src/Param.js~TestParam#methodArray');
assert.deepEqual(doc.params, [
{
"name": "p1",
"optional": true,
"types": [
"number[]"
],
"defaultRaw": [
123,
456
],
"defaultValue": "[123,456]"
}
]);
});
it('infer array destructuring param', ()=>{
const doc = find('longname', 'src/Param.js~TestParam#methodArrayDestructuring');
assert.deepEqual(doc.params, [
{
"name": "arrayPattern",
"types": [
"*[]"
],
"defaultRaw": [
"null",
"null"
],
"defaultValue": "[null, null]"
}
]);
});
it('infer array default and destructuring param', ()=>{
const doc = find('longname', 'src/Param.js~TestParam#methodArrayAndDestructuring');
assert.deepEqual(doc.params, [
{
"name": "arrayPattern",
"optional": true,
"types": [
"number[]"
],
"defaultRaw": [
123,
456
],
"defaultValue": "[123,456]"
}
]);
});
it('infer array sparse destructuring param', ()=>{
const doc = find('longname', 'src/Param.js~TestParam#methodArraySparseDestructuring');
assert.deepEqual(doc.params, [
{
"name": "arrayPattern",
"types": [
"*[]"
],
"defaultRaw": [
'undefined',
'null'
],
"defaultValue": "[undefined, null]"
}
]);
});
it('infer object param', ()=>{
const doc = find('longname', 'src/Param.js~TestParam#methodObject');
assert.deepEqual(doc.params, [
{
"name": "p1",
"optional": true,
"types": [
"{\"x1\": string, \"x2\": boolean}"
],
"defaultRaw": {
"x1": "text",
"x2": true
},
"defaultValue": "{\"x1\":\"text\",\"x2\":true}"
}
]);
});
it('infer object destructuring param', ()=>{
const doc = find('longname', 'src/Param.js~TestParam#methodObjectDestructuring');
assert.deepEqual(doc.params, [
{
"name": "objectPattern",
"types": [
"{\"x1\": *, \"x2\": *}"
],
"defaultRaw": {
"x1": null,
"x2": null
},
"defaultValue": "{\"x1\":null,\"x2\":null}"
}
]);
});
it('infer object default and destructuring param', ()=>{
const doc = find('longname', 'src/Param.js~TestParam#methodObjectAndDestructuring');
assert.deepEqual(doc.params, [
{
"name": "objectPattern",
"optional": true,
"types": [
"{\"x1\": number, \"x2\": string}"
],
"defaultRaw": {
"x1": 123,
"x2": "text"
},
"defaultValue": "{\"x1\":123,\"x2\":\"text\"}"
}
]);
});
it('infer spread param', ()=>{
const doc = find('longname', 'src/Param.js~TestParam#methodSpread');
assert.deepEqual(doc.params, [
{
"name": "p1",
"types": [
"...*"
],
"spread": true
}
]);
});
it('infer array destructuring and partial default param', ()=>{
const doc = find('longname', 'src/Param.js~TestParam#methodArrayDestructuringAndPartialDefault');
assert.deepEqual(doc.params, [
{
"name": "arrayPattern",
"types": [
"number[]"
],
"defaultRaw": [
"null",
"10",
"*",
"\"text\"",
"*"
],
"defaultValue": "[null, 10, *, \"text\", *]"
}
]);
});
});
================================================
FILE: esdoc-type-inference-plugin/test/src/Return.js
================================================
export default class TestReturn {
// literal
methodLiteral(){
return 123;
}
// array
methodArray(){
return [123, 456];
}
// object
methodObject(){
return {x1: 123, x2: 'text'};
}
// template literal
methodTemplateLiteral(){
return `text`;
}
}
================================================
FILE: esdoc-type-inference-plugin/test/src/Return.test.js
================================================
const assert = require('assert');
const {find} = require('../util');
describe('test/Return.js:', ()=>{
it('infer return value that is literal', ()=>{
const doc = find('longname', 'src/Return.js~TestReturn#methodLiteral');
assert.deepEqual(doc.return, {types: ['number']});
});
it('infer return value that is array', ()=>{
const doc = find('longname', 'src/Return.js~TestReturn#methodArray');
assert.deepEqual(doc.return, {types: ['number[]']});
});
it('infer return value that is object', ()=>{
const doc = find('longname', 'src/Return.js~TestReturn#methodObject');
assert.deepEqual(doc.return, {types: ['{"x1": number, "x2": string}']});
});
it('infer return value that is template literal', ()=>{
const doc = find('longname', 'src/Return.js~TestReturn#methodTemplateLiteral');
assert.deepEqual(doc.return, {types: ['string']});
});
});
================================================
FILE: esdoc-type-inference-plugin/test/src/Variable.js
================================================
// literal
export const testVariableLiteral = 123;
// array
export const testVariableArray = [123, 456];
// object
export const testVariableObject = {x1: 123, x2: "text"};
// template literal
export const testVariableTemplateLiteral = `text`;
// new expression with same file
export class TestVariableNewExpression {}
export default new TestVariableNewExpression();
// new expression with other file
import TestMember from './Member';
export const testVariableNewExpressionOtherFile = new TestMember();
================================================
FILE: esdoc-type-inference-plugin/test/src/Variable.test.js
================================================
const assert = require('assert');
const {find} = require('../util');
describe('test/Variable.js:', ()=>{
it('infer type that is literal', ()=>{
const doc = find('longname', 'src/Variable.js~testVariableLiteral');
assert.deepEqual(doc.type, {types: ['number']});
});
it('infer type that is array', ()=>{
const doc = find('longname', 'src/Variable.js~testVariableArray');
assert.deepEqual(doc.type, {types: ['number[]']});
});
it('infer type that is object', ()=>{
const doc = find('longname', 'src/Variable.js~testVariableObject');
assert.deepEqual(doc.type, {types: ['{"x1": number, "x2": string}']});
});
it('infer type that is template literal', ()=>{
const doc = find('longname', 'src/Variable.js~testVariableTemplateLiteral');
assert.deepEqual(doc.type, {types: ['string']});
});
it('infer type that is new expression with same file', ()=>{
const doc = find('longname', 'src/Variable.js~testVariableNewExpression');
assert.deepEqual(doc.type, {types: ['src/Variable.js~TestVariableNewExpression']});
});
it('infer type that is new expression with other file', ()=>{
const doc = find('longname', 'src/Variable.js~testVariableNewExpressionOtherFile');
assert.deepEqual(doc.type, {types: ['src/Member.js~TestMember']});
});
});
================================================
FILE: esdoc-type-inference-plugin/test/util.js
================================================
exports.find = function(key, ...values) {
if (values.length === 1) {
return global.docs.find((doc) => {
if (typeof values[0] === 'string') return doc[key] === values[0];
if (values[0] instanceof RegExp) return doc[key].match(values[0]);
});
}
const results = [];
for (const value of values) {
const result = global.docs.find(doc => {
if (typeof value === 'string') return doc[key] === value;
if (value instanceof RegExp) return doc[key].match(value);
});
results.push(result);
}
return results;
};
================================================
FILE: esdoc-typescript-plugin/CHANGELOG.md
================================================
# Changelog
## Next
- **Fix**
- Crash if overload methods ([#42](https://github.com/esdoc/esdoc-plugins/pull/42)). Thanks [@tchakabam](https://github.com/tchakabam)
- **Chore**
- Update typescript
## 1.0.0 (2017-07-30)
- Release
================================================
FILE: esdoc-typescript-plugin/LICENSE
================================================
The MIT License (MIT)
Copyright (c) 2015 Ryo Maruyama
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
================================================
FILE: esdoc-typescript-plugin/README.md
================================================
# ESDoc TypeScript Plugin (PoC)
**This plugin is proof of concept**
## Install
```bash
npm install esdoc-typescript-plugin
```
## Config
```json
{
"source": "./src",
"destination": "./doc",
"plugins": [
{"name": "esdoc-typescript-plugin", "option": {"enable": true}}
]
}
```
- `enable` is default `true`
## Example
```js
export class Foo {
// without document, with initializer
member: number = 10;
// without document
method1(n: number): string {
}
// without @param and @return
/**
* this is method2.
*/
method2(n: number): string {
}
// without type in @param and @return
/**
* this is method3.
* @param n - this is param desc.
* @return this is return desc.
*/
method3(n: number): string {
}
}
```
## LICENSE
MIT
## Author
[Ryo Maruyama@h13i32maru](https://github.com/h13i32maru)
================================================
FILE: esdoc-typescript-plugin/package.json
================================================
{
"name": "esdoc-typescript-plugin",
"version": "1.0.0",
"description": "A TypeScript plugin for ESDoc [PoC]",
"author": "h13i32maru",
"homepage": "https://github.com/esdoc/esdoc-plugins",
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/esdoc/esdoc-plugins"
},
"dependencies": {
"typescript": "^2.8.3"
},
"devDependencies": {
"esdoc": "^1.1.0",
"esdoc-standard-plugin": "^1.0.0",
"mocha": "2.5.3"
},
"engines": {
"node": ">= 6.0.0"
},
"scripts": {
"test": "rm -rf ./test/out && mocha --require ./test/init.js $(find test/ -regex '.*.test.js$') -R spec"
},
"keywords": [
"esdoc",
"typescript",
"plugin"
],
"files": [
"src",
"README.md"
],
"main": "src/Plugin.js"
}
================================================
FILE: esdoc-typescript-plugin/src/Plugin.js
================================================
const path = require('path');
const ts = require('typescript');
const CommentParser = require('esdoc/out/src/Parser/CommentParser').default;
class Plugin {
constructor() {
this._enable = true;
}
onStart(ev) {
if (!ev.data.option) return;
if ('enable' in ev.data.option) this._enable = ev.data.option.enable;
}
onHandleConfig(ev) {
if (!this._enable) return;
if (!ev.data.config.includes) ev.data.config.includes = [];
ev.data.config.includes.push('\\.ts$', '\\.js$');
}
onHandleCodeParser(ev) {
if (!this._enable) return;
const esParser = ev.data.parser;
const esParserOption = ev.data.parserOption;
const filePath = ev.data.filePath;
// ev.data.parser = this._tsParser.bind(this, esParser, esParserOption, filePath);
ev.data.parser = (code) =>{
try {
return this._tsParser(esParser, esParserOption, filePath, code);
} catch(e) {
console.log(e)
}
};
}
// https://github.com/Microsoft/TypeScript/blob/master/src/services/transpile.ts#L26
_tsParser(esParser, esParserOption, filePath, code) {
// return if not typescript
if (path.extname(filePath) !== '.ts') return esParser(code);
// create ast and get target nodes
const sourceFile = ts.createSourceFile(filePath, code, ts.ScriptTarget.Latest, true);
const nodes = this._getTargetTSNodes(sourceFile);
// rewrite jsdoc comment
nodes.sort((a,b) => b.pos - a.pos); // hack: transpile comment with reverse
const codeChars = [...code];
for (const node of nodes) {
const jsDocNode = this._getJSDocNode( node);
if (jsDocNode && jsDocNode.comment) codeChars.splice(jsDocNode.pos, jsDocNode.end - jsDocNode.pos);
const newComment = this._transpileComment(node, jsDocNode ? jsDocNode.comment : '', code);
codeChars.splice(node.pos, 0, newComment);
}
const newTSCode = codeChars.join('');
// transpile typescript to es
const esCode = this._transpileTS2ES(newTSCode);
return esParser(esCode);
}
_getTargetTSNodes(sourceFile) {
const nodes = [];
walk(sourceFile);
return nodes;
function walk(node) {
switch (node.kind) {
case ts.SyntaxKind.ClassDeclaration:
case ts.SyntaxKind.MethodDeclaration:
case ts.SyntaxKind.PropertyDeclaration:
case ts.SyntaxKind.GetAccessor:
case ts.SyntaxKind.SetAccessor:
case ts.SyntaxKind.FunctionDeclaration:
nodes.push(node);
break;
}
ts.forEachChild(node, walk);
}
}
_getJSDocNode(node) {
if (!node.jsDoc) return null;
return node.jsDoc[node.jsDoc.length - 1];
}
_transpileComment(node, comment, code) {
const esNode = {type: 'CommentBlock', value: `*\n${comment}`};
const tags = CommentParser.parse(esNode);
this._applyLOC(node, tags, code);
switch(node.kind) {
case ts.SyntaxKind.ClassDeclaration:
// do nothing
break;
case ts.SyntaxKind.MethodDeclaration:
this._applyCallableParam(node, tags);
this._applyCallableReturn(node, tags);
break;
case ts.SyntaxKind.PropertyDeclaration:
this._applyClassProperty(node, tags);
break;
case ts.SyntaxKind.GetAccessor:
this._applyClassMethodGetter(node, tags);
break;
case ts.SyntaxKind.SetAccessor:
this._applyClassMethodSetter(node, tags);
break;
case ts.SyntaxKind.FunctionDeclaration:
this._applyCallableParam(node, tags);
this._applyCallableReturn(node, tags);
break;
}
return `\n/*${CommentParser.buildComment(tags)} */\n`;
}
_applyLOC(node, tags, code) {
let loc = 1;
const codeChars = [...code];
for (let i = 0; i < node.name.end; i++) {
if (codeChars[i] === '\n') loc++;
}
tags.push({tagName: '@lineNumber', tagValue: `${loc}`});
}
_applyCallableParam(node, tags) {
const types = node.parameters.map(param => {
return {
type: this._getTypeFromAnnotation(param.type),
name: param.name.text
};
});
const paramTags = tags.filter(tag => tag.tagName === '@param');
// merge
// case: params without comments
if (paramTags.length === 0 && types.length) {
const tmp = types.map(({type, name}) => {
return {
tagName: '@param',
tagValue: `{${type}} ${name}`
};
});
tags.push(...tmp);
return;
}
// case: params with comments
if (paramTags.length === types.length) {
for (let i = 0; i < paramTags.length; i++) {
const paramTag = paramTags[i];
const type = types[i];
if (paramTag.tagValue.charAt(0) !== '{') { // does not have type
paramTag.tagValue = `{${type.type}} ${paramTag.tagValue}`;
}
}
return;
}
// case: mismatch params and comments
throw new Error('mismatch params and comments');
}
_applyCallableReturn(node, tags) {
if (!node.type) return;
// get type
const type = this._getTypeFromAnnotation(node.type);
if (!type) return;
// get comments
const returnTag = tags.find(tag => tag.tagName === '@return' || tag.tagName === '@returns');
// merge
if (returnTag && returnTag.tagValue.charAt(0) !== '{') { // return with comment but does not have type
returnTag.tagValue = `{${type}} ${returnTag.tagValue}`;
} else {
tags.push({tagName: '@return', tagValue: `{${type}}`});
}
}
_applyClassMethodGetter(node, tags) {
if (!node.type) return;
// get type
const type = this._getTypeFromAnnotation(node.type);
if (!type) return;
// get comments
const typeComment = tags.find(tag => tag.tagName === '@type');
if (typeComment && typeComment.tagValue.charAt(0) !== '{') { // type with comment but does not have tpe
typeComment.tagValue = `{${type}}`;
} else {
tags.push({tagName: '@type', tagValue: `{${type}}`});
}
}
_applyClassMethodSetter(node, tags) {
if (!node.parameters) return;
// get type
const type = this._getTypeFromAnnotation(node.parameters[0].type);
if (!type) return;
// get comment
const typeComment = tags.find(tag => tag.tagName === '@type');
if (typeComment) return;
// merge
// case: param without comment
tags.push({tagName: '@type', tagValue: `{${type}}`});
}
_applyClassProperty(node, tags) {
if (!node.type) return;
// get type
const type = this._getTypeFromAnnotation(node.type);
if (!type) return;
// get comments
const typeComment = tags.find(tag => tag.tagName === '@type');
if (typeComment && typeComment.tagValue.charAt(0) !== '{') { // type with comment but does not have tpe
typeComment.tagValue = `{${type}}`;
} else {
tags.push({tagName: '@type', tagValue: `{${type}}`});
}
}
_getTypeFromAnnotation(typeNode) {
if (!typeNode) {
return 'undefined';
}
switch(typeNode.kind) {
case ts.SyntaxKind.NumberKeyword: return 'number';
case ts.SyntaxKind.StringKeyword: return 'string';
case ts.SyntaxKind.BooleanKeyword: return 'boolean';
case ts.SyntaxKind.TypeReference: return typeNode.typeName.text;
}
}
_transpileTS2ES(tsCode) {
// todo
const esOption = {
decorators: true,
jsx: true,
};
const options = {
module: ts.ModuleKind.ES2015,
noResolve: true,
target: ts.ScriptTarget.Latest,
experimentalDecorators: esOption.decorators,
jsx: esOption.jsx ? 'preserve' : undefined,
};
const result = ts.transpileModule(tsCode, {compilerOptions: options});
return result.outputText;
}
}
module.exports = new Plugin();
================================================
FILE: esdoc-typescript-plugin/test/esdoc.json
================================================
{
"source": "./test/src",
"destination": "./test/out",
"excludes": ["\\.test\\.js"],
"plugins": [
{"name": "./src/Plugin.js"},
{"name": "esdoc-standard-plugin"}
]
}
================================================
FILE: esdoc-typescript-plugin/test/init.js
================================================
const path = require('path');
const fs = require('fs');
const ESDocCLI = require('esdoc/out/src/ESDocCLI.js').default;
function cli() {
const cliPath = path.resolve('./node_modules/esdoc/out/ESDocCLI.js');
const argv = ['node', cliPath, '-c', './test/esdoc.json'];
const cli = new ESDocCLI(argv);
cli.exec();
global.docs = JSON.parse(fs.readFileSync('./test/out/index.json').toString());
}
cli();
================================================
FILE: esdoc-typescript-plugin/test/src/TypeScript.test.js
================================================
const assert = require('assert');
const {find, file} = require('../util');
describe('test/TypeScript.js:', ()=> {
it('has type of method, without comment', ()=>{
const doc = find('longname', 'src/TypeScript.ts~TestTypeScriptClass#method1');
assert.equal(doc.params.length, 2);
assert.deepEqual(doc.params[0].types, ['number']);
assert.deepEqual(doc.params[1].types, ['Foo']);
assert.deepEqual(doc.return.types, ['string']);
});
it('has type of method, without tags', ()=>{
const doc = find('longname', 'src/TypeScript.ts~TestTypeScriptClass#method2');
assert.equal(doc.params.length, 2);
assert.deepEqual(doc.params[0].types, ['number']);
assert.deepEqual(doc.params[1].types, ['Foo']);
assert.deepEqual(doc.return.types, ['string']);
});
it('has type of method, without type', ()=>{
const doc = find('longname', 'src/TypeScript.ts~TestTypeScriptClass#method3');
assert.equal(doc.params.length, 2);
assert.deepEqual(doc.params[0].types, ['number']);
assert.deepEqual(doc.params[1].types, ['Foo']);
assert.deepEqual(doc.return.types, ['string']);
});
it('has type of getter, without comment', ()=>{
const doc = find('longname', 'src/TypeScript.ts~TestTypeScriptClass#getter1');
assert.deepEqual(doc.type.types, ['string']);
});
it('has type of setter, without comment', ()=>{
const doc = find('longname', 'src/TypeScript.ts~TestTypeScriptClass#setter1');
assert.deepEqual(doc.type.types, ['number']);
});
it('has type of member, without comment', ()=>{
const doc = find('longname', 'src/TypeScript.ts~TestTypeScriptClass#member1');
assert.deepEqual(doc.type.types, ['number']);
});
it('has type of function, without comment', ()=>{
const doc = find('longname', 'src/TypeScript.ts~testTypeScriptFunction');
assert.equal(doc.params.length, 2);
assert.deepEqual(doc.params[0].types, ['number']);
assert.deepEqual(doc.params[1].types, ['Foo']);
assert.deepEqual(doc.return.types, ['string']);
});
});
================================================
FILE: esdoc-typescript-plugin/test/src/TypeScript.ts
================================================
/**
* this is TestTypeScriptClass.
*/
export class TestTypeScriptClass {
member1: number = null;
get getter1(): string { return 'Hello'; }
set setter1(v: number) {}
method1(n: number, x: Foo): string {
return 'Hello'.repeat(n);
}
/**
* this is method2.
*/
method2(n: number, x: Foo): string {
return 'Hello'.repeat(n);
}
/**
* this is method3.
* @param n - this is n
* @param x - this is x
* @return this is return
*/
method3(n: number, x: Foo): string {
return 'Hello'.repeat(n);
}
}
export function testTypeScriptFunction(n: number, x: Foo): string{ return 'Hello'; }
export class Foo{}
================================================
FILE: esdoc-typescript-plugin/test/util.js
================================================
const fs = require('fs');
exports.find = function(key, ...values) {
if (values.length === 1) {
return global.docs.find((doc) => {
if (typeof values[0] === 'string') return doc[key] === values[0];
if (values[0] instanceof RegExp) return doc[key].match(values[0]);
});
}
const results = [];
for (const value of values) {
const result = global.docs.find(doc => {
if (typeof value === 'string') return doc[key] === value;
if (value instanceof RegExp) return doc[key].match(value);
});
results.push(result);
}
return results;
};
exports.file = function (filePath) {
return fs.readFileSync(filePath).toString();
};
================================================
FILE: esdoc-undocumented-identifier-plugin/CHANGELOG.md
================================================
# Changelog
## 1.0.0 (2017-07-30)
- Release
================================================
FILE: esdoc-undocumented-identifier-plugin/LICENSE
================================================
The MIT License (MIT)
Copyright (c) 2015 Ryo Maruyama
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
================================================
FILE: esdoc-undocumented-identifier-plugin/README.md
================================================
# ESDoc Undocumented Identifier Plugin
## Install
```bash
npm install esdoc-undocumented-identifier-plugin
```
## Config
```json
{
"source": "./src",
"destination": "./doc",
"plugins": [
{"name": "esdoc-undocumented-identifier-plugin", "option": {"enable": true}}
]
}
```
`enable` is default `true`.
## LICENSE
MIT
## Author
[Ryo Maruyama@h13i32maru](https://github.com/h13i32maru)
================================================
FILE: esdoc-undocumented-identifier-plugin/package.json
================================================
{
"name": "esdoc-undocumented-identifier-plugin",
"version": "1.0.0",
"description": "A undocumented identifier plugin for ESDoc",
"author": "h13i32maru",
"homepage": "https://github.com/esdoc/esdoc-plugins",
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/esdoc/esdoc-plugins"
},
"devDependencies": {
"esdoc": "latest",
"mocha": "2.5.3"
},
"engines": {
"node": ">= 6.0.0"
},
"scripts": {
"test": "rm -rf ./test/out && mocha --require ./test/init.js $(find test/ -regex '.*.test.js$') -R spec"
},
"keywords": [
"esdoc",
"undocument",
"plugin"
],
"files": [
"src",
"README.md"
],
"main": "src/Plugin.js"
}
================================================
FILE: esdoc-undocumented-identifier-plugin/src/Plugin.js
================================================
class Plugin {
onHandleDocs(ev) {
this._option = ev.data.option || {};
if (!('enable' in this._option)) this._option.enable = true;
const ignore = !this._option.enable;
for (const doc of ev.data.docs) {
if (doc.undocument === true && ignore && !('ignore' in doc)) {
doc.ignore = ignore;
}
}
}
}
module.exports = new Plugin();
================================================
FILE: esdoc-undocumented-identifier-plugin/test/esdoc.json
================================================
{
"source": "./test/src",
"destination": "./test/out",
"excludes": ["\\.test\\.js$"],
"plugins": [
{"name": "./src/Plugin.js"}
]
}
================================================
FILE: esdoc-undocumented-identifier-plugin/test/init.js
================================================
const path = require('path');
const fs = require('fs');
const ESDocCLI = require('esdoc/out/src/ESDocCLI.js').default;
function cli() {
const cliPath = path.resolve('./node_modules/esdoc/out/ESDocCLI.js');
const argv = ['node', cliPath, '-c', './test/esdoc.json'];
const cli = new ESDocCLI(argv);
cli.exec();
global.docs = JSON.parse(fs.readFileSync('./test/out/index.json').toString());
}
cli();
================================================
FILE: esdoc-undocumented-identifier-plugin/test/src/MyClass.js
================================================
export class MyClass1 {
}
/**
* this is desc
* @ignore
*/
export class MyClass2 {
}
================================================
FILE: esdoc-undocumented-identifier-plugin/test/src/MyClass.test.js
================================================
const assert = require('assert');
const {find, file} = require('../util');
describe('test undocumented identifier result:', ()=> {
it('does not ignore undocumented identifier.', ()=>{
const doc = find('name', 'MyClass1');
assert.equal(doc.undocument, true);
assert.equal(doc.ignore, undefined);
});
it('ignores documented identifier with @ignore.', ()=>{
const doc = find('name', 'MyClass2');
assert.equal(doc.undocument, undefined);
assert.equal(doc.ignore, true);
});
});
================================================
FILE: esdoc-undocumented-identifier-plugin/test/util.js
================================================
const fs = require('fs');
exports.find = function(key, ...values) {
if (values.length === 1) {
return global.docs.find((doc) => {
if (typeof values[0] === 'string') return doc[key] === values[0];
if (values[0] instanceof RegExp) return doc[key].match(values[0]);
});
}
const results = [];
for (const value of values) {
const result = global.docs.find(doc => {
if (typeof value === 'string') return doc[key] === value;
if (value instanceof RegExp) return doc[key].match(value);
});
results.push(result);
}
return results;
};
exports.file = function (filePath) {
return fs.readFileSync(filePath).toString();
};
================================================
FILE: esdoc-unexported-identifier-plugin/CHANGELOG.md
================================================
# Changelog
## 1.0.0 (2017-07-30)
- Release
================================================
FILE: esdoc-unexported-identifier-plugin/LICENSE
================================================
The MIT License (MIT)
Copyright (c) 2015 Ryo Maruyama
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
================================================
FILE: esdoc-unexported-identifier-plugin/README.md
================================================
# ESDoc Unexported Identifier Plugin
## Install
```bash
npm install esdoc-unexported-identifier-plugin
```
## Config
```json
{
"source": "./src",
"destination": "./doc",
"plugins": [
{"name": "esdoc-unexported-identifier-plugin", "option": {"enable": false}}
]
}
```
`enable` is default `false`.
## LICENSE
MIT
## Author
[Ryo Maruyama@h13i32maru](https://github.com/h13i32maru)
================================================
FILE: esdoc-unexported-identifier-plugin/package.json
================================================
{
"name": "esdoc-unexported-identifier-plugin",
"version": "1.0.0",
"description": "A unexported identifier plugin for ESDoc",
"author": "h13i32maru",
"homepage": "https://github.com/esdoc/esdoc-plugins",
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/esdoc/esdoc-plugins"
},
"devDependencies": {
"esdoc": "latest",
"mocha": "2.5.3"
},
"engines": {
"node": ">= 6.0.0"
},
"scripts": {
"test": "rm -rf ./test/out && mocha --require ./test/init.js $(find test/ -regex '.*.test.js$') -R spec"
},
"keywords": [
"esdoc",
"unexported",
"plugin"
],
"files": [
"src",
"README.md"
],
"main": "src/Plugin.js"
}
================================================
FILE: esdoc-unexported-identifier-plugin/src/Plugin.js
================================================
class Plugin {
onHandleDocs(ev) {
const option = ev.data.option || {};
if (!('enable' in option)) option.enable = false;
const ignore = !option.enable;
for (const doc of ev.data.docs) {
if (doc.export === false && ignore && !('ignore' in doc)) {
doc.ignore = ignore;
}
}
}
}
module.exports = new Plugin();
================================================
FILE: esdoc-unexported-identifier-plugin/test/esdoc.json
================================================
{
"source": "./test/src",
"destination": "./test/out",
"excludes": ["\\.test\\.js$"],
"plugins": [
{"name": "./src/Plugin.js"}
]
}
================================================
FILE: esdoc-unexported-identifier-plugin/test/init.js
================================================
const path = require('path');
const fs = require('fs');
const ESDocCLI = require('esdoc/out/src/ESDocCLI.js').default;
function cli() {
const cliPath = path.resolve('./node_modules/esdoc/out/ESDocCLI.js');
const argv = ['node', cliPath, '-c', './test/esdoc.json'];
const cli = new ESDocCLI(argv);
cli.exec();
global.docs = JSON.parse(fs.readFileSync('./test/out/index.json').toString());
}
cli();
================================================
FILE: esdoc-unexported-identifier-plugin/test/src/MyClass.js
================================================
class MyClass1 {
}
/**
* @ignore
*/
export class MyClass2 {
}
export class MyClass3 {
}
================================================
FILE: esdoc-unexported-identifier-plugin/test/src/MyClass.test.js
================================================
const assert = require('assert');
const {find, file} = require('../util');
describe('test unexported identifier result:', ()=> {
it('ignores unexported identifier.', ()=>{
const doc = find('name', 'MyClass1');
assert.equal(doc.export, false);
assert.equal(doc.ignore, true);
});
it('ignores exported identifier with @ignore.', ()=>{
const doc = find('name', 'MyClass2');
assert.equal(doc.export, true);
assert.equal(doc.ignore, true);
});
it('does not ignore exported identifier.', ()=>{
const doc = find('name', 'MyClass3');
assert.equal(doc.export, true);
assert.equal(doc.ignore, undefined);
});
});
================================================
FILE: esdoc-unexported-identifier-plugin/test/util.js
================================================
const fs = require('fs');
exports.find = function(key, ...values) {
if (values.length === 1) {
return global.docs.find((doc) => {
if (typeof values[0] === 'string') return doc[key] === values[0];
if (values[0] instanceof RegExp) return doc[key].match(values[0]);
});
}
const results = [];
for (const value of values) {
const result = global.docs.find(doc => {
if (typeof value === 'string') return doc[key] === value;
if (value instanceof RegExp) return doc[key].match(value);
});
results.push(result);
}
return results;
};
exports.file = function (filePath) {
return fs.readFileSync(filePath).toString();
};
================================================
FILE: script/check.sh
================================================
#!/bin/bash
for plugin in $(ls -1 -d esdoc-*)
do
cd $plugin
# localDate=$(TZ=UTC git log --date=format-local:%Y-%m-%d -n 1 ./ | grep Date | cut -d ' ' -f 4 | cut -d 'T' -f 1)
npmDate=$(npm view ./ | grep modified | awk -F "'" '{print $2}')
log=$(git log --since="$npmDate" --invert-grep --grep="bump v" -n 1 ./)
if [ "$log" != "" ]; then
echo $plugin
fi
cd ../
done
================================================
FILE: script/install.sh
================================================
#!/bin/bash -e
for plugin in $(ls -1 -d esdoc-*)
do
echo $plugin
(cd $plugin && npm install)
echo ========================================================================
done
================================================
FILE: script/test.sh
================================================
#!/bin/bash -e
for plugin in $(ls -1 -d esdoc-*)
do
echo $plugin
(cd $plugin && npm run test)
echo ========================================================================
done