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

Improve library documentation (#826)

Browse Source 
* Improve the Command Service documentation

The following changes have been added to this PR:
•	Fix minor grammatical errors.
•	Capitalize terms such as Commands, Modules and such, as the context is specific to the lib.
•	Wrap methods and properties in code blocks.

The docs page currently has several issues that remains to be fixed.

1. 
```md
>[!WARNING]
>This article is out of date and has not been rewritten yet.
Information is not guaranteed to be accurate.
```

The docs doesn't necessarily seem "out of date" as the warning claims. The basics seem pretty relevant to the latest version of the lib.

2.
>“To manually load a module, invoke [CommandService.AddModuleAsync], by passing in the generic type of your module and optionally, a dependency map.”

The latter part of the sentence seems off. Where should the user pass the dependency map to? It seems to suggest that `AddModuleAsync` has an argument to pass the dependency to. If it is referring to `AddModuleAsync(Type type)`, then I feel like it should be clarified here - or perhaps change the wording of the sentence.

3.
>“First, you need to create an @System.IServiceProvider You may create your own IServiceProvider if you wish.” 

Any mention of @System.IServiceProvider is currently broken on the docs.

4.
>“Submodules are Modules that reside within another one. Typically, submodules are used to create nested groups (although not required to create nested groups).”

Clarification on the part after "although?"

5.
>“Finally, pass the map into the LoadAssembly method. Your modules will automatically be loaded with this dependency map.”

Where is this `LoadAssembly` method?

6.
```md
>[!NOTE]
>Preconditions can be applied to Modules, Groups, or Commands.
```

The docs should mention `ParameterPreconditionAttribute`'s existence.

* Update line breaks to comply with docs standard

* Change "you should..." to "instead, ..."

* Trim trailing spaces

* Change "inherits" to "inherit"

* Fix Context warning note and add ReplyAsync xref

* Fix broken xrefs

* Fix [Command Service] xref

* Fix consistency between TypeReaders and Preconditions returns

* Add missing semi-colons in ServiceProvider sample

* Change CommandContext to SocketCommandContext & change variable naming

* Cleanup TypeReader section

* Wrap [DontInject] in code block

* Fix commands docs linking in intro

* Improve Getting Started - Installation

- Fix character misalignment to comply with docs standard.
- Fix image numbering issues by moving the tooltips above some of the steps.
- Add codeblocks to search terms like `Discord.Net`.
- Remove broken `addons` reference.
- Specify `.NET 4.6.1` as `.NET Framework 4.6.1`.
- Minor cross-reference cleanup.

* Fix Getting Started - Intro

- Minor grammartical fixes.
- Wrap mentions of the methods, properties, and events in code block.
- Replace `Discord.Net` to `Discord.NET`.
- Fix steps numbering under `Creating a Discord Bot` and `Adding your bot to a server`.
- Change `Task-based Asynchronous Pattern ([TAP])` linking to mark the entire term instead.
- Change code block of `Pong!` to quotation mark instead.

* Fix cross references in Sending Voice

* Mention parameter precondition attribute

* Change `Discord.NET` to `Discord.Net` for consistency

* Wrap project names in code blocks & minor fixes in Terminology

* Change `add-ons` to `addons` for consistency

* Fix cross references in Logging

* Fix minor grammatical issues in "Working with Events"

* Missed a tilda

* Remove out-of-date warning in Commands

* Minor grammatical fixes for Entities

* Fix broken xref in Logging

* Adjust service collection sample

...according to f89aecb7bf (r141530227)

* Update Command Handler sample

- Update Main for C# 7.1.
- Inject CommandService and DiscordSocketClient into the service collection.
- Add Async suffix to asynchronous methods.

* Minor grammatical fixes in Events

* Revert 2 incorrect grammar corrections

* Revert async Main sample

* Add hardcode token notice in sample

* Fix missing method for Command Handler

* Modify module samples to use SocketCommandContext instead

* Emphasize CommandContext and SocketCommandContext

* Fix formatting for module sample

* Add SocketCommandContext for Groups sample

* Remove comma

* Fix DepMap sample formatting

* Replace [DontInject] with DontInjectAttribute with cross reference

* Remove connection logic note

There is no reason that this note should still be here since Ready event exists.

* Add a new warning message informing the users the existence of CommandService

* Make command handler private

excellent change
This commit is contained in:
Hsu Still
2017-10-04 04:48:05 +08:00
committed by Christopher F
parent e00f17fe55
commit 22d79c1004
14 changed files with 393 additions and 340 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/guides/getting_started/terminology.md
View File

@@ -7,32 +7,34 @@ title: Terminology
## Preface
Most terms for objects remain the same between 0.9 and 1.0. The major difference is that the ``Server`` is now called ``Guild``, to stay in line with Discord internally
Most terms for objects remain the same between 0.9 and 1.0. The major
difference is that the ``Server`` is now called ``Guild`` to stay in
line with Discord internally.
## Implementation Specific Entities
Discord.Net 1.0 is split into a core library, and three different
implementations - Discord.Net.Core, Discord.Net.Rest, Discord.Net.Rpc,
and Discord.Net.WebSockets.
Discord.Net 1.0 is split into a core library and three different
implementations - `Discord.Net.Core`, `Discord.Net.Rest`,
`Discord.Net.Rpc`, and `Discord.Net.WebSockets`.
As a bot developer, you will only need to use Discord.Net.WebSockets,
As a bot developer, you will only need to use `Discord.Net.WebSockets`,
but you should be aware of the differences between them.
`Discord.Net.Core` provides a set of interfaces that model Discord's
`Discord.Net.Core` provides a set of interfaces that models Discord's
API. These interfaces are consistent throughout all implementations of
Discord.Net, and if you are writing an implementation-agnostic library
or addon, you can rely on the core interfaces to ensure that your
addon will run on all platforms.
`Discord.Net.Rest` provides a set of concrete classes to be used
**strictly** with the REST portion of Discord's API. Entities in
this implementation are prefixed with `Rest`, e.g. `RestChannel`.
**strictly** with the REST portion of Discord's API. Entities in this
implementation are prefixed with `Rest` (e.g. `RestChannel`).
`Discord.Net.Rpc` provides a set of concrete classes that are used with
Discord's RPC API. Entities in this implementation are prefixed with
`Rpc`, e.g. `RpcChannel`.
`Discord.Net.Rpc` provides a set of concrete classes that are used
with Discord's RPC API. Entities in this implementation are prefixed
with `Rpc` (e.g. `RpcChannel`).
`Discord.Net.WebSocket` provides a set of concrete classes that are used
primarily with Discord's WebSocket API, or entities that are kept in
cache. When developing bots, you will be using this implementation. All
entities are prefixed with `Socket`, e.g. `SocketChannel`.
`Discord.Net.WebSocket` provides a set of concrete classes that are
used primarily with Discord's WebSocket API or entities that are kept
in cache. When developing bots, you will be using this implementation.
All entities are prefixed with `Socket` (e.g. `SocketChannel`).