[docs] Document TypeReaders, Events, and Joining Audio

docs/guides/commands.md

@@ -59,4 +59,43 @@ In the constructor of your module, any parameters will be filled in by the @Disc
 >[!NOTE]
 >If you accept `CommandService` or `IDependencyMap`  as a parameter in your constructor, these parameters will be filled by the CommandService the module was loaded from, and the DependencyMap passed into it, respectively. 
 
-[!code-csharp[DependencyMap in Modules](samples/dependency_module.cs)]
+[!code-csharp[DependencyMap in Modules](samples/dependency_module.cs)]
+
+## Type Readers
+
+Type Readers allow you to parse different types of arguments in your commands.
+
+By default, the following Types are supported arguments:
+
+- string
+- sbyte/byte
+- ushort/short
+- uint/int
+- ulong/long
+- float, double, decimal
+- DateTime/DateTimeOffset
+- IUser/IGuildUser
+- IChannel/IGuildChannel/ITextChannel/IVoiceChannel/IGroupChannel
+- IRole
+- IMessage
+
+### Creating a Type Readers
+
+To create a TypeReader, create a new class that imports @Discord and @Discord.Commands . Ensure your class inherits from @Discord.Commands.TypeReader
+
+Next, satisfy the `TypeReader` class by overriding `Task<TypeReaderResult> Read(IMessage context, string input)`.
+
+>[!NOTE]
+>In many cases, Visual Stuido can fill this in for you, using the "Implement Abstract Class" IntelliSense hint.
+
+Inside this task, add whatever logic you need to parse the input string.
+
+Finally, return a `TypeReaderResult`. If you were able to successfully parse the input, return `TypeReaderResult.FromSuccess(parsedInput)`. Otherwise, return `TypeReaderResult.FromError`.
+
+#### Sample
+
+[!code-csharp[TypeReaders](samples/typereader.cs)]
+
+### Installing TypeReaders
+
+TypeReaders are not automatically discovered by the Command Service, and must be explicitly added. To install a TypeReader, invoke [CommandService.AddTypeReader](xref:Discord.Commands.CommandService#Discord_Commands_CommandService_AddTypeReader__1_Discord_Commands_TypeReader_).

docs/guides/events.md

@@ -0,0 +1,28 @@
+---
+title: Events
+---
+
+# Events
+
+Messages from Discord are exposed via events, and follow a pattern of `Func<[event params], Task>`, which allows you to easily create either async or sync event handlers.
+
+To hook into events, you must be using the @Discord.WebSocket.DiscordSocketClient, which provides WebSocket capabilities, necessary for receiving events.
+
+>[!NOTE]
+>The gateway will wait for all registered handlers of an event to finish before raising the next event. As a result of this, it is reccomended that if you need to perform any heavy work in an event handler, it is done on its own thread or Task.
+
+**For further documentation of all events**, it is reccomended to look at the [Events Section](xref:Discord.WebSocket.DiscordSocketClient#events) on the API documentation of @Discord.WebSocket.DiscordSocketClient
+
+## Connection State
+
+Connection Events will be raised when the Connection State of your client changes.
+
+[DiscordSocketClient.Connected](xref:Discord.WebSocket.DiscordSocketClient#Discord_WebSocket_DiscordSocketClient_Connected) and [Disconnected](Discord_WebSocket_DiscordSocketClient_Disconnected) are raised when the Gateway Socket connects or disconnects, respectively.
+
+>[!WARNING]
+>You should not use DiscordClient.Connected to run code when your client first connects to Discord. The client has not received and parsed the READY event and guild stream yet, and will have an incomplete or empty cache.
+
+[DiscordSocketClient.Ready](xref:Discord.WebSocket.DiscordSocketClient#Discord_WebSocket_DiscordSocketClient_Ready) is raised when the `READY` packet is parsed and received from Discord.
+
+>[!NOTE]
+>The [DiscordSocketClient.ConnectAsync](xref:Discord.WebSocket.DiscordSocketClient#Discord_WebSocket_DiscordSocketClient_ConnectAsync_System_Boolean_) method will not return until the READY packet has been processed. By default, it also will not return until the guild stream has finished. This means it is safe to run bot code directly after awaiting the ConnectAsync method.

docs/guides/samples/joining_audio.cs

@@ -0,0 +1,15 @@
+// Create an IAudioClient, and store it for later use
+private IAudioClient _audio;
+
+// Create a Join command, that will join the parameter or the user's current voice channel
+[Command("join")]
+public async Task JoinChannel(IMessage msg,
+    IVoiceChannel channel = null)
+{
+    // Get the audio channel
+    channel = channel ?? (msg.Author as IGuildUser)?.VoiceChannel;
+    if (channel == null) { await msg.Channel.SendMessageAsync("User must be in a voice channel, or a voice channel must be passed as an argument."); return; }
+
+    // Get the IAudioClient by calling the JoinAsync method
+    _audio = await channel.JoinAsync();
+}

docs/guides/samples/typereader.cs

@@ -0,0 +1,14 @@
+using Discord;
+using Discord.Commands;
+
+public class BooleanTypeReader : TypeReader
+{
+    public override Task<TypeReaderResult> Read(IMessage context, string input)
+    {
+        bool result;
+        if (bool.TryParse(input, out result))
+            return Task.FromResult(TypeReaderResult.FromSuccess(result));
+        
+        return Task.FromResult(TypeReaderResult.FromError(CommandError.ParseFailed, "Input could not be parsed as a boolean."))
+    }
+}

docs/guides/toc.yml

@@ -7,5 +7,9 @@
   href: logging.md
 - name: Commands
   href: commands.md
+- name: Voice
+  href: voice.md
+- name: Events
+  href: events.md
 - name: Code Samples
   href: samples.md

docs/guides/voice.md

@@ -0,0 +1,28 @@
+# Voice
+
+**Information on this page is subject to change!**
+
+>[!WARNING]
+>Audio in 1.0 is incomplete. Most of the below documentation is untested.
+
+## Installation
+
+To use Audio, you must first configure your `DiscordSocketClient` with Audio support.
+
+In your @Discord.DiscordSocketConfig, set `AudioMode` to the appropriate @Discord.Audio.AudioMode for your bot. For most bots, you will only need to use `AudioMode.Outgoing`.
+
+### Dependencies
+
+Audio requires two native libraries, `libsodium` and `opus`. Both of these libraries must be placed in the runtime directory of your bot (for .NET 4.6, the directory where your exe is located; for .NET core, directory where your project.json is located) 
+
+For Windows Users, precompiled binaries are available for your convienence [here](https://discord.foxbot.me/binaries/)
+
+For Linux Users, you will need to compile from source. [Sodium Source Code](https://download.libsodium.org/libsodium/releases/), [Opus Source Code](http://downloads.xiph.org/releases/opus/).
+
+## Joining a Channel
+
+Joining Voice Channels is relatively straight-forward, and is a requirement for sending or receiving audio. This will also allow us to create an @Discord.Audio.IAudioClient, which will be used later to send or receive audio.
+
+[!code-csharp[Joining a Channel](samples/joining_audio.cs)]
+
+The client will sustain a connection to this channel until it is kicked, disconnected from Discord, or told to disconnect.