discordjs/discord.js
2
0
Fork 0
mirror of https://github.com/discordjs/discord.js.git synced 2024-08-21 11:44:42 +12:00
Code Issues Projects Releases Packages 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
Show stats 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 parse = require('jsdoc-parse');
const jsdoc2md = require('jsdoc-to-markdown');
module.exports = class DocumentationScanner {
constructor(generator) {
@ -7,18 +6,6 @@ module.exports = class DocumentationScanner {
}
scan(directory) {
return new Promise((resolve, reject) => {
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);
});
});
return jsdoc2md.getTemplateData({ files: [`${directory}*.js`, `${directory}**/*.js`] });
}
};

45
docs/generator/documentation.js
View file

@ -1,3 +1,4 @@
/* eslint-disable no-console */
const DocumentedClass = require('./types/DocumentedClass');
const DocumentedInterface = require('./types/DocumentedInterface');
const DocumentedTypeDef = require('./types/DocumentedTypeDef');
@ -5,7 +6,7 @@ const DocumentedConstructor = require('./types/DocumentedConstructor');
const DocumentedMember = require('./types/DocumentedMember');
const DocumentedFunction = require('./types/DocumentedFunction');
const DocumentedEvent = require('./types/DocumentedEvent');
const GEN_VERSION = require('./config.json').GEN_VERSION;
const GEN_VERSION = require('./config').GEN_VERSION;
class Documentation {
constructor(items, custom) {
@ -35,29 +36,20 @@ class Documentation {
}
findParent(item) {
if (['constructor', 'member', 'function', 'event'].indexOf(item.kind) > -1) {
if (this.classes.get(item.memberof)) {
return this.classes.get(item.memberof);
}
if (this.interfaces.get(item.memberof)) {
return this.interfaces.get(item.memberof);
}
if (['constructor', 'member', 'function', 'event'].includes(item.kind)) {
let val = this.classes.get(item.memberof);
if (val) return val;
val = this.interfaces.get(item.memberof);
if (val) return val;
}
return;
return null;
}
parse(items) {
this.registerRoots(
items.filter(
item => ['class', 'interface', 'typedef'].indexOf(item.kind) > -1
)
);
const members = items.filter(
item => ['class', 'interface', 'typedef'].indexOf(item.kind) === -1
);
this.registerRoots(items.filter(item => ['class', 'interface', 'typedef'].includes(item.kind)));
const members = items.filter(item => !['class', 'interface', 'typedef'].includes(item.kind));
const unknowns = new Map();
for (const member of members) {
let item;
switch (member.kind) {
@ -75,22 +67,18 @@ class Documentation {
break;
default:
unknowns.set(member.kind, member);
break;
}
if (!item) {
continue;
continue;
}
const parent = this.findParent(member);
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;
}
parent.add(item);
}
if (unknowns.size > 0) {
Array.from(unknowns.keys()).map(
k => console.log(`Unknown documentation kind ${k} - \n${JSON.stringify(unknowns.get(k))}\n`
));
for (const [key, val] of unknowns) {
console.log(`Unknown documentation kind "${key}" - \n${JSON.stringify(val)}\n`);
}
}
@ -99,7 +87,6 @@ class Documentation {
version: GEN_VERSION,
date: Date.now(),
};
const serialized = {
meta,
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 */
const GEN_VERSION = require('./config.json').GEN_VERSION;
const compress = require('./config.json').COMPRESS;
const DocumentationScanner = require('./doc-scanner');
const Documentation = require('./documentation');
/* eslint-disable no-console */
const fs = require('fs-extra');
const zlib = require('zlib');
const jsdoc2md = require('jsdoc-to-markdown');
const Documentation = require('./documentation');
const custom = require('../custom/index');
const config = require('./config');
const docScanner = new DocumentationScanner(this);
process.on('unhandledRejection', console.error);
function parseDocs(json) {
console.log(`${json.length} items found`);
const documentation = new Documentation(json, custom);
console.log('serializing');
console.log(`Using format version ${config.GEN_VERSION}.`);
console.log('Parsing JSDocs in source files...');
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);
if (compress) {
console.log('compressing');
if (config.compress) {
console.log('Compressing...');
output = zlib.deflateSync(output).toString('utf8');
}
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);
}
console.log('done!');
console.log('Done!');
process.exit(0);
}
console.log(`using format version ${GEN_VERSION}`);
console.log('scanning for documentation');
docScanner.scan('./src/')
.then(parseDocs)
.catch(console.error);
}).catch(console.error);

6
package.json
View file

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