Merge pull request #23 from 420foxbot/docsrewrite

started updating documentation for 0.9

docs/features/commands.rst

@@ -1,5 +1,5 @@
-Commands
-========
+|stub| Commands
+===============
 
 The `Discord.Net.Commands`_ package DiscordBotClient extends DiscordClient with support for commands.
 
@@ -11,10 +11,10 @@ Example (Simple)
 .. literalinclude:: /samples/command.cs
    :language: csharp6
    :tab-width: 2
-   
+
 Example (Groups)
 ----------------
 
 .. literalinclude:: /samples/command_group.cs
    :language: csharp6
-   :tab-width: 2
+   :tab-width: 2

docs/features/events.rst

@@ -1,75 +1,75 @@
-|stub| Events
-=============
+Events
+======
 
 Usage
 -----
-To take advantage of Events in Discord.Net, you need to hook into them. 
-
-There are two ways of hooking into events. See the example for examples on using these events.
-
-Usable Events
--------------
-+--------------------+--------------------+------------------------------------------+
-| Event Name         | EventArgs          | Description                              |
-+====================+====================+==========================================+
-| UserBanned         | BanEventArgs       | Called when a user is banned.            |
-+--------------------+--------------------+------------------------------------------+
-| UserUnbanned       | BanEventArgs       | Called when a user is unbanned.          |
-+--------------------+--------------------+------------------------------------------+
-| ChannelCreated     | ChannelEventArgs   | Called when a channel is created.        |
-+--------------------+--------------------+------------------------------------------+
-| ChannelDestroyed   | ChannelEventArgs   | Called when a channel is destroyed.      |
-+--------------------+--------------------+------------------------------------------+
-| ChannelUpdated     | ChannelEventArgs   | Called when a channel is updated.        |
-+--------------------+--------------------+------------------------------------------+
-| MessageReceived    | MessageEventArgs   | Called when a message is received.       |
-+--------------------+--------------------+------------------------------------------+
-| MessageSent        | MessageEventArgs   | Called when a message is sent.           |
-+--------------------+--------------------+------------------------------------------+
-| MessageDeleted     | MessageEventArgs   | Called when a message is deleted.        |
-+--------------------+--------------------+------------------------------------------+
-| MessageUpdated     | MessageEventArgs   | Called when a message is updated\\edited.|
-+--------------------+--------------------+------------------------------------------+
-| MessageReadRemotely| MessageEventArgs   | Called when a message is read.           |
-+--------------------+--------------------+------------------------------------------+
-| RoleCreated        | RoleEventArgs      | Called when a role is created.           |
-+--------------------+--------------------+------------------------------------------+
-| RoleUpdated        | RoleEventArgs      | Called when a role is updated.           |
-+--------------------+--------------------+------------------------------------------+
-| RoleDeleted        | RoleEventArgs      | Called when a role is deleted.           |
-+--------------------+--------------------+------------------------------------------+
-| JoinedServer       | ServerEventArgs    | Called when a member joins a server.     |
-+--------------------+--------------------+------------------------------------------+
-| LeftServer         | ServerEventArgs    | Called when a member leaves a server.    |
-+--------------------+--------------------+------------------------------------------+
-| ServerUpdated      | ServerEventArgs    | Called when a server is updated.         |
-+--------------------+--------------------+------------------------------------------+
-| ServerUnavailable  | ServerEventArgs    | Called when a Discord server goes down.  |
-+--------------------+--------------------+------------------------------------------+
-| ServerAvailable    | ServerEventArgs    |Called when a Discord server goes back up.|
-+--------------------+--------------------+------------------------------------------+
-| UserJoined         | UserEventArgs      | Called when a user joins a Channel.      |
-+--------------------+--------------------+------------------------------------------+
-| UserLeft           | UserEventArgs      | Called when a user leaves a Channel.     |
-+--------------------+--------------------+------------------------------------------+
-| UserUpdated        | UserEventArgs      | ---                                      |
-+--------------------+--------------------+------------------------------------------+
-| UserPresenceUpdated| UserEventArgs      | Called when a user's presence changes.   |
-|                    |                    | (Here\\Away)                             |
-+--------------------+--------------------+------------------------------------------+
-| UserVoiceState     | UserEventArgs      | Called when a user's voice state changes.|
-| Updated            |                    | (Muted\\Unmuted)                         |
-+--------------------+--------------------+------------------------------------------+
-|UserIsTypingUpdated | UserEventArgs      | Called when a user starts\\stops typing. |
-+--------------------+--------------------+------------------------------------------+
-| UserIsSpeaking     | UserEventArgs      | Called when a user's voice state changes.|
-| Updated            |                    | (Speaking\\Not Speaking)                 |
-+--------------------+--------------------+------------------------------------------+
-| ProfileUpdated     | N/A                | Called when a user's profile changes.    |
-+--------------------+--------------------+------------------------------------------+
-Example
--------
-   
-.. literalinclude:: /samples/events.cs
-   :language: csharp6
-   :tab-width: 2
+Events in Discord.NET are raised using the Event system in c#. Most events are raised on the ``DiscordClient`` class.
+
+Most events in Discord.NET explain theirselves by their name.
+
+Messages
+--------
+
+The Four Message Events (MessageReceived, Updated, Deleted, and Acknowledged) are raised when a message has been modified/created.
+
+Example of MessageReceived:
+
+.. code-block:: c#
+
+    // (Preface: Echo Bots are discouraged, make sure your bot is not running in a public server if you use them)
+
+    // Hook into the MessageReceived event using a Lambda
+    _client.MessageReceived += (s, e) => {
+            // Check to make sure that the bot is not the author
+            if (!e.Message.IsAuthor)
+                // Echo the message back to the channel
+                e.Channel.SendMessage(e.Message);
+    };
+
+Users
+-----
+
+There are Six User Events:
+
+UserBanned: A user has been banned from a Server
+UserUnbanned: A user was unbanned
+UserJoined: A user joins a server
+UserLeft: A user left (or was kicked) from a Server
+UserIsTyping: A user in a channel starts typing
+UserUpdated: A user object was updated. (caused by a presence update, role/permission change, or a voice state update)
+
+.. note::
+    UserUpdated Events include a ``User`` object for Before and After the change.
+    When accessing the User, you should only use ``e.Before`` if comparing changes, otherwise use ``e.After``
+
+Examples:
+
+.. code-block:: c#
+
+    // Register a Hook into the UserBanned event using a Lambda
+    _client.UserBanned += (s, e) => {
+        // Create a Channel object by searching for a channel named '#logs' on the server the ban occurred in.
+        var logChannel = e.Server.FindChannels("logs").FirstOrDefault();
+        // Send a message to the server's log channel, stating that a user was banned.
+        logChannel.SendMessage($"User Banned: {e.User.Name}")
+    };
+
+    // Register a Hook into the UserUpdated event using a Lambda
+    _client.UserUpdated += (s, e) => {
+        // Check that the user is in a Voice channel
+        if (e.After.VoiceChannel == null) return;
+
+        // See if they changed Voice channels
+        if (e.Before.VoiceChannel == e.After.VoiceChannel) return;
+
+        // do something...
+    };
+
+Connection States
+-----------------
+
+Connection Events will be raised when the Connection State of your client changes.
+
+.. warning::
+    You should not use DiscordClient.Connected to run code when your client first connects to Discord.
+    If you lose connection and automatically reconnect, this code will be ran again, which may lead to unexpected behavior.

docs/features/permissions.rst

@@ -1,11 +1,11 @@
 Permissions
-==================
+===========
 
 There are two types of permissions: *Channel Permissions* and *Server Permissions*.
 
 Channel Permissions
 -------------------
-Channel Permissions have a set of bools behind them:
+Channel Permissions are controlled using a set of flags:
 
 ======================= ======= ==============
 Flag                    Type    Description
@@ -49,7 +49,7 @@ Otherwise, you can use a single DualChannelPermissions.
 Server Permissions
 ------------------
 
-Server permisisons are read-only, you cannot change them. You may still access them, however, using User.GetServerPermissions();
+Server Permissions can be accessed by ``Server.GetPermissions(User)``, and updated with ``Server.UpdatePermissions(User, ServerPermissions)``
 
 A user's server permissions also contain the default values for it's channel permissions, so the channel permissions listed above are also valid flags for Server Permissions. There are also a few extra Server Permissions:
 
@@ -57,7 +57,7 @@ A user's server permissions also contain the default values for it's channel per
 Flag                    Type    Description
 ======================= ======= ==============
 BanMembers              Server  Ban users from the server.
-KickMembers             Server  Kick users from the server. They can stil rejoin.
+KickMembers             Server  Kick users from the server. They can still rejoin.
 ManageRoles             Server  Manage roles on the server, and their permissions.
 ManageChannels          Server  Manage channels that exist on the server (add, remove them)
 ManageServer            Server  Manage the server settings.
@@ -69,7 +69,7 @@ Managing permissions for roles is much easier than for users in channels. For ro
 
 Example
 -------
-   
+
 .. literalinclude:: /samples/permissions.cs
    :language: csharp6
-   :tab-width: 2
+   :tab-width: 2

docs/index.rst

@@ -1,7 +1,7 @@
 Discord.Net
 ===========
 
-Discord.Net is an unofficial C# wrapper around the `Discord chat service`.
+Discord.Net is an unofficial C# wrapper around the `Discord Chat Service`.
 It offers several methods to create automated operations, bots, or even custom clients.
 
 Feel free to join us in the `Discord API chat`_.
@@ -9,28 +9,28 @@ Feel free to join us in the `Discord API chat`_.
 .. _Discord chat service: https://discordapp.com
 .. _Discord API chat: https://discord.gg/0SBTUU1wZTVjAMPx
 
-Warning
--------
+.. warn::
 
-This is an alpha!
+This is a beta!
 
-This library has been built thanks to a community effort reverse engineering the Discord client. 
-As Discord is still in alpha, it may change at any time without notice, breaking this library as well.
-Discord.Net itself is also in early development and you will often encounter breaking changes until the official Discord API is released.
+This library has been built thanks to a community effort reverse engineering the Discord client.
+As the API is still unofficial, it may change at any time without notice, breaking this library as well.
+Discord.Net itself is still in development (and is currently undergoing a rewrite) and you may encounter breaking changes throughout development until the official Discord API is released.
 
 It is highly recommended that you always use the latest version and please report any bugs you find to our `Discord chat`_.
 
 .. _Discord chat: https://discord.gg/0SBTUU1wZTVjAMPx
 
+This Documentation is **currently undergoing a rewrite**. Some pages (marked with a wrench) are not updated, or are not completed yet.
+
 .. toctree::
    :caption: Documentation
    :maxdepth: 2
-   
-   getting_started  
-   features/logging 
+
+   getting_started
+   features/logging
    features/management
    features/permissions
-   features/profile
    features/commands
    features/voice
-   features/events
+   features/events

docs/samples/getting_started.cs

@@ -11,17 +11,17 @@ class Program
 		client.MessageReceived += async (s, e) =>
 		{
 			if (!e.Message.IsAuthor)
-				await client.SendMessage(e.Channel, e.Message.Text);
+				await e.Channel.SendMessage(e.Message.Text);
 		};
 
 		//Convert our sync method to an async one and block the Main function until the bot disconnects
-		client.Run(async () =>
+		client.ExecuteAndWait(async () =>
 		{
 			//Connect to the Discord server using our email and password
 			await client.Connect("discordtest@email.com", "Password123");
 
 			//If we are not a member of any server, use our invite code (made beforehand in the official Discord Client)
-			if (!client.AllServers.Any())
+			if (!client.Servers.Any())
 				await client.AcceptInvite(client.GetInvite("aaabbbcccdddeee"));
 		});
 	}

docs/samples/permissions.cs

@@ -1,28 +1,14 @@
-// Finding User Permissions
+// Find a User's Channel Permissions
+var userChannelPermissions = user.GetPermissions(channel);
 
-void FindPermissions(User u, Channel c)
-{
-	ChannelPermissions cperms = u.GetPermissions(c);
-	ServerPermissions sperms = u.GetServerPermissions();
-}
-
-void SetPermissionsChannelPerms(User u, Channel c)
-{
-	ChannelPermissions allow = new ChannelPermissions();
-	ChannelPermissions deny = new ChannelPermissions();
+// Find a User's Server Permissions
+var userServerPermissions = user.ServerPermissions();
+var userServerPermissions = server.GetPermissions(user);
 
-	allow.Connect = true;
-	deny.AttachFiles = true;
+// Set a User's Channel Permissions (using DualChannelPermissions)
 
-	client.SetChannelPermissions(c, u, allow, deny)
+var userPerms = user.GetPermissions(channel);
+userPerms.ReadMessageHistory = false;
+userPerms.AttachFiles = null;
+channel.AddPermissionsRule(user, userPerms);
 }
-
-void SetPermissionsDualPerms(User u, Channel c)
-{
-	DualChannelPermissions dual = new DualChannelPermissions();
-    dual.ReadMessageHistory = false;
-    dual.Connect = true;
-    dual.AttachFiles = null;
-
-    client.SetChannelPermissions(c, u, dual);
-}