github/Discord.Net
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Documentation December Update (#1218)

Browse Source 
* Fix broken link (#11)

* Fix typos and improve wording

* Add information for IGuildUser

+ Add GetPermission sample
+ Add ModifyAsync remarks

* Add information for IGuildChannel

+ Add ModifyAsync remarks
+ Add GetOverwritePermissionAsync examples

* Add warning for Direction.Around

* Fix indentations and references

* Move IRole.ModifyAsync sample

* Add information for IUser

+ Add example, remarks for Get(Default)AvatarUrl
+ Add example, remarks for GetOrCreateDMChannelAsync
+ Add missing remarks/summary/returns for other properties of the class

* Change verbs used in IVoiceState summary/remarks

* Add additional explanation for IGuildUser.RoleIds

* Change verbs used in IMessage summary/remarks

* Clarify IUserMessage Add/RemoveReactionAsync samples

* Fix command handler sample typo

* Add information for DiscordSocketConfig

+ Add remarks/example to the class
+ Add remarks to AlwaysDownloadUsers

* Fix documentation for SlowMode

* Add additional remarks for Guild/TextChannelProperties

* Update DocFx.Plugins.LastModified to v1.2.0
This should drastically improve docfx build time.

* Add missing dependencies

* Update DocFx.Plugins.LastModified to v1.2.1

Improve performance

* Update DocFx.Plugins.LastModified to v1.2.2

* Clarify deployment.md

+ Rewritten .NET Core deployment strategies for better clarification
    * Split deployment types into framework-dependent and self-contained
    * Clarify the benefits of using different types of publishing
    * Include a sample of how to execute dotnet application with the dotnet command in a TIP dialog for visibility

* Update post-execution article and samples

+ This change is to reflect changes made in https://github.com/RogueException/Discord.Net/pull/1164, where CommandInfo is now passed into the CommandExecuted event as an Optional<T>

* Update DocFX.Plugin.DescriptionGenerator to v1.1.1

* Adjust according to recent CommandExecuted changes

See:
+ f549da50e0
+ 6260749095

* Add further documentation for https://github.com/RogueException/Discord.Net/pull/1037

* Add partial documentation for the precondition helper class

* Include CHANGELOG.md in docs

* Revise post-execution docs
* Fix incorrect Optional<T> usage
* Indent some sample code and add a comment reminding the user that the post-execution basic sample code is not ideal.

* Streamline docs for Attachment
+ This commit also adds further explanation for why Embeds and Attachments are read-only collections

* Add further documentation for MessageActivity and MessageApplication

* Add caching-related docs to ISocketMessageChannel

* Add missing documentation inheritance for SyncPermissionsAsync

* Streamline documentation process

This is done by changing the documentation of the implementations required by interfaces to redirect to the interface method instead (e.g., SocketDMChannel#GetMessagesAsync refer to IMessageChannel.GetMessagesAsync within the remarks of the method).

* Cleanup 92bf8363ca

* Update src/Discord.Net.Core/Entities/Channels/Direction.cs

Co-Authored-By: Still34 <341464@gmail.com>

* Update src/Discord.Net.Core/Entities/Channels/Direction.cs

Co-Authored-By: Still34 <341464@gmail.com>

* Update src/Discord.Net.Core/Entities/Channels/GuildChannelProperties.cs

Co-Authored-By: Still34 <341464@gmail.com>

* Update src/Discord.Net.WebSocket/DiscordSocketConfig.cs

Co-Authored-By: Still34 <341464@gmail.com>

* Update according to PR suggestions

* Reword sentences of deployment article for clarification & remove mention of portability
* Fix typos/grammar errors within TextChannelProperties

* Add the logo SVG to the page navbar

* Implement changing logo image based on theme color using CSS background image

* Add a favicon

* use the purple logomark instead of white

* hack? set the title to navbar svg to read "Discord.Net Docs"
This commit is contained in:
Still Hsu
2018-12-29 00:49:02 +08:00
committed by Christopher F
parent 2a67514e55
commit 0fecdf69bb
65 changed files with 812 additions and 379 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
src/Discord.Net.WebSocket/Entities/Channels/ISocketMessageChannel.cs
View File

@@ -21,6 +21,10 @@ namespace Discord.WebSocket
/// <summary>
/// Sends a message to this message channel.
/// </summary>
/// <remarks>
/// This method follows the same behavior as described in <see cref="IMessageChannel.SendMessageAsync"/>.
/// Please visit its documentation for more details on this method.
/// </remarks>
/// <param name="text">The message to be sent.</param>
/// <param name="isTTS">Determines whether the message should be read aloud by Discord or not.</param>
/// <param name="embed">The <see cref="Discord.EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
@@ -34,12 +38,8 @@ namespace Discord.WebSocket
/// Sends a file to this message channel with an optional caption.
/// </summary>
/// <remarks>
/// This method sends a file as if you are uploading an attachment directly from your Discord client.
/// <note>
/// If you wish to upload an image and have it embedded in a <see cref="Discord.EmbedType.Rich"/>embed,
/// you may upload the file and refer to the file with "attachment://filename.ext" in the
/// <see cref="Discord.EmbedBuilder.ImageUrl"/>.
/// </note>
/// This method follows the same behavior as described in <see cref="IMessageChannel.SendFileAsync(string, string, bool, Embed, RequestOptions)"/>.
/// Please visit its documentation for more details on this method.
/// </remarks>
/// <param name="filePath">The file path of the file.</param>
/// <param name="text">The message to be sent.</param>
@@ -55,12 +55,8 @@ namespace Discord.WebSocket
/// Sends a file to this message channel with an optional caption.
/// </summary>
/// <remarks>
/// This method sends a file as if you are uploading an attachment directly from your Discord client.
/// <note>
/// If you wish to upload an image and have it embedded in a <see cref="Discord.EmbedType.Rich"/>embed,
/// you may upload the file and refer to the file with "attachment://filename.ext" in the
/// <see cref="Discord.EmbedBuilder.ImageUrl"/>.
/// </note>
/// This method follows the same behavior as described in <see cref="IMessageChannel.SendFileAsync(Stream, string, string, bool, Embed, RequestOptions)"/>.
/// Please visit its documentation for more details on this method.
/// </remarks>
/// <param name="stream">The <see cref="Stream" /> of the file to be sent.</param>
/// <param name="filename">The name of the attachment.</param>
@@ -75,16 +71,41 @@ namespace Discord.WebSocket
new Task<RestUserMessage> SendFileAsync(Stream stream, string filename, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null);
/// <summary>
/// Gets the cached message if one exists.
/// Gets a cached message from this channel.
/// </summary>
/// <param name="id">The ID of the message.</param>
/// <remarks>
/// <note type="warning">
/// This method requires the use of cache, which is not enabled by default; if caching is not enabled,
/// this method will always return <c>null</c>. Please refer to
/// <see cref="Discord.WebSocket.DiscordSocketConfig.MessageCacheSize" /> for more details.
/// </note>
/// <para>
/// This method retrieves the message from the local WebSocket cache and does not send any additional
/// request to Discord. This message may be a message that has been deleted.
/// </para>
/// </remarks>
/// <param name="id">The snowflake identifier of the message.</param>
/// <returns>
/// Cached message object; <c>null</c> if it doesn't exist in the cache.
/// A WebSocket-based message object; <c>null</c> if it does not exist in the cache or if caching is not
/// enabled.
/// </returns>
SocketMessage GetCachedMessage(ulong id);
/// <summary>
/// Gets the last N messages from this message channel.
/// Gets the last N cached messages from this message channel.
/// </summary>
/// <remarks>
/// <note type="warning">
/// This method requires the use of cache, which is not enabled by default; if caching is not enabled,
/// this method will always return an empty collection. Please refer to
/// <see cref="Discord.WebSocket.DiscordSocketConfig.MessageCacheSize" /> for more details.
/// </note>
/// <para>
/// This method retrieves the message(s) from the local WebSocket cache and does not send any additional
/// request to Discord. This read-only collection may include messages that have been deleted. The
/// maximum number of messages that can be retrieved from this method depends on the
/// <see cref="Discord.WebSocket.DiscordSocketConfig.MessageCacheSize" /> set.
/// </para>
/// </remarks>
/// <param name="limit">The number of messages to get.</param>
/// <returns>
/// A read-only collection of WebSocket-based messages.
@@ -92,8 +113,21 @@ namespace Discord.WebSocket
IReadOnlyCollection<SocketMessage> GetCachedMessages(int limit = DiscordConfig.MaxMessagesPerBatch);
/// <summary>
/// Gets a collection of messages in this channel.
/// Gets the last N cached messages starting from a certain message in this message channel.
/// </summary>
/// <remarks>
/// <note type="warning">
/// This method requires the use of cache, which is not enabled by default; if caching is not enabled,
/// this method will always return an empty collection. Please refer to
/// <see cref="Discord.WebSocket.DiscordSocketConfig.MessageCacheSize" /> for more details.
/// </note>
/// <para>
/// This method retrieves the message(s) from the local WebSocket cache and does not send any additional
/// request to Discord. This read-only collection may include messages that have been deleted. The
/// maximum number of messages that can be retrieved from this method depends on the
/// <see cref="Discord.WebSocket.DiscordSocketConfig.MessageCacheSize" /> set.
/// </para>
/// </remarks>
/// <param name="fromMessageId">The message ID to start the fetching from.</param>
/// <param name="dir">The direction of which the message should be gotten from.</param>
/// <param name="limit">The number of messages to get.</param>
@@ -102,8 +136,21 @@ namespace Discord.WebSocket
/// </returns>
IReadOnlyCollection<SocketMessage> GetCachedMessages(ulong fromMessageId, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch);
/// <summary>
/// Gets a collection of messages in this channel.
/// Gets the last N cached messages starting from a certain message in this message channel.
/// </summary>
/// <remarks>
/// <note type="warning">
/// This method requires the use of cache, which is not enabled by default; if caching is not enabled,
/// this method will always return an empty collection. Please refer to
/// <see cref="Discord.WebSocket.DiscordSocketConfig.MessageCacheSize" /> for more details.
/// </note>
/// <para>
/// This method retrieves the message(s) from the local WebSocket cache and does not send any additional
/// request to Discord. This read-only collection may include messages that have been deleted. The
/// maximum number of messages that can be retrieved from this method depends on the
/// <see cref="Discord.WebSocket.DiscordSocketConfig.MessageCacheSize" /> set.
/// </para>
/// </remarks>
/// <param name="fromMessage">The message to start the fetching from.</param>
/// <param name="dir">The direction of which the message should be gotten from.</param>
/// <param name="limit">The number of messages to get.</param>
@@ -112,12 +159,16 @@ namespace Discord.WebSocket
/// </returns>
IReadOnlyCollection<SocketMessage> GetCachedMessages(IMessage fromMessage, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch);
/// <summary>
/// Gets a collection of pinned messages in this channel.
/// Gets a read-only collection of pinned messages in this channel.
/// </summary>
/// <remarks>
/// This method follows the same behavior as described in <see cref="IMessageChannel.GetPinnedMessagesAsync"/>.
/// Please visit its documentation for more details on this method.
/// </remarks>
/// <param name="options">The options to be used when sending the request.</param>
/// <returns>
/// A task that represents the asynchronous get operation for retrieving pinned messages in this channel.
/// The task result contains a collection of messages found in the pinned messages.
/// The task result contains a read-only collection of messages found in the pinned messages.
/// </returns>
new Task<IReadOnlyCollection<RestMessage>> GetPinnedMessagesAsync(RequestOptions options = null);
}