Add event docs

- MessageReceived - ChannelUpdated/Destroyed/Created
Still34 · May 22, 2018 · a998302 · a998302
1 parent dece19d
commit a998302
Show file tree

Hide file tree

Showing 2 changed files with 69 additions and 1 deletion.
diff --git a/docs/docfx.json b/docs/docfx.json
@@ -43,7 +43,7 @@
     "globalMetadata": {
 	  "_appTitle": "Discord.Net Documentation",
       "_appFooter": "Discord.Net (c) 2015-2018 2.0.0-beta",
-      "_enableSearch": true,
+      "_enableSearch": true
     },
     "noLangKeyword": false,
     "xrefService": [

diff --git a/src/Discord.Net.WebSocket/BaseSocketClient.Events.cs b/src/Discord.Net.WebSocket/BaseSocketClient.Events.cs
@@ -7,19 +7,53 @@ public partial class BaseSocketClient
     {
         //Channels
         /// <summary> Fired when a channel is created. </summary>
+        /// <remarks>
+        ///     <para>
+        ///         This event is fired when a generic channel has been created. The event handler must return a
+        ///         <see cref="Task"/>.
+        ///     </para>
+        ///     <para>
+        ///         The newly created channel is passed into the event handler parameter. The given channel type may
+        ///         include, but not limited to, Private Channels (DM, Group), Guild Channels (Text, Voice, Category);
+        ///         see the derived classes of <see cref="SocketChannel"/> for more details.
+        ///     </para>
+        /// </remarks>
         public event Func<SocketChannel, Task> ChannelCreated 
         {
             add { _channelCreatedEvent.Add(value); }
             remove { _channelCreatedEvent.Remove(value); }
         }
         internal readonly AsyncEvent<Func<SocketChannel, Task>> _channelCreatedEvent = new AsyncEvent<Func<SocketChannel, Task>>();
         /// <summary> Fired when a channel is destroyed. </summary>
+        /// <remarks>
+        ///     <para>
+        ///         This event is fired when a generic channel has been destroyed. The event handler must return a
+        ///         <see cref="Task"/>.
+        ///     </para>
+        ///     <para>
+        ///         The destroyed channel is passed into the event handler parameter. The given channel type may
+        ///         include, but not limited to, Private Channels (DM, Group), Guild Channels (Text, Voice, Category);
+        ///         see the derived classes of <see cref="SocketChannel"/> for more details.
+        ///     </para>
+        /// </remarks>
         public event Func<SocketChannel, Task> ChannelDestroyed {
             add { _channelDestroyedEvent.Add(value); }
             remove { _channelDestroyedEvent.Remove(value); }
         }
         internal readonly AsyncEvent<Func<SocketChannel, Task>> _channelDestroyedEvent = new AsyncEvent<Func<SocketChannel, Task>>();
         /// <summary> Fired when a channel is updated. </summary>
+        /// <remarks>
+        ///     <para>
+        ///         This event is fired when a generic channel has been destroyed. The event handler must return a
+        ///         <see cref="Task"/>.
+        ///     </para>
+        ///     <para>
+        ///         The original (prior to update) channel is passed into the first <see cref="SocketChannel"/>, while
+        ///         the updated channel is passed into the second. The given channel type may include, but not limited
+        ///         to, Private Channels (DM, Group), Guild Channels (Text, Voice, Category); see the derived classes of
+        ///         <see cref="SocketChannel"/> for more details.
+        ///     </para>
+        /// </remarks>
         public event Func<SocketChannel, SocketChannel, Task> ChannelUpdated {
             add { _channelUpdatedEvent.Add(value); }
             remove { _channelUpdatedEvent.Remove(value); }
@@ -28,12 +62,46 @@ public event Func<SocketChannel, SocketChannel, Task> ChannelUpdated {
 
         //Messages
         /// <summary> Fired when a message is received. </summary>
+        /// <remarks>
+        ///     <para>
+        ///         This event is fired when a message is received. The event handler must return a
+        ///         <see cref="Task"/>.
+        ///     </para>
+        ///     <para>
+        ///         The message that is sent to the client is passed into the event handler parameter as
+        ///         <see cref="SocketMessage"/>. This message may be a system message (i.e.
+        ///         <see cref="SocketSystemMessage"/>) or a user message (i.e. <see cref="SocketUserMessage"/>. See
+        ///         the derived clsases of <see cref="SocketMessage"/> for more details.
+        ///     </para>
+        /// </remarks>
         public event Func<SocketMessage, Task> MessageReceived {
             add { _messageReceivedEvent.Add(value); }
             remove { _messageReceivedEvent.Remove(value); }
         }
         internal readonly AsyncEvent<Func<SocketMessage, Task>> _messageReceivedEvent = new AsyncEvent<Func<SocketMessage, Task>>();
         /// <summary> Fired when a message is deleted. </summary>
+        /// <remarks>
+        ///     <para>
+        ///         This event is fired when a message is deleted. The event handler must return a
+        ///         <see cref="Task"/> and accept a <see cref="Cacheable{TEntity,TId}"/> and 
+        ///         <see cref="ISocketMessageChannel"/> as its parameters.
+        ///     </para>
+        ///     <para>
+        ///         <note type="important">
+        ///             It is not possible to retrieve the message via
+        ///             <see cref="Cacheable{TEntity,TId}.DownloadAsync"/>; the message cannot be retrieved by Discord
+        ///             after the message has been deleted.
+        ///         </note>
+        ///         If caching is enabled via <see cref="DiscordSocketConfig"/>, the
+        ///         <see cref="Cacheable{TEntity,TId}"/> entity will contain the deleted message; otherwise, in event
+        ///         that the message cannot be retrieved, the snowflake ID of the message is preserved in the 
+        ///         <see cref="ulong"/>.
+        ///     </para>
+        ///     <para>
+        ///         The source channel of the removed message will be passed into the 
+        ///         <see cref="ISocketMessageChannel"/> parameter.
+        ///     </para>
+        /// </remarks>
         public event Func<Cacheable<IMessage, ulong>, ISocketMessageChannel, Task> MessageDeleted {
             add { _messageDeletedEvent.Add(value); }
             remove { _messageDeletedEvent.Remove(value); }