Nomchy/discord.js
1
0
Fork 0
mirror of https://github.com/discordjs/discord.js.git synced 2026-03-18 20:43:30 +01:00
Code Issues Packages Projects Releases Wiki Activity

Give the docgen a facelift

Browse Source
This commit is contained in:
Schuyler Cebulskie
2016-10-26 23:30:37 -04:00
parent 4543422e37
commit b8946d5904
5 changed files with 39 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/docs.json Normal file
View File

File diff suppressed because one or more lines are too long

17
docs/generator/doc-scanner.js
View File

@@ -1,5 +1,4 @@
/* eslint no-console:0 no-return-assign:0 */ const jsdoc2md = require('jsdoc-to-markdown');
const parse = require('jsdoc-parse');
module.exports = class DocumentationScanner { module.exports = class DocumentationScanner {
constructor(generator) { constructor(generator) {
@@ -7,18 +6,6 @@ module.exports = class DocumentationScanner {
} }
scan(directory) { scan(directory) {
return new Promise((resolve, reject) => { return jsdoc2md.getTemplateData({ files: [`${directory}*.js`, `${directory}**/*.js`] });
const stream = parse({
src: [`${directory}*.js`, `${directory}**/*.js`],
});
let json = '';
stream.on('data', chunk => json += chunk.toString('utf-8'));
stream.on('error', reject);
stream.on('end', () => {
json = JSON.parse(json);
resolve(json);
});
});
} }
}; };

45
docs/generator/documentation.js
View File

@@ -1,3 +1,4 @@
/* eslint-disable no-console */
const DocumentedClass = require('./types/DocumentedClass'); const DocumentedClass = require('./types/DocumentedClass');
const DocumentedInterface = require('./types/DocumentedInterface'); const DocumentedInterface = require('./types/DocumentedInterface');
const DocumentedTypeDef = require('./types/DocumentedTypeDef'); const DocumentedTypeDef = require('./types/DocumentedTypeDef');
@@ -5,7 +6,7 @@ const DocumentedConstructor = require('./types/DocumentedConstructor');
const DocumentedMember = require('./types/DocumentedMember'); const DocumentedMember = require('./types/DocumentedMember');
const DocumentedFunction = require('./types/DocumentedFunction'); const DocumentedFunction = require('./types/DocumentedFunction');
const DocumentedEvent = require('./types/DocumentedEvent'); const DocumentedEvent = require('./types/DocumentedEvent');
const GEN_VERSION = require('./config.json').GEN_VERSION; const GEN_VERSION = require('./config').GEN_VERSION;
class Documentation { class Documentation {
constructor(items, custom) { constructor(items, custom) {
@@ -35,29 +36,20 @@ class Documentation {
} }
findParent(item) { findParent(item) {
if (['constructor', 'member', 'function', 'event'].indexOf(item.kind) > -1) { if (['constructor', 'member', 'function', 'event'].includes(item.kind)) {
if (this.classes.get(item.memberof)) { let val = this.classes.get(item.memberof);
return this.classes.get(item.memberof); if (val) return val;
} val = this.interfaces.get(item.memberof);
if (this.interfaces.get(item.memberof)) { if (val) return val;
return this.interfaces.get(item.memberof);
}
} }
return; return null;
} }
parse(items) { parse(items) {
this.registerRoots( this.registerRoots(items.filter(item => ['class', 'interface', 'typedef'].includes(item.kind)));
items.filter( const members = items.filter(item => !['class', 'interface', 'typedef'].includes(item.kind));
item => ['class', 'interface', 'typedef'].indexOf(item.kind) > -1
)
);
const members = items.filter(
item => ['class', 'interface', 'typedef'].indexOf(item.kind) === -1
);
const unknowns = new Map(); const unknowns = new Map();
for (const member of members) { for (const member of members) {
let item; let item;
switch (member.kind) { switch (member.kind) {
@@ -75,22 +67,18 @@ class Documentation {
break; break;
default: default:
unknowns.set(member.kind, member); unknowns.set(member.kind, member);
break; continue;
}
if (!item) {
continue;
} }
const parent = this.findParent(member); const parent = this.findParent(member);
if (!parent) { if (!parent) {
console.log(new Error(`${member.name || member.directData.name} has no accessible parent`)); console.warn(`Warning: "${member.name || member.directData.name}" has no accessible parent.`);
continue; continue;
} }
parent.add(item); parent.add(item);
} }
if (unknowns.size > 0) { for (const [key, val] of unknowns) {
Array.from(unknowns.keys()).map( console.log(`Unknown documentation kind "${key}" - \n${JSON.stringify(val)}\n`);
k => console.log(`Unknown documentation kind ${k} - \n${JSON.stringify(unknowns.get(k))}\n`
));
} }
} }
@@ -99,7 +87,6 @@ class Documentation {
version: GEN_VERSION, version: GEN_VERSION,
date: Date.now(), date: Date.now(),
}; };
const serialized = { const serialized = {
meta, meta,
classes: Array.from(this.classes.values()).map(c => c.serialize()), classes: Array.from(this.classes.values()).map(c => c.serialize()),

39
docs/generator/generator.js
View File

@@ -1,34 +1,29 @@
/* eslint no-console:0 no-return-assign:0 */ /* eslint-disable no-console */
const GEN_VERSION = require('./config.json').GEN_VERSION;
const compress = require('./config.json').COMPRESS;
const DocumentationScanner = require('./doc-scanner');
const Documentation = require('./documentation');
const fs = require('fs-extra'); const fs = require('fs-extra');
const zlib = require('zlib'); const zlib = require('zlib');
const jsdoc2md = require('jsdoc-to-markdown');
const Documentation = require('./documentation');
const custom = require('../custom/index'); const custom = require('../custom/index');
const config = require('./config');
const docScanner = new DocumentationScanner(this); process.on('unhandledRejection', console.error);
function parseDocs(json) { console.log(`Using format version ${config.GEN_VERSION}.`);
console.log(`${json.length} items found`); console.log('Parsing JSDocs in source files...');
const documentation = new Documentation(json, custom);
console.log('serializing'); jsdoc2md.getTemplateData({ files: [`./src/*.js`, `./src/**/*.js`] }).then(data => {
console.log(`${data.length} items found.`);
const documentation = new Documentation(data, custom);
console.log('Serializing...');
let output = JSON.stringify(documentation.serialize(), null, 0); let output = JSON.stringify(documentation.serialize(), null, 0);
if (compress) { if (config.compress) {
console.log('compressing'); console.log('Compressing...');
output = zlib.deflateSync(output).toString('utf8'); output = zlib.deflateSync(output).toString('utf8');
} }
if (!process.argv.slice(2).includes('silent')) { if (!process.argv.slice(2).includes('silent')) {
console.log('writing to docs.json'); console.log('Writing to docs.json...');
fs.writeFileSync('./docs/docs.json', output); fs.writeFileSync('./docs/docs.json', output);
} }
console.log('done!'); console.log('Done!');
process.exit(0); process.exit(0);
} }).catch(console.error);
console.log(`using format version ${GEN_VERSION}`);
console.log('scanning for documentation');
docScanner.scan('./src/')
.then(parseDocs)
.catch(console.error);

6
package.json
View File

@@ -26,7 +26,7 @@
}, },
"homepage": "https://github.com/hydrabolt/discord.js#readme", "homepage": "https://github.com/hydrabolt/discord.js#readme",
"dependencies": { "dependencies": {
"superagent": "^2.2.0", "superagent": "^2.3.0",
"tweetnacl": "^0.14.3", "tweetnacl": "^0.14.3",
"ws": "^1.1.1" "ws": "^1.1.1"
}, },
@@ -35,9 +35,9 @@
"opusscript": "^0.0.1" "opusscript": "^0.0.1"
}, },
"devDependencies": { "devDependencies": {
"eslint": "^3.8.0",
"fs-extra": "^0.30.0", "fs-extra": "^0.30.0",
"jsdoc-parse": "^1.2.0", "jsdoc-to-markdown": "^2.0.0"
"eslint": "^3.4.0"
}, },
"engines": { "engines": {
"node": ">=6.0.0" "node": ">=6.0.0"