docs(WIP): Bring the main doc pages up to date, and add more examples (#2094)

* Bring some docs up to date, as well as add a new example

* Missed an exclamation mark

* Do requested changes

* Do suggestions

* Same suggestions for the other examples

* Show people that they can also use reply with embeds

* Typos in embed.js example

* Remove object example from embeds, too complex
Suggested by Yukine

* Some changes, some requested changes

* Add moderation examples!

* Add attachment examples

* Missing dot

* Fix spacing

* Requested Changes

* Quote consistency

* Tfw you break the syntax

docs/examples/attachments.md

@@ -0,0 +1,163 @@
+# Sending Attachments
+
+In here you'll see a few examples showing how you can send an attachment using discord.js.
+
+## Sending an attachment using a URL
+
+There are a few ways you can do this, but we'll show you the easiest.
+
+The following examples use [MessageAttachment](/#/docs/main/master/class/MessageAttachment).
+
+```js
+// Extract the required classes from the discord.js module
+const { Client, MessageAttachment } = require('discord.js');
+
+// Create an instance of a Discord client
+const client = new Client();
+
+/**
+ * The ready event is vital, it means that only _after_ this will your bot start reacting to information
+ * received from Discord
+ */
+client.on('ready', () => {
+  console.log('I am ready!');
+});
+
+client.on('message', message => {
+	// If the message is '!rip'
+	if (message.content === '!rip') {
+		// Create the attachment using MessageAttachment
+		const attachment = new MessageAttachment('https://i.imgur.com/w3duR07.png');
+		// Send the attachment in the message channel
+		message.channel.send(attachment);
+	}
+});
+
+// Log our bot in using the token from https://discordapp.com/developers/applications/me
+client.login('your token here');
+```
+
+And here is the result:
+
+![Image showing the result](/static/attachment-example1.png)
+
+But what if you want to send an attachment with a message content? Fear not, for it is easy to do that too! We'll recommend reading [the TextChannel's "send" function documentation](/#/docs/main/master/class/TextChannel?scrollTo=send) to see what other options are available.
+
+```js
+// Extract the required classes from the discord.js module
+const { Client, MessageAttachment } = require('discord.js');
+
+// Create an instance of a Discord client
+const client = new Client();
+
+/**
+ * The ready event is vital, it means that only _after_ this will your bot start reacting to information
+ * received from Discord
+ */
+client.on('ready', () => {
+  console.log('I am ready!');
+});
+
+client.on('message', message => {
+	// If the message is '!rip'
+	if (message.content === '!rip') {
+		// Create the attachment using MessageAttachment
+		const attachment = new MessageAttachment('https://i.imgur.com/w3duR07.png');
+		// Send the attachment in the message channel with a content
+		message.channel.send(`${message.author},`, attachment);
+	}
+});
+
+// Log our bot in using the token from https://discordapp.com/developers/applications/me
+client.login('your token here');
+```
+
+And here's the result of this one:
+
+![Image showing the result](/static/attachment-example2.png)
+
+## Sending a local file or buffer
+
+Sending a local file isn't hard either! We'll be using [MessageAttachment](/#/docs/main/master/class/MessageAttachment) for these examples too.
+
+```js
+// Extract the required classes from the discord.js module
+const { Client, MessageAttachment } = require('discord.js');
+
+// Create an instance of a Discord client
+const client = new Client();
+
+/**
+ * The ready event is vital, it means that only _after_ this will your bot start reacting to information
+ * received from Discord
+ */
+client.on('ready', () => {
+  console.log('I am ready!');
+});
+
+client.on('message', message => {
+	// If the message is '!rip'
+	if (message.content === '!rip') {
+		// Create the attachment using MessageAttachment
+		const attachment = new MessageAttachment('./rip.png');
+		// Send the attachment in the message channel with a content
+		message.channel.send(`${message.author},`, attachment);
+	}
+});
+
+// Log our bot in using the token from https://discordapp.com/developers/applications/me
+client.login('your token here');
+```
+
+The results are the same as the URL examples:
+
+![Image showing result](/static/attachment-example1.png)
+
+But what if you have a buffer from an image? Or a text document? Well, it's the same as sending a local file or a URL!
+
+In the following example, we'll be getting the buffer from a `memes.txt` file, and send it in the message channel.
+You can use any buffer you want, and send it. Just make sure to overwrite the filename if it isn't an image!
+
+```js
+// Extract the required classes from the discord.js module
+const { Client, MessageAttachment } = require('discord.js');
+
+// Import the native fs module
+const fs = require('fs');
+
+// Create an instance of a Discord client
+const client = new Client();
+
+/**
+ * The ready event is vital, it means that only _after_ this will your bot start reacting to information
+ * received from Discord
+ */
+client.on('ready', () => {
+  console.log('I am ready!');
+});
+
+client.on('message', message => {
+	// If the message is '!memes'
+	if (message.content === '!memes') {
+		// Get the buffer from the 'memes.txt', assuming that the file exists
+		const buffer = fs.readFileSync('./memes.txt');
+
+		/**
+		 * Create the attachment using MessageAttachment,
+		 * overwritting the default file name to 'memes.txt'
+		 * Read more about it over at
+		 * http://discord.js.org/#/docs/main/master/class/MessageAttachment
+		 */
+		const attachment = new MessageAttachment(buffer, 'memes.txt');
+		// Send the attachment in the message channel with a content
+		message.channel.send(`${message.author}, here are your memes!`, attachment);
+	}
+});
+
+// Log our bot in using the token from https://discordapp.com/developers/applications/me
+client.login('your token here');
+```
+
+And of course, the results are:
+
+![Attachment File example 3](/static/attachment-example3.png)

docs/examples/avatars.js

@@ -1,6 +1,6 @@
-/*
+/**
-  Send a user a link to their avatar
+ * Send a user a link to their avatar
-*/
+ */
 
 // Import the discord.js module
 const Discord = require('discord.js');
@@ -8,11 +8,10 @@ const Discord = require('discord.js');
 // Create an instance of a Discord client
 const client = new Discord.Client();
 
-// The token of your bot - https://discordapp.com/developers/applications/me
+/**
-const token = 'your bot token here';
+ * The ready event is vital, it means that only _after_ this will your bot start reacting to information
-
+ * received from Discord
-// The ready event is vital, it means that your bot will only start reacting to information
+ */
-// from Discord _after_ ready is emitted
 client.on('ready', () => {
   console.log('I am ready!');
 });
@@ -26,5 +25,5 @@ client.on('message', message => {
   }
 });
 
-// Log our bot in
+// Log our bot in using the token from https://discordapp.com/developers/applications/me
-client.login(token);
+client.login('your token here');

docs/examples/embed.js

@@ -0,0 +1,38 @@
+/**
+ * An example of how you can send embeds
+ */
+
+// Extract the required classes from the discord.js module
+const { Client, MessageEmbed } = require('discord.js');
+
+// Create an instance of a Discord client
+const client = new Client();
+
+/**
+ * The ready event is vital, it means that only _after_ this will your bot start reacting to information
+ * received from Discord
+ */
+client.on('ready', () => {
+  console.log('I am ready!');
+});
+
+client.on('message', message => {
+  // If the message is "how to embed"
+  if (message.content === 'how to embed') {
+    // We can create embeds using the MessageEmbed constructor
+    // Read more about all that you can do with the constructor
+    // over at https://discord.js.org/#/docs/main/master/class/MessageEmbed
+    const embed = new MessageEmbed()
+      // Set the title of the field
+      .setTitle('A slick little embed')
+      // Set the color of the embed
+      .setColor(0xFF0000)
+      // Set the main content of the embed
+      .setDescription('Hello, this is a slick embed!');
+    // Send the embed to the same channel as the message
+    message.channel.send(embed);
+  }
+});
+
+// Log our bot in using the token from https://discordapp.com/developers/applications/me
+client.login('your token here');

docs/examples/greeting.js

@@ -1,6 +1,6 @@
-/*
+/**
-  A bot that welcomes new guild members when they join
+ * A bot that welcomes new guild members when they join
-*/
+ */
 
 // Import the discord.js module
 const Discord = require('discord.js');
@@ -8,11 +8,10 @@ const Discord = require('discord.js');
 // Create an instance of a Discord client
 const client = new Discord.Client();
 
-// The token of your bot - https://discordapp.com/developers/applications/me
+/**
-const token = 'your bot token here';
+ * The ready event is vital, it means that only _after_ this will your bot start reacting to information
-
+ * received from Discord
-// The ready event is vital, it means that your bot will only start reacting to information
+ */
-// from Discord _after_ ready is emitted
 client.on('ready', () => {
   console.log('I am ready!');
 });
@@ -27,5 +26,5 @@ client.on('guildMemberAdd', member => {
   channel.send(`Welcome to the server, ${member}`);
 });
 
-// Log our bot in
+// Log our bot in using the token from https://discordapp.com/developers/applications/me
-client.login(token);
+client.login('your token here');

docs/examples/moderation.md

@@ -0,0 +1,145 @@
+# Moderation
+
+In here, you'll see some basic examples for kicking and banning a member.
+
+## Kicking a member
+
+Let's say you have a member that you'd like to kick. Here is an example of how you *can* do it.
+
+```js
+// Import the discord.js module
+const Discord = require('discord.js');
+
+// Create an instance of a Discord client
+const client = new Discord.Client();
+
+/**
+ * The ready event is vital, it means that only _after_ this will your bot start reacting to information
+ * received from Discord
+ */
+client.on('ready', () => {
+  console.log('I am ready!');
+});
+
+client.on('message', message => {
+  // Ignore messages that aren't from a guild
+  if (!message.guild) return;
+
+  // If the message content starts with "!kick"
+  if (message.content.startsWith('!kick')) {
+    // Assuming we mention someone in the message, this will return the user
+    // Read more about mentions over at https://discord.js.org/#/docs/main/master/class/MessageMentions
+    const user = message.mentions.users.first();
+    // If we have a user mentioned
+    if (user) {
+      // Now we get the member from the user
+      const member = message.guild.member(user);
+      // If the member is in the guild
+      if (member) {
+        /**
+         * Kick the member
+         * Make sure you run this on a member, not a user!
+         * There are big differences between a user and a member
+         */
+        member.kick('Optional reason that will display in the audit logs').then(() => {
+          // We let the message author know we were able to kick the person
+          message.reply(`Successfully kicked ${user.tag}`);
+        }).catch(err => {
+          // An error happened
+          // This is generally due to the bot not being able to kick the member,
+          // either due to missing permissions or role hierarchy
+          message.reply('I was unable to kick the member');
+          // Log the error
+          console.error(err);
+        });
+      } else {
+        // The mentioned user isn't in this guild
+        message.reply('That user isn\'t in this guild!');
+      }
+    // Otherwise, if no user was mentioned
+    } else {
+      message.reply('You didn\'t mention the user to kick!');
+    }
+  }
+});
+
+// Log our bot in using the token from https://discordapp.com/developers/applications/me
+client.login('your token here');
+```
+
+And the result is:
+
+![Image showing the result](/static/kick-example.png)
+
+## Banning a member
+
+Banning works the same way as kicking, but it has slightly more options that can be changed.
+
+```js
+// Import the discord.js module
+const Discord = require('discord.js');
+
+// Create an instance of a Discord client
+const client = new Discord.Client();
+
+/**
+ * The ready event is vital, it means that only _after_ this will your bot start reacting to information
+ * received from Discord
+ */
+client.on('ready', () => {
+  console.log('I am ready!');
+});
+
+client.on('message', message => {
+  // Ignore messages that aren't from a guild
+  if (!message.guild) return;
+
+  // if the message content starts with "!ban"
+  if (message.content.startsWith('!ban')) {
+    // Assuming we mention someone in the message, this will return the user
+    // Read more about mentions over at https://discord.js.org/#/docs/main/master/class/MessageMentions
+    const user = message.mentions.users.first();
+    // If we have a user mentioned
+    if (user) {
+      // Now we get the member from the user
+      const member = message.guild.member(user);
+      // If the member is in the guild
+      if (member) {
+        /**
+         * Ban the member
+         * Make sure you run this on a member, not a user!
+         * There are big differences between a user and a member
+         * Read more about what ban options there are over at
+         * https://discord.js.org/#/docs/main/master/class/GuildMember?scrollTo=ban
+         */
+        member.ban({
+          reason: 'They were bad!',
+        }).then(() => {
+          // We let the message author know we were able to ban the person
+          message.reply(`Successfully banned ${user.tag}`);
+        }).catch(err => {
+          // An error happened
+          // This is generally due to the bot not being able to ban the member,
+          // either due to missing permissions or role hierarchy
+          message.reply('I was unable to ban the member');
+          // Log the error
+          console.error(err);
+        });
+      } else {
+        // The mentioned user isn't in this guild
+        message.reply('That user isn\'t in this guild!');
+      }
+    } else {
+    // Otherwise, if no user was mentioned
+      message.reply('You didn\'t mention the user to ban!');
+    }
+  }
+});
+
+// Log our bot in using the token from https://discordapp.com/developers/applications/me
+client.login('your token here');
+```
+
+And the result is:
+
+![Image showing the result](/static/ban-example.png)

docs/examples/ping.js

@@ -1,6 +1,6 @@
-/*
+/**
-  A ping pong bot, whenever you send "ping", it replies "pong".
+ * A ping pong bot, whenever you send "ping", it replies "pong".
-*/
+ */
 
 // Import the discord.js module
 const Discord = require('discord.js');
@@ -8,11 +8,10 @@ const Discord = require('discord.js');
 // Create an instance of a Discord client
 const client = new Discord.Client();
 
-// The token of your bot - https://discordapp.com/developers/applications/me
+/**
-const token = 'your bot token here';
+ * The ready event is vital, it means that only _after_ this will your bot start reacting to information
-
+ * received from Discord
-// The ready event is vital, it means that your bot will only start reacting to information
+ */
-// from Discord _after_ ready is emitted
 client.on('ready', () => {
   console.log('I am ready!');
 });
@@ -26,5 +25,5 @@ client.on('message', message => {
   }
 });
 
-// Log our bot in
+// Log our bot in using the token from https://discordapp.com/developers/applications/me
-client.login(token);
+client.login('your token here');

docs/examples/webhook.js

@@ -1,6 +1,6 @@
-/*
+/**
-  Send a message using a webhook
+ * Send a message using a webhook
-*/
+ */
 
 // Import the discord.js module
 const Discord = require('discord.js');

docs/general/faq.md

@@ -12,10 +12,10 @@ Update to Node.js 8.0.0 or newer.
   node-opus is greatly preferred, due to it having significantly better performance.
 
 ## How do I install FFMPEG?
-- **npm:** `npm install --save ffmpeg-binaries`
+- **npm:** `npm install ffmpeg-binaries`
 - **Ubuntu 16.04:** `sudo apt install ffmpeg`
 - **Ubuntu 14.04:** `sudo apt-get install libav-tools`
-- **Windows:** See the [FFMPEG section of AoDude's guide](https://github.com/bdistin/OhGodMusicBot/blob/master/README.md#download-ffmpeg).
+- **Windows:** `npm install ffmpeg-binaries` or see the [FFMPEG section of AoDude's guide](https://github.com/bdistin/OhGodMusicBot/blob/master/README.md#download-ffmpeg).
 
 ## How do I set up node-opus?
 - **Ubuntu:** Simply run `npm install node-opus`, and it's done. Congrats!

docs/general/welcome.md

@@ -10,6 +10,7 @@
     <a href="https://www.npmjs.com/package/discord.js"><img src="https://img.shields.io/npm/dt/discord.js.svg?maxAge=3600" alt="NPM downloads" /></a>
     <a href="https://travis-ci.org/discordjs/discord.js"><img src="https://travis-ci.org/discordjs/discord.js.svg" alt="Build status" /></a>
     <a href="https://david-dm.org/discordjs/discord.js"><img src="https://img.shields.io/david/discordjs/discord.js.svg?maxAge=3600" alt="Dependencies" /></a>
+    <a href="https://www.patreon.com/discordjs"><img src="https://img.shields.io/badge/donate-patreon-F96854.svg" alt="Patreon" /></a>
   </p>
   <p>
     <a href="https://nodei.co/npm/discord.js/"><img src="https://nodei.co/npm/discord.js.png?downloads=true&stars=true" alt="NPM info" /></a>

docs/index.yml

@@ -18,7 +18,13 @@
       path: ping.js
     - name: Avatars
       path: avatars.js
+    - name: Attachments
+      path: attachments.md
     - name: Server greeting
       path: greeting.js
+    - name: Message Embed
+      path: embed.js
+    - name: Moderation
+      path: moderation.md
     - name: Webhook
       path: webhook.js

docs/topics/voice.md

@@ -4,12 +4,16 @@ Voice in discord.js can be used for many things, such as music bots, recording o
 In discord.js, you can use voice by connecting to a `VoiceChannel` to obtain a `VoiceConnection`, where you can start streaming and receiving audio.
 
 To get started, make sure you have:
-* ffmpeg - `npm install ffmpeg-binaries`
+* FFmpeg - `npm install ffmpeg-binaries`
 * an opus encoder, choose one from below:
   * `npm install node-opus` (better performance)
   * `npm install opusscript`
 * a good network connection
 
+The preferred opus 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.
+
 ## Joining a voice channel
 The example below reacts to a message and joins the sender's voice channel, catching any errors. This is important
 as it allows us to obtain a `VoiceConnection` that we can start to stream audio with.
@@ -132,4 +136,4 @@ connection.play(broadcast);
 It's important to note that the `dispatcher` stored above is a `BroadcastDispatcher` - it controls all the dispatcher subscribed to the broadcast, e.g. setting the volume of this dispatcher affects the volume of all subscribers.
 
 ## Voice Receive
-coming soon™
+coming soon™