Revamp docs page on logging

docs/CONTRIBUTING.md

@@ -1,15 +1,45 @@
 # Contributing to Docs
 
-I don't really have any strict conditions for writing documentation, but just keep these few guidelines in mind:
+I don't really have any strict conditions for writing documentation, 
+but just keep these few guidelines in mind:
 
 * Keep code samples in the `guides/samples` folder
-* When referencing an object in the API, link to it's page in the API documentation.
+* When referencing an object in the API, link to it's page in the 
+API documentation.
 * Documentation should be written in clear and proper English*
 
-\* If anyone is interested in translating documentation into other languages, please open an issue or contact me on Discord (`foxbot#0282`).
+\* If anyone is interested in translating documentation into other 
+languages, please open an issue or contact me on 
+Discord (`foxbot#0282`).
+
+### Layout
+
+Documentation should be written in a FAQ/Wiki style format.
+
+Recommended reads:
+
+* http://docs.microsoft.com
+* http://flask.pocoo.org/docs/0.12/
+
+Style consistencies:
+
+* Use a ruler set at 70 characters
+* Links should use long syntax
+
+Example of long link syntax:
+
+```
+Please consult the [API Documentation] for more information.
+
+[API Documentation]: xref:System.String
+```
 
 ### Compiling
 
-Documentation is compiled into a static site using [DocFx](https://dotnet.github.io/docfx/). We currently use version 2.8
+Documentation is compiled into a static site using [DocFx]. 
+We currently use the most recent build off the dev branch.
 
-After making changes, compile your changes into the static site with `docfx`. You can also view your changes live with `docfx --serve`.
+After making changes, compile your changes into the static site with 
+`docfx`. You can also view your changes live with `docfx --serve`.
+
+[DocFx]: https://dotnet.github.io/docfx/

docs/docfx.json

@@ -42,7 +42,8 @@
     "resource": [
       {
         "files": [
-          "images/**"
+          "**/images/**",
+          "**/samples/**"
         ],
         "exclude": [
           "obj/**",

docs/guides/installing.md

@@ -11,7 +11,7 @@ Optionally, you may compile from source and install yourself.
 
 Currently, Discord.Net targets [.NET Standard] 1.3, and offers support for
 .NET Standard 1.1. If your application will be targeting .NET Standard 1.1,
-please see the [additional steps](#installing-on-.net-standard-11).
+please see the [additional steps](#installing-on-net-standard-11).
 
 Since Discord.Net is built on the .NET Standard, it is also recommended to
 create applications using [.NET Core], though you are not required to. When

docs/guides/intro.md

@@ -34,7 +34,9 @@ through the OAuth2 flow.
 
 1. Open your bot's application on the [Discord Applications Portal]
 2. Retrieve the app's **Client ID**.
+
 ![Step 2](images/intro-client-id.png)
+
 3. Create an OAuth2 authorization URL
 `https://discordapp.com/oauth2/authorize?client_id=<CLIENT ID>&scope=bot`
 4. Open the authorization URL in your browser
@@ -45,6 +47,7 @@ Only servers where you have the `MANAGE_SERVER` permission will be
 present in this list.
 
 6. Click authorize
+
 ![Step 6](images/intro-add-bot.png)
 
 ## Connecting to Discord
@@ -120,7 +123,7 @@ on your bot's application page on the [Discord Applications Portal]).
 
 >[!IMPORTANT]
 Your bot's token can be used to gain total access to your bot, so
-**do __NOT__ share this token with anyone!**. It may behoove you to
+**do __NOT__ share this token with anyone!** It may behoove you to
 store this token in an external file if you plan on distributing the
 source code for your bot.
 
@@ -157,7 +160,7 @@ for how to fix this.
 [TAP]: https://docs.microsoft.com/en-us/dotnet/articles/csharp/async
 [API Documentation]: xref:Discord.Rest.BaseDiscordClient#Discord_Rest_BaseDiscordClient_Log
 [DiscordSocketClient]: xref:Discord.WebSocket.DiscordSocketClient
-[installing guide]: installing.md#installing-on-.net-standard-11
+[installing guide]: installing.md#installing-on-net-standard-11
 
 ### Handling a 'ping'
 

docs/guides/logging.md

@@ -1,11 +1,42 @@
-# Using the Logger
+---
+title: Logging
+---
 
-Discord.Net will automatically output log messages through the [Log](xref:Discord.DiscordClient#Discord_DiscordClient_Log) event.
+Discord.Net's clients provide a [Log] event that all messages will be
+disbatched over.
 
-## Usage
+For more information about events in Discord.Net, see the [Events]
+section.
 
-To handle Log Messages through Discord.Net's Logger, hook into the [Log](xref:Discord.DiscordClient#Discord_DiscordClient_Log) event.
+[Log]: xref:Discord.Rest.BaseDiscordClient#Discord_Rest_BaseDiscordClient_Log
+[Events]: events.md
 
-The @Discord.LogMessage object has a custom `ToString` method attached to it, when outputting log messages, it is reccomended you use this, instead of building your own output message.
+### Usage
 
-[!code-csharp[](samples/logging.cs)]
+To receive log events, simply hook the discord client's log method
+to a Task with a single parameter of type [LogMessage]
+
+It is recommended that you use an established function instead of a
+lambda for handling logs, because most [addons] accept a reference
+to a logging function to write their own messages.
+
+### Usage in Commands
+
+Discord.Net's [CommandService] also provides a log event, identical
+in signature to other log events.
+
+Data logged through this event is typically coupled with a
+[CommandException], where information about the command's context
+and error can be found and handled.
+
+#### Samples
+
+[!code-csharp[Logging Sample](samples/logging.cs)]
+
+#### Tips
+
+Due to the nature of Discord.Net's event system, all log event
+handlers will be executed synchronously on the gateway thread. If your
+log output will be dumped to a Web API (e.g. Sentry), you are advised
+to wrap your output in a `Task.Run` so the gateway thread does not
+become blocked while waiting for logging data to be written.

docs/guides/samples/logging.cs

@@ -1,28 +1,29 @@
 using Discord;
-using Discord.Rest;
+using Discord.WebSocket;
 
 public class Program
 {
-    private DiscordSocketClient _client;
-    static void Main(string[] args) => new Program().Start().GetAwaiter().GetResult();
-    
-    public async Task Start()
-    {
-        _client = new DiscordSocketClient(new DiscordSocketConfig() {
+	private DiscordSocketClient _client;
+	static void Main(string[] args) => new Program().MainAsync().GetAwaiter().GetResult();
+	
+	public async Task MainAsync()
+	{
+		_client = new DiscordSocketClient(new DiscordSocketConfig
+		{
 			LogLevel = LogSeverity.Info
-        });
+		});
 
-        _client.Log += Log;
+		_client.Log += Log;
 
-	 await _client.LoginAsync(TokenType.Bot, "bot token");
-	 await _client.ConnectAsync();
-	    
-	 await Task.Delay(-1);
-    }
+		await _client.LoginAsync(TokenType.Bot, "bot token");
+		await _client.StartAsync();
+		
+		await Task.Delay(-1);
+	}
 
-    private Task Log(LogMessage message)
-    {
-        Console.WriteLine(message.ToString());
-        return Task.CompletedTask;
-    }
-}
+	private Task Log(LogMessage message)
+	{
+		Console.WriteLine(message.ToString());
+		return Task.CompletedTask;
+	}
+}