From 7c97244854d2901c3b98ea891176be291d5a3575 Mon Sep 17 00:00:00 2001 From: Schuyler Cebulskie Date: Tue, 22 Nov 2016 18:24:29 -0500 Subject: [PATCH] Move to new docgen --- .travis.yml | 2 +- README.md | 6 +- {docs/deploy => deploy}/deploy.sh | 2 +- {docs/deploy => deploy}/deploy_key.enc | Bin docs/README.md | 3 +- docs/custom/avatar.js | 10 - docs/custom/faq.js | 7 - docs/custom/index.js | 17 -- docs/custom/ping_pong.js | 10 - docs/custom/updating.js | 7 - docs/custom/webhook.js | 10 - docs/custom/welcome.js | 7 - docs/{custom => }/examples/avatar.js | 0 docs/{custom => }/examples/ping_pong.js | 0 docs/{custom => }/examples/webhook.js | 0 docs/{custom/documents => general}/faq.md | 0 .../{custom/documents => general}/updating.md | 256 +++++++++--------- docs/{custom/documents => general}/welcome.md | 124 ++++----- docs/generator/config.json | 4 - docs/generator/documentation.js | 101 ------- docs/generator/index.js | 33 --- docs/generator/types/DocumentedClass.js | 80 ------ docs/generator/types/DocumentedConstructor.js | 42 --- docs/generator/types/DocumentedEvent.js | 76 ------ docs/generator/types/DocumentedFunction.js | 88 ------ docs/generator/types/DocumentedInterface.js | 32 --- docs/generator/types/DocumentedItem.js | 17 -- docs/generator/types/DocumentedItemMeta.js | 27 -- docs/generator/types/DocumentedMember.js | 56 ---- docs/generator/types/DocumentedParam.js | 36 --- docs/generator/types/DocumentedTypeDef.js | 48 ---- docs/generator/types/DocumentedVarType.js | 45 --- package.json | 7 +- 33 files changed, 200 insertions(+), 953 deletions(-) rename {docs/deploy => deploy}/deploy.sh (99%) rename {docs/deploy => deploy}/deploy_key.enc (100%) delete mode 100644 docs/custom/avatar.js delete mode 100644 docs/custom/faq.js delete mode 100644 docs/custom/index.js delete mode 100644 docs/custom/ping_pong.js delete mode 100644 docs/custom/updating.js delete mode 100644 docs/custom/webhook.js delete mode 100644 docs/custom/welcome.js rename docs/{custom => }/examples/avatar.js (100%) rename docs/{custom => }/examples/ping_pong.js (100%) rename docs/{custom => }/examples/webhook.js (100%) rename docs/{custom/documents => general}/faq.md (100%) rename docs/{custom/documents => general}/updating.md (97%) rename docs/{custom/documents => general}/welcome.md (96%) delete mode 100644 docs/generator/config.json delete mode 100644 docs/generator/documentation.js delete mode 100644 docs/generator/index.js delete mode 100644 docs/generator/types/DocumentedClass.js delete mode 100644 docs/generator/types/DocumentedConstructor.js delete mode 100644 docs/generator/types/DocumentedEvent.js delete mode 100644 docs/generator/types/DocumentedFunction.js delete mode 100644 docs/generator/types/DocumentedInterface.js delete mode 100644 docs/generator/types/DocumentedItem.js delete mode 100644 docs/generator/types/DocumentedItemMeta.js delete mode 100644 docs/generator/types/DocumentedMember.js delete mode 100644 docs/generator/types/DocumentedParam.js delete mode 100644 docs/generator/types/DocumentedTypeDef.js delete mode 100644 docs/generator/types/DocumentedVarType.js diff --git a/.travis.yml b/.travis.yml index c31f0f431..de3f3d9dd 100644 --- a/.travis.yml +++ b/.travis.yml @@ -7,7 +7,7 @@ cache: install: npm install script: - npm run test - - bash ./docs/deploy/deploy.sh + - bash ./deploy/deploy.sh env: global: - ENCRYPTION_LABEL: "af862fa96d3e" diff --git a/README.md b/README.md index e8392968c..c305a51d3 100644 --- a/README.md +++ b/README.md @@ -59,10 +59,10 @@ the entire `Discord` object is available as a global (on the `window` object). The ShardingManager and any voice-related functionality is unavailable in these builds. ## Links -* [Website](http://discord.js.org/) +* [Website](https://discord.js.org/) * [Discord.js server](https://discord.gg/bRCvFy9) * [Discord API server](https://discord.gg/rV4BwdK) -* [Documentation](http://discord.js.org/#/docs) +* [Documentation](https://discord.js.org/#/docs) * [Legacy (v8) documentation](http://discordjs.readthedocs.io/en/8.2.0/docs_client.html) * [Examples](https://github.com/hydrabolt/discord.js/tree/master/docs/custom/examples) * [GitHub](https://github.com/hydrabolt/discord.js) @@ -71,7 +71,7 @@ The ShardingManager and any voice-related functionality is unavailable in these ## Contributing Before creating an issue, please ensure that it hasn't already been reported/suggested, and double-check the -[documentation](http://discord.js.org/#/docs). +[documentation](https://discord.js.org/#/docs). See [the contributing guide](CONTRIBUTING.md) if you'd like to submit a PR. ## Help diff --git a/docs/deploy/deploy.sh b/deploy/deploy.sh similarity index 99% rename from docs/deploy/deploy.sh rename to deploy/deploy.sh index d20038b87..eee2336bb 100644 --- a/docs/deploy/deploy.sh +++ b/deploy/deploy.sh @@ -5,7 +5,7 @@ set -e function build { # Build docs - node docs/generator + npm run docs # Build the webpack VERSIONED=false npm run web-dist diff --git a/docs/deploy/deploy_key.enc b/deploy/deploy_key.enc similarity index 100% rename from docs/deploy/deploy_key.enc rename to deploy/deploy_key.enc diff --git a/docs/README.md b/docs/README.md index 7092346cf..d41af8eaf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,2 +1 @@ -# discord.js docs -[View documentation here](http://discord.js.org/#/docs) +## [View the documentation here.](https://discord.js.org/#/docs) diff --git a/docs/custom/avatar.js b/docs/custom/avatar.js deleted file mode 100644 index b3a77ced7..000000000 --- a/docs/custom/avatar.js +++ /dev/null @@ -1,10 +0,0 @@ -const fs = require('fs'); - -module.exports = { - category: 'Examples', - name: 'Avatars', - data: -`\`\`\`js -${fs.readFileSync('./docs/custom/examples/avatar.js').toString('utf-8')} -\`\`\``, -}; diff --git a/docs/custom/faq.js b/docs/custom/faq.js deleted file mode 100644 index abb06946a..000000000 --- a/docs/custom/faq.js +++ /dev/null @@ -1,7 +0,0 @@ -const fs = require('fs'); - -module.exports = { - category: 'General', - name: 'FAQ', - data: fs.readFileSync('./docs/custom/documents/faq.md').toString('utf-8'), -}; diff --git a/docs/custom/index.js b/docs/custom/index.js deleted file mode 100644 index 49e594bc0..000000000 --- a/docs/custom/index.js +++ /dev/null @@ -1,17 +0,0 @@ -const files = [ - require('./welcome'), - require('./updating'), - require('./faq'), - require('./ping_pong'), - require('./avatar'), - require('./webhook'), -]; - -const categories = {}; -for (const file of files) { - file.category = file.category.toLowerCase(); - if (!categories[file.category]) categories[file.category] = []; - categories[file.category].push(file); -} - -module.exports = categories; diff --git a/docs/custom/ping_pong.js b/docs/custom/ping_pong.js deleted file mode 100644 index c6952ad6c..000000000 --- a/docs/custom/ping_pong.js +++ /dev/null @@ -1,10 +0,0 @@ -const fs = require('fs'); - -module.exports = { - category: 'Examples', - name: 'Ping Pong', - data: -`\`\`\`js -${fs.readFileSync('./docs/custom/examples/ping_pong.js').toString('utf-8')} -\`\`\``, -}; diff --git a/docs/custom/updating.js b/docs/custom/updating.js deleted file mode 100644 index 1615d95cd..000000000 --- a/docs/custom/updating.js +++ /dev/null @@ -1,7 +0,0 @@ -const fs = require('fs'); - -module.exports = { - category: 'General', - name: 'Updating your code', - data: fs.readFileSync('./docs/custom/documents/updating.md').toString('utf-8'), -}; diff --git a/docs/custom/webhook.js b/docs/custom/webhook.js deleted file mode 100644 index 10f57f361..000000000 --- a/docs/custom/webhook.js +++ /dev/null @@ -1,10 +0,0 @@ -const fs = require('fs'); - -module.exports = { - category: 'Examples', - name: 'Webhooks', - data: -`\`\`\`js -${fs.readFileSync('./docs/custom/examples/webhook.js').toString('utf-8')} -\`\`\``, -}; diff --git a/docs/custom/welcome.js b/docs/custom/welcome.js deleted file mode 100644 index 809093e7e..000000000 --- a/docs/custom/welcome.js +++ /dev/null @@ -1,7 +0,0 @@ -const fs = require('fs'); - -module.exports = { - category: 'General', - name: 'Welcome', - data: fs.readFileSync('./docs/custom/documents/welcome.md').toString('utf-8'), -}; diff --git a/docs/custom/examples/avatar.js b/docs/examples/avatar.js similarity index 100% rename from docs/custom/examples/avatar.js rename to docs/examples/avatar.js diff --git a/docs/custom/examples/ping_pong.js b/docs/examples/ping_pong.js similarity index 100% rename from docs/custom/examples/ping_pong.js rename to docs/examples/ping_pong.js diff --git a/docs/custom/examples/webhook.js b/docs/examples/webhook.js similarity index 100% rename from docs/custom/examples/webhook.js rename to docs/examples/webhook.js diff --git a/docs/custom/documents/faq.md b/docs/general/faq.md similarity index 100% rename from docs/custom/documents/faq.md rename to docs/general/faq.md diff --git a/docs/custom/documents/updating.md b/docs/general/updating.md similarity index 97% rename from docs/custom/documents/updating.md rename to docs/general/updating.md index 9efe1c8f8..2926691ab 100644 --- a/docs/custom/documents/updating.md +++ b/docs/general/updating.md @@ -1,128 +1,128 @@ -# Version 10 -Version 10's non-BC changes focus on cleaning up some inconsistencies that exist in previous versions. -Upgrading from v9 should be quick and painless. - -## Client options -All client options have been converted to camelCase rather than snake_case, and `max_message_cache` was renamed to `messageCacheMaxSize`. - -v9 code example: -```js -const client = new Discord.Client({ - disable_everyone: true, - max_message_cache: 500, - message_cache_lifetime: 120, - message_sweep_interval: 60 -}); -``` - -v10 code example: -```js -const client = new Discord.Client({ - disableEveryone: true, - messageCacheMaxSize: 500, - messageCacheLifetime: 120, - messageSweepInterval: 60 -}); -``` - -## Presences -Presences have been completely restructured. -Previous versions of discord.js assumed that users had the same presence amongst all guilds - with the introduction of sharding, however, this is no longer the case. - -v9 discord.js code may look something like this: -```js -User.status; // the status of the user -User.game; // the game that the user is playing -ClientUser.setStatus(status, game, url); // set the new status for the user -``` - -v10 moves presences to GuildMember instances. For the sake of simplicity, though, User classes also expose presences. -When accessing a presence on a User object, it simply finds the first GuildMember for the user, and uses its presence. -Additionally, the introduction of the Presence class keeps all of the presence data organised. - -**It is strongly recommended that you use a GuildMember's presence where available, rather than a User. -A user may have an entirely different presence between two different guilds.** - -v10 code: -```js -MemberOrUser.presence.status; // the status of the member or user -MemberOrUser.presence.game; // the game that the member or user is playing -ClientUser.setStatus(status); // online, idle, dnd, offline -ClientUser.setGame(game, streamingURL); // a game -ClientUser.setPresence(fullPresence); // status and game combined -``` - -## Voice -Voice has been rewritten internally, but in a backwards-compatible manner. -There is only one breaking change here; the `disconnected` event was renamed to `disconnect`. -Several more events have been made available to a VoiceConnection, so see the documentation. - -## Events -Many events have been renamed or had their arguments change. - -### Client events -| Version 9 | Version 10 | -|------------------------------------------------------|-----------------------------------------------| -| guildMemberAdd(guild, member) | guildMemberAdd(member) | -| guildMemberAvailable(guild, member) | guildMemberAvailable(member) | -| guildMemberRemove(guild, member) | guildMemberRemove(member) | -| guildMembersChunk(guild, members) | guildMembersChunk(members) | -| guildMemberUpdate(guild, oldMember, newMember) | guildMemberUpdate(oldMember, newMember) | -| guildRoleCreate(guild, role) | roleCreate(role) | -| guildRoleDelete(guild, role) | roleDelete(role) | -| guildRoleUpdate(guild, oldRole, newRole) | roleUpdate(oldRole, newRole) | - -The guild parameter that has been dropped from the guild-related events can still be derived using `member.guild` or `role.guild`. - -### VoiceConnection events -| Version 9 | Version 10 | -|--------------|------------| -| disconnected | disconnect | - -## Dates and timestamps -All dates/timestamps on the structures have been refactored to have a consistent naming scheme and availability. -All of them are named similarly to this: -**Date:** `Message.createdAt` -**Timestamp:** `Message.createdTimestamp` -See the docs for each structure to see which date/timestamps are available on them. - - -# Version 9 -The version 9 (v9) rewrite takes a much more object-oriented approach than previous versions, -which allows your code to be much more readable and manageable. -It's been rebuilt from the ground up and should be much more stable, fixing caching issues that affected -older versions. It also has support for newer Discord Features, such as emojis. - -Version 9, while containing a sizable number of breaking changes, does not require much change in your code's logic - -most of the concepts are still the same, but loads of functions have been moved around. -The vast majority of methods you're used to using have been moved out of the Client class, -into other more relevant classes where they belong. -Because of this, you will need to convert most of your calls over to the new methods. - -Here are a few examples of methods that have changed: -* `Client.sendMessage(channel, message)` ==> `TextChannel.sendMessage(message)` - * `Client.sendMessage(user, message)` ==> `User.sendMessage(message)` -* `Client.updateMessage(message, "New content")` ==> `Message.edit("New Content")` -* `Client.getChannelLogs(channel, limit)` ==> `TextChannel.fetchMessages({options})` -* `Server.detailsOfUser(User)` ==> `Server.members.get(User).properties` (retrieving a member gives a GuildMember object) -* `Client.joinVoiceChannel(voicechannel)` => `VoiceChannel.join()` - -A couple more important details: -* `Client.loginWithToken("token")` ==> `client.login("token")` -* `Client.servers.length` ==> `client.guilds.size` (all instances of `server` are now `guild`) - -## No more callbacks! -Version 9 eschews callbacks in favour of Promises. This means all code relying on callbacks must be changed. -For example, the following code: - -```js -client.getChannelLogs(channel, 100, function(messages) { - console.log(`${messages.length} messages found`); -}); -``` - -```js -channel.fetchMessages({limit: 100}).then(messages => { - console.log(`${messages.size} messages found`); -}); -``` +# Version 10 +Version 10's non-BC changes focus on cleaning up some inconsistencies that exist in previous versions. +Upgrading from v9 should be quick and painless. + +## Client options +All client options have been converted to camelCase rather than snake_case, and `max_message_cache` was renamed to `messageCacheMaxSize`. + +v9 code example: +```js +const client = new Discord.Client({ + disable_everyone: true, + max_message_cache: 500, + message_cache_lifetime: 120, + message_sweep_interval: 60 +}); +``` + +v10 code example: +```js +const client = new Discord.Client({ + disableEveryone: true, + messageCacheMaxSize: 500, + messageCacheLifetime: 120, + messageSweepInterval: 60 +}); +``` + +## Presences +Presences have been completely restructured. +Previous versions of discord.js assumed that users had the same presence amongst all guilds - with the introduction of sharding, however, this is no longer the case. + +v9 discord.js code may look something like this: +```js +User.status; // the status of the user +User.game; // the game that the user is playing +ClientUser.setStatus(status, game, url); // set the new status for the user +``` + +v10 moves presences to GuildMember instances. For the sake of simplicity, though, User classes also expose presences. +When accessing a presence on a User object, it simply finds the first GuildMember for the user, and uses its presence. +Additionally, the introduction of the Presence class keeps all of the presence data organised. + +**It is strongly recommended that you use a GuildMember's presence where available, rather than a User. +A user may have an entirely different presence between two different guilds.** + +v10 code: +```js +MemberOrUser.presence.status; // the status of the member or user +MemberOrUser.presence.game; // the game that the member or user is playing +ClientUser.setStatus(status); // online, idle, dnd, offline +ClientUser.setGame(game, streamingURL); // a game +ClientUser.setPresence(fullPresence); // status and game combined +``` + +## Voice +Voice has been rewritten internally, but in a backwards-compatible manner. +There is only one breaking change here; the `disconnected` event was renamed to `disconnect`. +Several more events have been made available to a VoiceConnection, so see the documentation. + +## Events +Many events have been renamed or had their arguments change. + +### Client events +| Version 9 | Version 10 | +|------------------------------------------------------|-----------------------------------------------| +| guildMemberAdd(guild, member) | guildMemberAdd(member) | +| guildMemberAvailable(guild, member) | guildMemberAvailable(member) | +| guildMemberRemove(guild, member) | guildMemberRemove(member) | +| guildMembersChunk(guild, members) | guildMembersChunk(members) | +| guildMemberUpdate(guild, oldMember, newMember) | guildMemberUpdate(oldMember, newMember) | +| guildRoleCreate(guild, role) | roleCreate(role) | +| guildRoleDelete(guild, role) | roleDelete(role) | +| guildRoleUpdate(guild, oldRole, newRole) | roleUpdate(oldRole, newRole) | + +The guild parameter that has been dropped from the guild-related events can still be derived using `member.guild` or `role.guild`. + +### VoiceConnection events +| Version 9 | Version 10 | +|--------------|------------| +| disconnected | disconnect | + +## Dates and timestamps +All dates/timestamps on the structures have been refactored to have a consistent naming scheme and availability. +All of them are named similarly to this: +**Date:** `Message.createdAt` +**Timestamp:** `Message.createdTimestamp` +See the docs for each structure to see which date/timestamps are available on them. + + +# Version 9 +The version 9 (v9) rewrite takes a much more object-oriented approach than previous versions, +which allows your code to be much more readable and manageable. +It's been rebuilt from the ground up and should be much more stable, fixing caching issues that affected +older versions. It also has support for newer Discord Features, such as emojis. + +Version 9, while containing a sizable number of breaking changes, does not require much change in your code's logic - +most of the concepts are still the same, but loads of functions have been moved around. +The vast majority of methods you're used to using have been moved out of the Client class, +into other more relevant classes where they belong. +Because of this, you will need to convert most of your calls over to the new methods. + +Here are a few examples of methods that have changed: +* `Client.sendMessage(channel, message)` ==> `TextChannel.sendMessage(message)` + * `Client.sendMessage(user, message)` ==> `User.sendMessage(message)` +* `Client.updateMessage(message, "New content")` ==> `Message.edit("New Content")` +* `Client.getChannelLogs(channel, limit)` ==> `TextChannel.fetchMessages({options})` +* `Server.detailsOfUser(User)` ==> `Server.members.get(User).properties` (retrieving a member gives a GuildMember object) +* `Client.joinVoiceChannel(voicechannel)` => `VoiceChannel.join()` + +A couple more important details: +* `Client.loginWithToken("token")` ==> `client.login("token")` +* `Client.servers.length` ==> `client.guilds.size` (all instances of `server` are now `guild`) + +## No more callbacks! +Version 9 eschews callbacks in favour of Promises. This means all code relying on callbacks must be changed. +For example, the following code: + +```js +client.getChannelLogs(channel, 100, function(messages) { + console.log(`${messages.length} messages found`); +}); +``` + +```js +channel.fetchMessages({limit: 100}).then(messages => { + console.log(`${messages.size} messages found`); +}); +``` diff --git a/docs/custom/documents/welcome.md b/docs/general/welcome.md similarity index 96% rename from docs/custom/documents/welcome.md rename to docs/general/welcome.md index 0d2b4aad3..33ac6e077 100644 --- a/docs/custom/documents/welcome.md +++ b/docs/general/welcome.md @@ -1,62 +1,62 @@ -
-
-

- discord.js -

-
-

- Discord server - NPM version - NPM downloads - Build status - Dependencies -

-

- NPM info -

-
- -# Welcome! -Welcome to the discord.js v10 documentation. -v10 is just a more consistent and stable iteration over v9, and contains loads of new and improved features, optimisations, and bug fixes. - -## About -discord.js is a powerful node.js module that allows you to interact with the [Discord API](https://discordapp.com/developers/docs/intro) very easily. -It takes a much more object-oriented approach than most other JS Discord libraries, making your bot's code significantly tidier and easier to comprehend. -Usability and performance are key focuses of discord.js, and it also has nearly 100% coverage of the Discord API. - -## Installation -**Node.js 6.0.0 or newer is required.** - -Without voice support: `npm install discord.js --save` -With voice support ([node-opus](https://www.npmjs.com/package/node-opus)): `npm install discord.js node-opus --save` -With voice support ([opusscript](https://www.npmjs.com/package/opusscript)): `npm install discord.js opusscript --save` - -The preferred audio engine is node-opus, as it performs significantly better than opusscript. When both are available, discord.js will automatically choose node-opus. -Using opusscript is only recommended for development environments where node-opus is tough to get working. -For production bots, using node-opus should be considered a necessity, especially if they're going to be running on multiple servers. - -## Web distributions -Web builds of discord.js that are fully capable of running in browsers are available [here](https://github.com/hydrabolt/discord.js/tree/webpack). -These are built by [Webpack 2](https://webpack.js.org/). The API is identical, but rather than using `require('discord.js')`, -the entire `Discord` object is available as a global (on the `window` object). -The ShardingManager and any voice-related functionality is unavailable in these builds. - -## Guides -* [LuckyEvie's general guide](https://eslachance.gitbooks.io/discord-js-bot-guide/content/) -* [York's v9 upgrade guide](https://yorkaargh.wordpress.com/2016/09/03/updating-discord-js-bots/) - -## Links -* [Website](http://discord.js.org/) -* [Discord.js server](https://discord.gg/bRCvFy9) -* [Discord API server](https://discord.gg/rV4BwdK) -* [Documentation](http://discord.js.org/#/docs) -* [Legacy (v8) documentation](http://discordjs.readthedocs.io/en/8.2.0/docs_client.html) -* [Examples](https://github.com/hydrabolt/discord.js/tree/master/docs/custom/examples) -* [GitHub](https://github.com/hydrabolt/discord.js) -* [NPM](https://www.npmjs.com/package/discord.js) -* [Related libraries](https://discordapi.com/unofficial/libs.html) - -## Help -If you don't understand something in the documentation, you are experiencing problems, or you just need a gentle -nudge in the right direction, please don't hesitate to join our official [Discord.js Server](https://discord.gg/bRCvFy9). +
+
+

+ discord.js +

+
+

+ Discord server + NPM version + NPM downloads + Build status + Dependencies +

+

+ NPM info +

+
+ +# Welcome! +Welcome to the discord.js v10 documentation. +v10 is just a more consistent and stable iteration over v9, and contains loads of new and improved features, optimisations, and bug fixes. + +## About +discord.js is a powerful node.js module that allows you to interact with the [Discord API](https://discordapp.com/developers/docs/intro) very easily. +It takes a much more object-oriented approach than most other JS Discord libraries, making your bot's code significantly tidier and easier to comprehend. +Usability and performance are key focuses of discord.js, and it also has nearly 100% coverage of the Discord API. + +## Installation +**Node.js 6.0.0 or newer is required.** + +Without voice support: `npm install discord.js --save` +With voice support ([node-opus](https://www.npmjs.com/package/node-opus)): `npm install discord.js node-opus --save` +With voice support ([opusscript](https://www.npmjs.com/package/opusscript)): `npm install discord.js opusscript --save` + +The preferred audio engine is node-opus, as it performs significantly better than opusscript. When both are available, discord.js will automatically choose node-opus. +Using opusscript is only recommended for development environments where node-opus is tough to get working. +For production bots, using node-opus should be considered a necessity, especially if they're going to be running on multiple servers. + +## Web distributions +Web builds of discord.js that are fully capable of running in browsers are available [here](https://github.com/hydrabolt/discord.js/tree/webpack). +These are built by [Webpack 2](https://webpack.js.org/). The API is identical, but rather than using `require('discord.js')`, +the entire `Discord` object is available as a global (on the `window` object). +The ShardingManager and any voice-related functionality is unavailable in these builds. + +## Guides +* [LuckyEvie's general guide](https://eslachance.gitbooks.io/discord-js-bot-guide/content/) +* [York's v9 upgrade guide](https://yorkaargh.wordpress.com/2016/09/03/updating-discord-js-bots/) + +## Links +* [Website](https://discord.js.org/) +* [Discord.js server](https://discord.gg/bRCvFy9) +* [Discord API server](https://discord.gg/rV4BwdK) +* [Documentation](https://discord.js.org/#/docs) +* [Legacy (v8) documentation](http://discordjs.readthedocs.io/en/8.2.0/docs_client.html) +* [Examples](https://github.com/hydrabolt/discord.js/tree/master/docs/custom/examples) +* [GitHub](https://github.com/hydrabolt/discord.js) +* [NPM](https://www.npmjs.com/package/discord.js) +* [Related libraries](https://discordapi.com/unofficial/libs.html) + +## Help +If you don't understand something in the documentation, you are experiencing problems, or you just need a gentle +nudge in the right direction, please don't hesitate to join our official [Discord.js Server](https://discord.gg/bRCvFy9). diff --git a/docs/generator/config.json b/docs/generator/config.json deleted file mode 100644 index 0efc2dc71..000000000 --- a/docs/generator/config.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "GEN_VERSION": 14, - "COMPRESS": false -} diff --git a/docs/generator/documentation.js b/docs/generator/documentation.js deleted file mode 100644 index f5dba5b1c..000000000 --- a/docs/generator/documentation.js +++ /dev/null @@ -1,101 +0,0 @@ -/* eslint-disable no-console */ -const DocumentedClass = require('./types/DocumentedClass'); -const DocumentedInterface = require('./types/DocumentedInterface'); -const DocumentedTypeDef = require('./types/DocumentedTypeDef'); -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').GEN_VERSION; - -class Documentation { - constructor(items, custom) { - this.classes = new Map(); - this.interfaces = new Map(); - this.typedefs = new Map(); - this.custom = custom; - this.parse(items); - } - - registerRoots(data) { - for (const item of data) { - switch (item.kind) { - case 'class': - this.classes.set(item.name, new DocumentedClass(this, item)); - break; - case 'interface': - this.interfaces.set(item.name, new DocumentedInterface(this, item)); - break; - case 'typedef': - this.typedefs.set(item.name, new DocumentedTypeDef(this, item)); - break; - default: - break; - } - } - } - - findParent(item) { - 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 null; - } - - parse(items) { - 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) { - case 'constructor': - item = new DocumentedConstructor(this, member); - break; - case 'member': - item = new DocumentedMember(this, member); - break; - case 'function': - item = new DocumentedFunction(this, member); - break; - case 'event': - item = new DocumentedEvent(this, member); - break; - default: - unknowns.set(member.kind, member); - continue; - } - - const parent = this.findParent(member); - if (!parent) { - console.warn(`- "${member.name || member.directData.name}" has no accessible parent.`); - continue; - } - parent.add(item); - } - for (const [key, val] of unknowns) { - console.warn(`- Unknown documentation kind "${key}" - \n${JSON.stringify(val)}\n`); - } - } - - serialize() { - const meta = { - version: GEN_VERSION, - date: Date.now(), - }; - const serialized = { - meta, - classes: Array.from(this.classes.values()).map(c => c.serialize()), - interfaces: Array.from(this.interfaces.values()).map(i => i.serialize()), - typedefs: Array.from(this.typedefs.values()).map(t => t.serialize()), - custom: this.custom, - }; - return serialized; - } -} - -module.exports = Documentation; diff --git a/docs/generator/index.js b/docs/generator/index.js deleted file mode 100644 index ce8e06b6d..000000000 --- a/docs/generator/index.js +++ /dev/null @@ -1,33 +0,0 @@ -#!/usr/bin/env node -/* eslint-disable no-console */ -const fs = require('fs'); -const jsdoc2md = require('jsdoc-to-markdown'); -const Documentation = require('./documentation'); -const custom = require('../custom/index'); -const config = require('./config'); - -process.on('unhandledRejection', console.error); - -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 (config.compress) { - console.log('Compressing...'); - output = require('zlib').deflateSync(output).toString('utf8'); - } - - if (!process.argv.slice(2).includes('test')) { - console.log('Writing to docs.json...'); - fs.writeFileSync('./docs/docs.json', output); - } - - console.log('Done!'); - process.exit(0); -}).catch(console.error); diff --git a/docs/generator/types/DocumentedClass.js b/docs/generator/types/DocumentedClass.js deleted file mode 100644 index 9f321b5fb..000000000 --- a/docs/generator/types/DocumentedClass.js +++ /dev/null @@ -1,80 +0,0 @@ -const DocumentedItem = require('./DocumentedItem'); -const DocumentedItemMeta = require('./DocumentedItemMeta'); -const DocumentedConstructor = require('./DocumentedConstructor'); -const DocumentedFunction = require('./DocumentedFunction'); -const DocumentedMember = require('./DocumentedMember'); -const DocumentedEvent = require('./DocumentedEvent'); - -/* -{ id: 'VoiceChannel', - longname: 'VoiceChannel', - name: 'VoiceChannel', - scope: 'global', - kind: 'class', - augments: [ 'GuildChannel' ], - description: 'Represents a Server Voice Channel on Discord.', - meta: - { lineno: 7, - filename: 'VoiceChannel.js', - path: 'src/structures' }, - order: 232 } - */ - -class DocumentedClass extends DocumentedItem { - constructor(docParent, data) { - super(docParent, data); - this.props = new Map(); - this.methods = new Map(); - this.events = new Map(); - } - - add(item) { - if (item instanceof DocumentedConstructor) { - if (this.classConstructor) { - throw new Error(`Doc ${this.directData.name} already has constructor - ${this.directData.classConstructor}`); - } - this.classConstructor = item; - } else if (item instanceof DocumentedFunction) { - if (this.methods.get(item.directData.name)) { - throw new Error(`Doc ${this.directData.name} already has method ${item.directData.name}`); - } - this.methods.set(item.directData.name, item); - } else if (item instanceof DocumentedMember) { - if (this.props.get(item.directData.name)) { - throw new Error(`Doc ${this.directData.name} already has prop ${item.directData.name}`); - } - this.props.set(item.directData.name, item); - } else if (item instanceof DocumentedEvent) { - if (this.events.get(item.directData.name)) { - throw new Error(`Doc ${this.directData.name} already has event ${item.directData.name}`); - } - this.events.set(item.directData.name, item); - } - } - - registerMetaInfo(data) { - super.registerMetaInfo(data); - this.directData = data; - this.directData.meta = new DocumentedItemMeta(this, data.meta); - } - - serialize() { - super.serialize(); - const { id, name, description, meta, augments, access } = this.directData; - const serialized = { - id, - name, - description, - meta: meta.serialize(), - extends: augments, - access, - }; - if (this.classConstructor) serialized.classConstructor = this.classConstructor.serialize(); - serialized.methods = Array.from(this.methods.values()).map(m => m.serialize()); - serialized.properties = Array.from(this.props.values()).map(p => p.serialize()); - serialized.events = Array.from(this.events.values()).map(e => e.serialize()); - return serialized; - } -} - -module.exports = DocumentedClass; diff --git a/docs/generator/types/DocumentedConstructor.js b/docs/generator/types/DocumentedConstructor.js deleted file mode 100644 index 06b21d6b0..000000000 --- a/docs/generator/types/DocumentedConstructor.js +++ /dev/null @@ -1,42 +0,0 @@ -const DocumentedItem = require('./DocumentedItem'); -const DocumentedParam = require('./DocumentedParam'); - -/* -{ id: 'Client()', - longname: 'Client', - name: 'Client', - kind: 'constructor', - description: 'Creates an instance of Client.', - memberof: 'Client', - params: - [ { type: [Object], - optional: true, - description: 'options to pass to the client', - name: 'options' } ], - order: 10 } -*/ - -class DocumentedConstructor extends DocumentedItem { - registerMetaInfo(data) { - super.registerMetaInfo(data); - this.directData = data; - const newParams = []; - for (const param of data.params) newParams.push(new DocumentedParam(this, param)); - this.directData.params = newParams; - } - - serialize() { - super.serialize(); - const { id, name, description, memberof, access, params } = this.directData; - return { - id, - name, - description, - memberof, - access, - params: params.map(p => p.serialize()), - }; - } -} - -module.exports = DocumentedConstructor; diff --git a/docs/generator/types/DocumentedEvent.js b/docs/generator/types/DocumentedEvent.js deleted file mode 100644 index 52791980d..000000000 --- a/docs/generator/types/DocumentedEvent.js +++ /dev/null @@ -1,76 +0,0 @@ -const DocumentedItem = require('./DocumentedItem'); -const DocumentedItemMeta = require('./DocumentedItemMeta'); -const DocumentedParam = require('./DocumentedParam'); - -/* -{ - "id":"Client#event:guildMemberRolesUpdate", - "longname":"Client#event:guildMemberRolesUpdate", - "name":"guildMemberRolesUpdate", - "scope":"instance", - "kind":"event", - "description":"Emitted whenever a Guild Member's Roles change - i.e. new role or removed role", - "memberof":"Client", - "params":[ - { - "type":{ - "names":[ - "Guild" - ] - }, - "description":"the guild that the update affects", - "name":"guild" - }, - { - "type":{ - "names":[ - "Array." - ] - }, - "description":"the roles before the update", - "name":"oldRoles" - }, - { - "type":{ - "names":[ - "Guild" - ] - }, - "description":"the roles after the update", - "name":"newRoles" - } - ], - "meta":{ - "lineno":91, - "filename":"Guild.js", - "path":"src/structures" - }, - "order":110 -} -*/ - -class DocumentedEvent extends DocumentedItem { - registerMetaInfo(data) { - this.directData = data; - this.directData.meta = new DocumentedItemMeta(this, data.meta); - const newParams = []; - data.params = data.params || []; - for (const param of data.params) newParams.push(new DocumentedParam(this, param)); - this.directData.params = newParams; - } - - serialize() { - super.serialize(); - const { id, name, description, memberof, meta, params } = this.directData; - return { - id, - name, - description, - memberof, - meta: meta.serialize(), - params: params.map(p => p.serialize()), - }; - } -} - -module.exports = DocumentedEvent; diff --git a/docs/generator/types/DocumentedFunction.js b/docs/generator/types/DocumentedFunction.js deleted file mode 100644 index 04ba6760d..000000000 --- a/docs/generator/types/DocumentedFunction.js +++ /dev/null @@ -1,88 +0,0 @@ -const DocumentedItem = require('./DocumentedItem'); -const DocumentedItemMeta = require('./DocumentedItemMeta'); -const DocumentedVarType = require('./DocumentedVarType'); -const DocumentedParam = require('./DocumentedParam'); - -/* -{ - "id":"ClientUser#sendTTSMessage", - "longname":"ClientUser#sendTTSMessage", - "name":"sendTTSMessage", - "scope":"instance", - "kind":"function", - "inherits":"User#sendTTSMessage", - "inherited":true, - "implements":[ - "TextBasedChannel#sendTTSMessage" - ], - "description":"Send a text-to-speech message to this channel", - "memberof":"ClientUser", - "params":[ - { - "type":{ - "names":[ - "String" - ] - }, - "description":"the content to send", - "name":"content" - } - ], - "examples":[ - "// send a TTS message..." - ], - "returns":[ - { - "type":{ - "names":[ - "Promise." - ] - } - } - ], - "meta":{ - "lineno":38, - "filename":"TextBasedChannel.js", - "path":src/structures/interface" - }, - "order":293 -} - */ - -class DocumentedFunction extends DocumentedItem { - registerMetaInfo(data) { - super.registerMetaInfo(data); - this.directData = data; - this.directData.meta = new DocumentedItemMeta(this, data.meta); - this.directData.returns = new DocumentedVarType(this, data.returns ? data.returns[0].type : { - names: ['void'], - }); - const newParams = []; - for (const param of data.params) newParams.push(new DocumentedParam(this, param)); - this.directData.params = newParams; - } - - serialize() { - super.serialize(); - const { - id, name, description, memberof, examples, inherits, inherited, meta, returns, params, access, - } = this.directData; - const serialized = { - id, - access, - name, - description, - memberof, - examples, - inherits, - inherited, - meta: meta.serialize(), - returns: returns.serialize(), - params: params.map(p => p.serialize()), - }; - serialized.implements = this.directData.implements; - return serialized; - } -} - -module.exports = DocumentedFunction; diff --git a/docs/generator/types/DocumentedInterface.js b/docs/generator/types/DocumentedInterface.js deleted file mode 100644 index ce2905785..000000000 --- a/docs/generator/types/DocumentedInterface.js +++ /dev/null @@ -1,32 +0,0 @@ -const DocumentedClass = require('./DocumentedClass'); - -/* -{ id: 'TextBasedChannel', - longname: 'TextBasedChannel', - name: 'TextBasedChannel', - scope: 'global', - kind: 'interface', - classdesc: 'Interface for classes that have text-channel-like features', - params: [], - meta: - { lineno: 5, - filename: 'TextBasedChannel.js', - path: 'src/structures/interface' }, - order: 175 } - */ - -class DocumentedInterface extends DocumentedClass { - registerMetaInfo(data) { - super.registerMetaInfo(data); - this.directData = data; - // this.directData.meta = new DocumentedItemMeta(this, data.meta); - } - - serialize() { - const serialized = super.serialize(); - serialized.description = this.directData.classdesc; - return serialized; - } -} - -module.exports = DocumentedInterface; diff --git a/docs/generator/types/DocumentedItem.js b/docs/generator/types/DocumentedItem.js deleted file mode 100644 index 562c706d3..000000000 --- a/docs/generator/types/DocumentedItem.js +++ /dev/null @@ -1,17 +0,0 @@ -class DocumentedItem { - constructor(parent, info) { - this.parent = parent; - this.directData = {}; - this.registerMetaInfo(info); - } - - registerMetaInfo() { - return; - } - - serialize() { - return; - } -} - -module.exports = DocumentedItem; diff --git a/docs/generator/types/DocumentedItemMeta.js b/docs/generator/types/DocumentedItemMeta.js deleted file mode 100644 index 3bc6fbae1..000000000 --- a/docs/generator/types/DocumentedItemMeta.js +++ /dev/null @@ -1,27 +0,0 @@ -const DocumentedItem = require('./DocumentedItem'); - -const cwd = `${process.cwd()}\\`.replace(/\\/g, '/'); -const backToForward = /\\/g; - -/* - { lineno: 7, - filename: 'VoiceChannel.js', - path: 'src/structures' }, -*/ - -class DocumentedItemMeta extends DocumentedItem { - registerMetaInfo(data) { - super.registerMetaInfo(data); - this.directData.line = data.lineno; - this.directData.file = data.filename; - this.directData.path = data.path.replace(backToForward, '/').replace(cwd, ''); - } - - serialize() { - super.serialize(); - const { line, file, path } = this.directData; - return { line, file, path }; - } -} - -module.exports = DocumentedItemMeta; diff --git a/docs/generator/types/DocumentedMember.js b/docs/generator/types/DocumentedMember.js deleted file mode 100644 index 5b66e7b65..000000000 --- a/docs/generator/types/DocumentedMember.js +++ /dev/null @@ -1,56 +0,0 @@ -const DocumentedItem = require('./DocumentedItem'); -const DocumentedItemMeta = require('./DocumentedItemMeta'); -const DocumentedVarType = require('./DocumentedVarType'); -const DocumentedParam = require('./DocumentedParam'); - -/* -{ id: 'Client#rest', - longname: 'Client#rest', - name: 'rest', - scope: 'instance', - kind: 'member', - description: 'The REST manager of the client', - memberof: 'Client', - type: { names: [ 'RESTManager' ] }, - access: 'private', - meta: - { lineno: 32, - filename: 'Client.js', - path: 'src/client' }, - order: 11 } -*/ - -class DocumentedMember extends DocumentedItem { - registerMetaInfo(data) { - super.registerMetaInfo(data); - this.directData = data; - this.directData.meta = new DocumentedItemMeta(this, data.meta); - this.directData.type = new DocumentedVarType(this, data.type); - if (data.properties) { - const newProps = []; - for (const param of data.properties) { - newProps.push(new DocumentedParam(this, param)); - } - this.directData.properties = newProps; - } else { - data.properties = []; - } - } - - serialize() { - super.serialize(); - const { id, name, description, memberof, type, access, meta, properties } = this.directData; - return { - id, - name, - description, - memberof, - type: type.serialize(), - access, - meta: meta.serialize(), - props: properties.map(p => p.serialize()), - }; - } -} - -module.exports = DocumentedMember; diff --git a/docs/generator/types/DocumentedParam.js b/docs/generator/types/DocumentedParam.js deleted file mode 100644 index d869078d4..000000000 --- a/docs/generator/types/DocumentedParam.js +++ /dev/null @@ -1,36 +0,0 @@ -const DocumentedItem = require('./DocumentedItem'); -const DocumentedVarType = require('./DocumentedVarType'); - -/* -{ - "type":{ - "names":[ - "Guild" - ] - }, - "description":"the roles after the update", - "name":"newRoles" - } -*/ - -class DocumentedParam extends DocumentedItem { - registerMetaInfo(data) { - super.registerMetaInfo(data); - this.directData = data; - this.directData.type = new DocumentedVarType(this, data.type); - } - - serialize() { - super.serialize(); - const { name, description, type, optional, defaultvalue } = this.directData; - return { - name, - description, - optional, - default: defaultvalue, - type: type.serialize(), - }; - } -} - -module.exports = DocumentedParam; diff --git a/docs/generator/types/DocumentedTypeDef.js b/docs/generator/types/DocumentedTypeDef.js deleted file mode 100644 index 0571868ec..000000000 --- a/docs/generator/types/DocumentedTypeDef.js +++ /dev/null @@ -1,48 +0,0 @@ -const DocumentedItem = require('./DocumentedItem'); -const DocumentedItemMeta = require('./DocumentedItemMeta'); -const DocumentedVarType = require('./DocumentedVarType'); -const DocumentedParam = require('./DocumentedParam'); - -/* -{ id: 'StringResolvable', - longname: 'StringResolvable', - name: 'StringResolvable', - scope: 'global', - kind: 'typedef', - description: 'Data that can be resolved to give a String...', - type: { names: [ 'String', 'Array', 'Object' ] }, - meta: - { lineno: 142, - filename: 'ClientDataResolver.js', - path: 'src/client' }, - order: 37 } -*/ - -class DocumentedTypeDef extends DocumentedItem { - registerMetaInfo(data) { - super.registerMetaInfo(data); - this.props = new Map(); - this.directData = data; - this.directData.meta = new DocumentedItemMeta(this, data.meta); - this.directData.type = new DocumentedVarType(this, data.type); - data.properties = data.properties || []; - for (const prop of data.properties) this.props.set(prop.name, new DocumentedParam(this, prop)); - } - - serialize() { - super.serialize(); - const { id, name, description, type, access, meta } = this.directData; - const serialized = { - id, - name, - description, - type: type.serialize(), - access, - meta: meta.serialize(), - }; - serialized.properties = Array.from(this.props.values()).map(p => p.serialize()); - return serialized; - } -} - -module.exports = DocumentedTypeDef; diff --git a/docs/generator/types/DocumentedVarType.js b/docs/generator/types/DocumentedVarType.js deleted file mode 100644 index fcbb1b548..000000000 --- a/docs/generator/types/DocumentedVarType.js +++ /dev/null @@ -1,45 +0,0 @@ -const DocumentedItem = require('./DocumentedItem'); - -/* -{ - "names":[ - "String" - ] -} -*/ - -const regex = /([\w]+)([^\w]+)/; -const regexG = /([\w]+)([^\w]+)/g; - -class DocumentedVarType extends DocumentedItem { - registerMetaInfo(data) { - super.registerMetaInfo(data); - this.directData = data; - } - - serialize() { - super.serialize(); - const names = []; - for (const name of this.directData.names) names.push(splitVarName(name)); - return { - types: names, - }; - } -} - -function splitVarName(str) { - if (str === '*') return ['*', '']; - const matches = str.match(regexG); - const output = []; - if (matches) { - for (const match of matches) { - const groups = match.match(regex); - output.push([groups[1], groups[2]]); - } - } else { - output.push([str.match(/(\w+)/g)[0], '']); - } - return output; -} - -module.exports = DocumentedVarType; diff --git a/package.json b/package.json index f4fd7046a..c5e4c2d1c 100644 --- a/package.json +++ b/package.json @@ -4,9 +4,9 @@ "description": "A powerful library for interacting with the Discord API", "main": "./src/index", "scripts": { - "test": "eslint src && node docs/generator test", - "docs": "node docs/generator", - "test-docs": "node docs/generator test", + "test": "eslint src && docgen --source src --custom docs", + "docs": "docgen --source src --custom docs --output docs/docs.json", + "test-docs": "docgen --source src --custom docs", "lint": "eslint src", "web-dist": "node ./node_modules/parallel-webpack/bin/run.js" }, @@ -39,6 +39,7 @@ }, "devDependencies": { "bufferutil": "^1.2.1", + "discord.js-docgen": "github:Gawdl3y/discord.js-docgen", "eslint": "^3.10.0", "jsdoc-to-markdown": "^2.0.0", "json-loader": "^0.5.4",