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

Documentation Overhaul (#1161)

Browse Source 
* Add XML docs

* Clean up style switcher

* Squash commits on branch docs/faq-n-patches

* Fix broken theme selector

* Add local image embed instruction

* Add a bunch of XML docs

* Add a bunch of XML docs

* Fix broken search
+ DocFX by default ships with an older version of jQuery, switching to a newer version confuses parts of the DocFX Javascript.

* Minor fixes for CONTRIBUTING.md and README.md

* Clean up filterConfig.yml

+ New config exposes Discord.Net namespace since it has several common public exceptions that may be helpful to users

* Add XML docs

* Read token from Environment Variable instead of hardcode

* Add XMLDocs

* Compress some assets & add OAuth2 URL generator

* Fix sample link & add missing pictures

* Add tag examples

* Fix embed docs consistency

* Add details regarding userbot support

* Add XML Docs

* Add XML Docs

* Add XML Docs

* Minor fixes in documentations
+ Fix unescaped '<'
+ Fix typo

* Fix seealso for preconditions and add missing descriptions

* Add missing exceptions

* Document exposed TypeReaders

* Fix letter-casing for files

* Add 'last modified' plugin

Source: https://github.com/Still34/DocFx.Plugin.LastModified
Licensed under MIT License

* XML Docs

* Fix minor consistencies & redundant impl

* Add properties examples to overwrite

* Fix missing Username prop

* Add warning for bulk-delete endpoint

* Replace note block

* Add BaseSocketClient docs

* Add XML docs

* Replace langword null to code block null instead

- Because DocFX sucks at rendering langword

* Replace all langword placements with code block

* Add more IGuild docs

* Add details to SpotifyGame

* Initial proofread of the articles

* Add explanation for RunMode

* Add event docs

- MessageReceived
- ChannelUpdated/Destroyed/Created

* Fix light theme link color

* Fix xml docs error

* Add partial documentation for audit log impl

* Add documentation for some REST-based objects

* Add partial documentation for audit log objects

* Add more XML comments to quotation mark alias map stuff, including an example

* Add reference to CommandServiceConfig from the util docs'

* Add explanation that if " is removed then it wont work

* Fix missing service provider in example

* Add documentation for new INestedChannel

* Add documentation

* Add documentation for new API version & few events

* Revise guide paragraphs/samples

+ Fix various formatting.
+ Provide a more detailed walkthrough for dependency injection.
+ Add C# note at intro.

* Fix typos & formatting

* Improve group module example

* Small amount to see if I'm doing it right

* Remove/cleanup redundant variables

* Fix EnterTypingState impl for doc inheritance

* Fix Test to resolve changes made in 15b58e

* Improve precondition documentation

+ Add precondition usage sample
+ Add precondition group usage sample
+ Move precondition samples to its own sample folder

* Move samples to individual folders

* Clarify token source

* Cleanup styling of README.md for docs

* Replace InvalidPathChars for NS1.3

* InvalidPathChars does not exist in NS1.3; replaced with GetInvalidPathChars instead.

* Add a missing change for 2c7cc738

* Update LastModified to v1.1.0 & add license

* Rewrite installation page for Core 2.1

* Fix anchor link

* Bump post-processor to v1.1.1

* Add fixes to partial file & add license

* Moved theme-switcher code to scripts partial file
+ Add author's MIT license to featherlight javascript

* Remove unused bootstrap plugin

* Bump LastModified plugin

* Changed the path from 'lastmodified' to 'last-modified' for consistency

* Cleanup README & Contribution guide

* Changes to last pr

* Fix GetCategoryAsync docs

* Proofread and cleanup articles

* Change passive voice in "Get Started" to active
* Fix improper preposition in Commands Introduction page
* Fix minor grammar mistakes in "Your First Bot" (future tense -> present tense/subjunctive mood -> indicative mood/proper noun casing/incorrect noun/add missing article)
* Fix minor grammar mistakes in "Installation" (missing article)

* no hablo ingles

* Try try try again

* I'm sure you're having as much fun as I am

* Cleanup TOC & fix titles

* Improve styling

+ Change title font to Noto Sans
+ Add materialized design for commit message box

* Add DescriptionGenerator plugin

* Add nightly section for clarification

* Fix typos in Nightlies & Post-execution

* Bump DescriptionGenerator to v1.1.0

+ This build adds the functionality of generating managed references' summary into the description tag.

* Initial emoji article draft

* Add 'additional information' section for emoji article

* Add cosmetic changes to the master css

* Alter info box color
+ Add transition to article content

* Add clarification in the emoji article

* Emphasize that normal emoji string will not translate to its Unicode representation.
* Clean up or add some of the samples featured in the article.
+ Add emoji/emote declaration section for clarification.
+ Add WebSocket emote sample.
- Remove inconsistent styling ('wacky memes' proves to be too out of place).

* Improve readability for nightlies article

* Move 'Bundled Preconditions' section

* Bump LastModified to fix UTC DateTime parsing

* Add langwordMapping.yml

* Add XML docs

* Add VSC workspace rule

* The root workspace limits the ruler to 120 characters for member documentations and excludes folders such as 'samples' and 'docs'.
* The docs workspace limits the ruler to 70 characters for standard conceptual article to comply with documentation's CONTRIBUTING.md rule, and excludes temprorary folders created by DocFX.

* Update CONTRIBUTING.md

* Add documentation style rule

* Fix styling of several member documentation

* Fix ' />' caused by Agent Smith oddities
* Fix styling to be more specific about the mention of IDs

* Fix exception summary to comply with official Microsoft Docs style

* References
https://docs.microsoft.com/en-us/dotnet/api/system.argumentnullexception?view=netframework-4.7.2
https://docs.microsoft.com/en-us/dotnet/api/system.platformnotsupportedexception?view=netframework-4.7.2
https://docs.microsoft.com/en-us/dotnet/api/system.badimageformatexception?view=netframework-4.7.2

* Add XML documentations

* Shift color return docs

* Fix minor docs

* Added documentation for SocketDMChannel, SocketGuildChannel, and SocketTextChannel

* Add XML docs

* Corrections to SocketGuildChannel

* Corrections to SocketTextChannel

* Corrections to SocketDMChannel

* Swapped out 'id' for 'snowflake identifier

* Swapped out 'id' for 'snowflake identifier'

* SocketDMChannel amendments

* SocketGuildChannel amendments

* SocketTextChannel amendments

* Add XML docs & patch return types
+ Starting from this commit, all return types for tasks will use style similar to most documentations featured on docs.microsoft.com

References:
https://docs.microsoft.com/en-us/dotnet/api/microsoft.entityframeworkcore.dbcontext.-ctor?view=efcore-2.1
https://docs.microsoft.com/en-us/dotnet/api/system.io.filestream.readasync?view=netcore-2.1
https://docs.microsoft.com/en-us/dotnet/api/system.io.textwriter.writelineasync?view=netcore-2.1#System_IO_TextWriter_WriteLineAsync_System_Char___
And many more other asynchronous method documentations featured in the latest BCL.

* Added documentation for many audit log data types, fixed vowel indefinite articles

* Change audit log data types to start with 'Contains' (verb) instead of an article

* Fix some documentation issues and document some more audit log data types

* Fix English posession

* Add XML doc

* Documented two more types

* Documented RoleCreateAuditLogData

* Document remaining audit log data types

* Added RestDMChannel documentation

* Added RestGuildChannel documentation

* Added RestTextChannel documentation

* Added RestVoiceChannel documentation

* Added RestUser documentation

* Added RestRole documentation

* Added RestMessage documentation

* Slightly better wording

* Contains -> Contains a piece of (describe article)

* [EN] Present perf. -> past perf.

* Add XML docs

* Fix arrow alignment

* Clarify supported nullable type

* Fixed a typo in ISnowflakeEntity

* Added RestUser Documentation

* Added RestInvite documentation

* Add XML docs & minor optimizations

* Minor optimization for doc rendering

* Rollback font optimization changes

* Amendments to RestUser

* Added SocketDMChannel documentation

* Added RestDMChannel documentation

* Added RestGuild documentation

* Adjustment to SocketDMChannel

* Added minimal descriptions from the API documentation for Integration types

* Added obsolete mention to the ReadMessages flag.

* Added remarks about 2FA requirement for guild permissions

* Added xmldoc for GuildPermission methods

* Added xml doc for ToAllowList and ToDenyList

* Added specification of how the bits of the color raw value are packed

* Added discord API documentation to IConnection interface

* I can spell :^)

* Fix whitespace in ChannelPermission

* fix spacing of values in guildpermission

* Made changes to get field descriptions from feedback, added returns tag to IConnection

* Added property get standard for IntegrationAccount

* Added property get pattern to xml docs and identical returns tag.

* Change all color class references to struct
...because it isn't a class.

* Add XML docs

* Rewrote the returns tags in IGuildIntegration, removed the ones I was unsure about.

* Rewrote the rest of the returns tags

* Amendments

* Cleanup doc for c1d78189

* Added types to <returns> tags where missing

* Added second sample for adding reactions

* Added some class summaries

* Missed a period

* Amendments

* restored the removed line break

* Removed unnecessary see tag

* Use consistent quotation marks around subscribers, the name for these users are dependant on the source of where they are integrated from (youtube or twitch), so we should not use a name that is specific to one platform

* Add <remarks> tag to the IGuildIntegration xmldocs

* Fix grammar issue

* Update DescriptionGenerator

* Cleanup of https://github.com/Still34/Discord.Net/pull/8

* Cleanup previous PR

* Fix for misleading behaviour in the emoji guide
+ Original lines stated that sending a emoji wrapped in colon will not be parsed, but that was incorrect; replaced with reactions instead of sending messages as the example

* Add strings for dictionary in DotSettings

* Add XML docs

* Fix lots of typos in comments
+ Geez, I didn't know there were so many.

* Add XML docs & rewrite GetMessagesAsync docs

This commit rewrites the remarks section of GetMessagesAsync, as well as adding examples to several methods.

* Update 'Your First Bot'
+ This commit reflects the new changes made to the Discord Application Developer Portal after its major update

* Initial optimization for DocFX render & add missing files

* Add examples in message methods

* Cleanup https://github.com/RogueException/Discord.Net/pull/1128

* Fix first bot note

* Cleanup FAQ structure

* Add XML docs

* Update docfx plugins

* Fix navbar collapsing issue

* Fix broken xref

* Cleanup FAQ section
+ Add introductory paragraphs to each FAQ section.
+ Add 'missing dependency' entry to commands FAQ.
* Split commands FAQ to 'General' and 'DI' sections.

* Cleanup https://github.com/RogueException/Discord.Net/pull/1139

* Fix missing namespace

* Add missing highlighting css for the light theme

* Add additional clarification for installing packages

* Add indentation to example for clarity

* Cleanup several articles to be more human-friendly and easier to read

* Remove RPC-related notes

* Cleanup slow-mode-related documentation strings

* Add an additional note about cross-guild emote usage

* Add CreateTextChannel sample

* Add XMLDocs
This commit is contained in:
Still Hsu
2018-10-01 05:44:33 +08:00
committed by Christopher F
parent 6b21b11f7d
commit ff0fea98a6
498 changed files with 16064 additions and 2633 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
docs/_overwrites/Common/EmbedBuilder.Overwrites.md Normal file
View File

@@ -0,0 +1,68 @@
---
uid: Discord.EmbedBuilder
seealso:
- linkId: Discord.EmbedFooterBuilder
- linkId: Discord.EmbedAuthorBuilder
- linkId: Discord.EmbedFieldBuilder
remarks: *content
---
This builder class is used to build an @Discord.Embed (rich embed)
object that will be ready to be sent via @Discord.IMessageChannel.SendMessageAsync*
after @Discord.EmbedBuilder.Build* is called.
---
uid: Discord.EmbedBuilder
example: [*content]
---
#### Basic Usage
The example below builds an embed and sends it to the chat using the
command system.
```cs
[Command("embed")]
public async Task SendRichEmbedAsync()
{
var embed = new EmbedBuilder
{
// Embed property can be set within object initializer
Title = "Hello world!"
Description = "I am a description set by initializer."
};
// Or with methods
embed.AddField("Field title",
"Field value. I also support [hyperlink markdown](https://example.com)!")
.WithAuthor(Context.Client.CurrentUser)
.WithFooter(footer => footer.Text = "I am a footer.")
.WithColor(Color.Blue)
.WithTitle("I overwrote \"Hello world!\"")
.WithDescription("I am a description.")
.WithUrl("https://example.com")
.WithCurrentTimestamp()
.Build();
await ReplyAsync(embed: embed);
}
```
![Embed Example](images/embed-example.png)
#### Usage with Local Images
The example below sends an image and has the image embedded in the rich
embed. See @Discord.IMessageChannel.SendFileAsync* for more information
about uploading a file or image.
```cs
[Command("embedimage")]
public async Task SendEmbedWithImageAsync()
{
var fileName = "image.png";
var embed = new EmbedBuilder()
{
ImageUrl = $"attachment://{fileName}"
}.Build();
await Context.Channel.SendFileAsync(fileName, embed: embed);
}
```

25
docs/_overwrites/Common/EmbedObjectBuilder.Inclusion.md Normal file
View File

@@ -0,0 +1,25 @@
The example will build a rich embed with an author field, a footer
field, and 2 normal fields using an @Discord.EmbedBuilder:
```cs
var exampleAuthor = new EmbedAuthorBuilder()
.WithName("I am a bot")
.WithIconUrl("https://discordapp.com/assets/e05ead6e6ebc08df9291738d0aa6986d.png");
var exampleFooter = new EmbedFooterBuilder()
.WithText("I am a nice footer")
.WithIconUrl("https://discordapp.com/assets/28174a34e77bb5e5310ced9f95cb480b.png");
var exampleField = new EmbedFieldBuilder()
.WithName("Title of Another Field")
.WithValue("I am an [example](https://example.com).")
.WithInline(true);
var otherField = new EmbedFieldBuilder()
.WithName("Title of a Field")
.WithValue("Notice how I'm inline with that other field next to me.")
.WithInline(true);
var embed = new EmbedBuilder()
.AddField(exampleField)
.AddField(otherField)
.WithAuthor(exampleAuthor)
.WithFooter(exampleFooter)
.Build();
```

20
docs/_overwrites/Common/EmbedObjectBuilder.Overwrites.md Normal file
View File

@@ -0,0 +1,20 @@
---
uid: Discord.EmbedAuthorBuilder
example: [*content]
---
[!include[Embed Object Builder Sample](EmbedObjectBuilder.Inclusion.md)]
---
uid: Discord.EmbedFooterBuilder
example: [*content]
---
[!include[Embed Object Builder Sample](EmbedObjectBuilder.Inclusion.md)]
---
uid: Discord.EmbedFieldBuilder
example: [*content]
---
[!include[Embed Object Builder Sample](EmbedObjectBuilder.Inclusion.md)]

26
docs/_overwrites/Common/IEmote.Inclusion.md Normal file
View File

@@ -0,0 +1,26 @@
The sample below sends a message and adds an @Discord.Emoji and a custom
@Discord.Emote to the message.
```cs
public async Task SendAndReactAsync(ISocketMessageChannel channel)
{
var message = await channel.SendMessageAsync("I am a message.");
// Creates a Unicode-based emoji based on the Unicode string.
// This is effectively the same as new Emoji("💕").
var heartEmoji = new Emoji("\U0001f495");
// Reacts to the message with the Emoji.
await message.AddReactionAsync(heartEmoji);
// Parses a custom emote based on the provided Discord emote format.
// Please note that this does not guarantee the existence of
// the emote.
var emote = Emote.Parse("<:thonkang:282745590985523200>");
// Reacts to the message with the Emote.
await message.AddReactionAsync(emote);
}
```
#### Result
![React Example](images/react-example.png)

81
docs/_overwrites/Common/IEmote.Overwrites.md Normal file
View File

@@ -0,0 +1,81 @@
---
uid: Discord.IEmote
seealso:
- linkId: Discord.Emote
- linkId: Discord.Emoji
- linkId: Discord.GuildEmote
- linkId: Discord.IUserMessage
remarks: *content
---
This interface is often used with reactions. It can represent an
unicode-based @Discord.Emoji, or a custom @Discord.Emote.
---
uid: Discord.Emote
seealso:
- linkId: Discord.IEmote
- linkId: Discord.GuildEmote
- linkId: Discord.Emoji
- linkId: Discord.IUserMessage
remarks: *content
---
> [!NOTE]
> A valid @Discord.Emote format is `<:emoteName:emoteId>`. This can be
> obtained by escaping with a `\` in front of the emote using the
> Discord chat client.
This class represents a custom emoji. This type of emoji can be
created via the @Discord.Emote.Parse* or @Discord.Emote.TryParse*
method.
---
uid: Discord.Emoji
seealso:
- linkId: Discord.Emote
- linkId: Discord.GuildEmote
- linkId: Discord.Emoji
- linkId: Discord.IUserMessage
remarks: *content
---
> [!NOTE]
> A valid @Discord.Emoji format is Unicode-based. This means only
> something like `🙃` or `\U0001f643` would work, instead of
> `:upside_down:`.
>
> A Unicode-based emoji can be obtained by escaping with a `\` in
> front of the emote using the Discord chat client or by looking up on
> [Emojipedia](https://emojipedia.org).
This class represents a standard Unicode-based emoji. This type of emoji
can be created by passing the Unicode into the constructor.
---
uid: Discord.IEmote
example: [*content]
---
[!include[Example Section](IEmote.Inclusion.md)]
---
uid: Discord.Emoji
example: [*content]
---
[!include[Example Section](IEmote.Inclusion.md)]
---
uid: Discord.Emote
example: [*content]
---
[!include[Example Section](IEmote.Inclusion.md)]
---
uid: Discord.GuildEmote
example: [*content]
---
[!include[Example Section](IEmote.Inclusion.md)]

174
docs/_overwrites/Common/ObjectProperties.Overwrites.md Normal file
View File

@@ -0,0 +1,174 @@
---
uid: Discord.GuildChannelProperties
example: [*content]
---
The following example uses @Discord.IGuildChannel.ModifyAsync* to
apply changes specified in the properties,
```cs
var channel = _client.GetChannel(id) as IGuildChannel;
if (channel == null) return;
await channel.ModifyAsync(x =>
{
x.Name = "new-name";
x.Position = channel.Position - 1;
});
```
---
uid: Discord.TextChannelProperties
example: [*content]
---
The following example uses @Discord.ITextChannel.ModifyAsync* to
apply changes specified in the properties,
```cs
var channel = _client.GetChannel(id) as ITextChannel;
if (channel == null) return;
await channel.ModifyAsync(x =>
{
x.Name = "cool-guys-only";
x.Topic = "This channel is only for cool guys and adults!!!";
x.Position = channel.Position - 1;
x.IsNsfw = true;
});
```
---
uid: Discord.VoiceChannelProperties
example: [*content]
---
The following example uses @Discord.IVoiceChannel.ModifyAsync* to
apply changes specified in the properties,
```cs
var channel = _client.GetChannel(id) as IVoiceChannel;
if (channel == null) return;
await channel.ModifyAsync(x =>
{
x.UserLimit = 5;
});
```
---
uid: Discord.EmoteProperties
example: [*content]
---
The following example uses @Discord.IGuild.ModifyEmoteAsync* to
apply changes specified in the properties,
```cs
await guild.ModifyEmoteAsync(x =>
{
x.Name = "blobo";
});
```
---
uid: Discord.MessageProperties
example: [*content]
---
The following example uses @Discord.IUserMessage.ModifyAsync* to
apply changes specified in the properties,
```cs
var message = await channel.SendMessageAsync("boo");
await Task.Delay(TimeSpan.FromSeconds(1));
await message.ModifyAsync(x => x.Content = "boi");
```
---
uid: Discord.GuildProperties
example: [*content]
---
The following example uses @Discord.IGuild.ModifyAsync* to
apply changes specified in the properties,
```cs
var guild = _client.GetGuild(id);
if (guild == null) return;
await guild.ModifyAsync(x =>
{
x.Name = "VERY Fast Discord Running at Incredible Hihg Speed";
});
```
---
uid: Discord.RoleProperties
example: [*content]
---
The following example uses @Discord.IRole.ModifyAsync* to
apply changes specified in the properties,
```cs
var role = guild.GetRole(id);
if (role == null) return;
await role.ModifyAsync(x =>
{
x.Name = "cool boi";
x.Color = Color.Gold;
x.Hoist = true;
x.Mentionable = true;
});
```
---
uid: Discord.GuildUserProperties
example: [*content]
---
The following example uses @Discord.IGuildUser.ModifyAsync* to
apply changes specified in the properties,
```cs
var user = guild.GetUser(id);
if (user == null) return;
await user.ModifyAsync(x =>
{
x.Nickname = "I need healing";
});
```
---
uid: Discord.SelfUserProperties
example: [*content]
---
The following example uses @Discord.ISelfUser.ModifyAsync* to
apply changes specified in the properties,
```cs
await selfUser.ModifyAsync(x =>
{
x.Username = "Mercy";
});
```
---
uid: Discord.WebhookProperties
example: [*content]
---
The following example uses @Discord.IWebhook.ModifyAsync* to
apply changes specified in the properties,
```cs
await webhook.ModifyAsync(x =>
{
x.Name = "very fast fox";
x.ChannelId = newChannelId;
});
```

24
docs/_overwrites/Common/OverrideTypeReaderAttribute.Overwrites.md Normal file
View File

@@ -0,0 +1,24 @@
---
uid: Discord.Commands.OverrideTypeReaderAttribute
remarks: *content
---
This attribute is used to override a command parameter's type reading
behaviour. This may be useful when you have multiple custom
@Discord.Commands.TypeReader and would like to specify one.
---
uid: Discord.Commands.OverrideTypeReaderAttribute
examples: [*content]
---
The following example will override the @Discord.Commands.TypeReader
of @Discord.IUser to `MyUserTypeReader`.
```cs
public async Task PrintUserAsync(
[OverrideTypeReader(typeof(MyUserTypeReader))] IUser user)
{
//...
}
```

BIN
docs/_overwrites/Common/images/embed-example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

BIN
docs/_overwrites/Common/images/react-example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.8 KiB