Merge pull request #11 from 420foxbot/master

Updated the Documentation

docs/features/events.rst

@@ -1,4 +1,75 @@
 |stub| Events
 =============
 
-|stub-desc|
+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

docs/features/permissions.rst

@@ -1,4 +1,75 @@
-|stub| Permissions
+Permissions
 ==================
 
-|stub-desc|
+There are two types of permissions: *Channel Permissions* and *Server Permissions*.
+
+Channel Permissions
+-------------------
+Channel Permissions have a set of bools behind them:
+
+======================= ======= ==============
+Flag                    Type    Description
+======================= ======= ==============
+AttachFiles             Text    Send files to a channel.
+Connect                 Voice   Connect to a voice channel.
+CreateInstantInvite     General Create an invite to the channel.
+DeafenMembers           Voice   Prevent users of a voice channel from hearing other users (server-wide).
+EmbedLinks              Text    Create embedded links.
+ManageChannel           General Manage a channel.
+ManageMessages          Text    Remove messages in a channel.
+ManagePermissions       General Manage the permissions of a channel.
+MentionEveryone         Text    Use @everyone in a channel.
+MoveMembers             Voice   Move members around in voice channels.
+MuteMembers             Voice   Mute users of a voice channel (server-wide).
+ReadMessageHistory      Text    Read the chat history of a voice channel.
+ReadMessages            Text    Read any messages in a text channel; exposes the text channel to users.
+SendMessages            Text    Send messages in a text channel.
+SendTTSMessages         Text    Send TTS messages in a text channel.
+Speak                   Voice   Speak in a voice channel.
+UseVoiceActivation      Voice   Use Voice Activation in a text channel (for large channels where PTT is preferred)
+======================= ======= ==============
+
+If a user has a permission, the value is true. Otherwise, it must be null.
+
+Dual Channel Permissions
+------------------------
+You may also access a user's permissions in a channel with the DualChannelPermissions class.
+Unlike normal ChannelPermissions, DualChannelPermissions hold three values:
+
+If a user has a permission, the value is true. If a user is denied a permission, it will be false. If the permission is not set, the value will return null.
+
+Setting Channel Permissions
+---------------------------
+
+To set channel permissions, you may use either two ChannelPermissions, or one DualChannelPermissions.
+
+In the case of using two Channel Permissions, you must create one list of allowed permissions, and one list of denied permissions.
+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();
+
+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:
+
+======================= ======= ==============
+Flag                    Type    Description
+======================= ======= ==============
+BanMembers              Server  Ban users from the server.
+KickMembers             Server  Kick users from the server. They can stil 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.
+
+Roles
+-----
+
+Managing permissions for roles is much easier than for users in channels. For roles, just access the flag under `Role.Permissions`.
+
+Example
+-------
+   
+.. literalinclude:: /samples/permissions.cs
+   :language: csharp6
+   :tab-width: 2

docs/global.txt

@@ -1,2 +1,2 @@
-.. |stub| unicode:: U+0D83D U+0DD27
+.. |stub| unicode:: U+1F527
 .. |stub-desc| replace:: This page is a placeholder and has not been written yet. It should be coming soon!

docs/samples/events.cs

@@ -0,0 +1,27 @@
+class Program
+{
+	private static DiscordBotClient _client;
+	static void Main(string[] args)
+	{
+		var client = new DiscordClient();
+
+		// Handle Events using Lambdas
+		client.MessageCreated += (s, e) =>
+		{
+			if (!e.Message.IsAuthor)
+				await client.SendMessage(e.Message.ChannelId, "foo");
+		}
+
+		// Handle Events using Event Handlers
+		EventHandler<MessageEventArgs> handler = new EventHandler<MessageEventArgs>(HandleMessageCreated);
+		client.MessageCreated += handler;
+	}
+
+
+	// NOTE: When using this method, 'client' must be accessible from outside the Main function.
+	static void HandleMessageCreated(object sender, EventArgs e)
+	{
+		if (!e.Message.IsAuthor)
+				await client.SendMessage(e.Message.ChannelId, "foo");
+	}
+}

docs/samples/permissions.cs

@@ -0,0 +1,28 @@
+// Finding User Permissions
+
+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();
+
+	allow.Connect = true;
+	deny.AttachFiles = true;
+
+	client.SetChannelPermissions(c, u, allow, deny)
+}
+
+void SetPermissionsDualPerms(User u, Channel c)
+{
+	DualChannelPermissions dual = new DualChannelPermissions();
+    dual.ReadMessageHistory = false;
+    dual.Connect = true;
+    dual.AttachFiles = null;
+
+    client.SetChannelPermissions(c, u, dual);
+}