diff --git a/docs/_overwrites/Commands/ICommandContext.Inclusion.md b/docs/_overwrites/Commands/ICommandContext.Inclusion.md index c99148db7..4c1257b23 100644 --- a/docs/_overwrites/Commands/ICommandContext.Inclusion.md +++ b/docs/_overwrites/Commands/ICommandContext.Inclusion.md @@ -1,5 +1,5 @@ An example of how this class is used the command system can be seen below: -[!code[Sample module](../../guides/commands/samples/empty-module.cs)] -[!code[Command handler](../../guides/commands/samples/command_handler.cs)] \ No newline at end of file +[!code[Sample module](../../guides/commands/samples/intro/empty-module.cs)] +[!code[Command handler](../../guides/commands/samples/intro/command_handler.cs)] \ No newline at end of file diff --git a/docs/guides/commands/dependency-injection.md b/docs/guides/commands/dependency-injection.md index 6c748b8dc..5dc5b02d2 100644 --- a/docs/guides/commands/dependency-injection.md +++ b/docs/guides/commands/dependency-injection.md @@ -19,7 +19,7 @@ DI when writing your modules. ### Example - Setting up Injection -[!code-csharp[IServiceProvider Setup](samples/dependency_map_setup.cs)] +[!code-csharp[IServiceProvider Setup](samples/dependency-injection/dependency_map_setup.cs)] ## Usage in Modules @@ -41,6 +41,7 @@ manner. ### Example - Injection in Modules -[!code-csharp[IServiceProvider in Modules](samples/dependency_module.cs)] +[!code-csharp[Injection Modules](samples/dependency-injection/dependency_module.cs)] +[!code-csharp[Disallow Dependency Injection](samples/dependency-injection/dependency_module_noinject.cs)] [DontInjectAttribute]: xref:Discord.Commands.DontInjectAttribute \ No newline at end of file diff --git a/docs/guides/commands/intro.md b/docs/guides/commands/intro.md index e2fad73e8..573ba4059 100644 --- a/docs/guides/commands/intro.md +++ b/docs/guides/commands/intro.md @@ -23,7 +23,7 @@ minimum. > look over the properties in [CommandServiceConfig] and their default > values. -[!code-csharp[Command Handler](samples/command_handler.cs)] +[!code-csharp[Command Handler](samples/intro/command_handler.cs)] [Command Service]: xref:Discord.Commands.CommandService [CommandServiceConfig]: xref:Discord.Commands.CommandServiceConfig @@ -56,7 +56,7 @@ your module must: By now, your module should look like this: -[!code-csharp[Empty Module](samples/empty-module.cs)] +[!code-csharp[Empty Module](samples/intro/empty-module.cs)] > [!NOTE] > [ModuleBase] is an `abstract` class, meaning that you may extend it @@ -162,7 +162,7 @@ accessing the channel through the [Context] and sending a message. > [!TIP] > At this point, your module should look comparable to this example: -> [!code-csharp[Example Module](samples/module.cs)] +> [!code-csharp[Example Module](samples/intro/module.cs)] #### Loading Modules Automatically @@ -218,4 +218,4 @@ Submodules are "modules" that reside within another one. Typically, submodules are used to create nested groups (although not required to create nested groups). -[!code-csharp[Groups and Submodules](samples/groups.cs)] \ No newline at end of file +[!code-csharp[Groups and Submodules](samples/intro/groups.cs)] \ No newline at end of file diff --git a/docs/guides/commands/post-execution.md b/docs/guides/commands/post-execution.md index 267f84b8f..76bade254 100644 --- a/docs/guides/commands/post-execution.md +++ b/docs/guides/commands/post-execution.md @@ -13,7 +13,7 @@ for you to work with. If you recall, in the [Command Guide], we have shown the following example for executing and handling commands, -[!code[Command Handler](samples/command_handler.cs)] +[!code[Command Handler](samples/intro/command_handler.cs)] You may notice that after we perform [ExecuteAsync], we store the result and print it to the chat, essentially creating the most @@ -21,7 +21,7 @@ fundamental form of a post-execution handler. With this in mind, we could start doing things like the following, -[!code[Basic Command Handler](samples/post-execution_basic.cs)] +[!code[Basic Command Handler](samples/post-execution/post-execution_basic.cs)] However, this may not always be preferred, because you are creating your post-execution logic *with* the essential command @@ -45,7 +45,7 @@ about this event is that it is not prone to `RunMode.Async`'s Thus, we can begin working on code such as: -[!code[CommandExecuted demo](samples/command_executed_demo.cs)] +[!code[CommandExecuted demo](samples/post-execution/command_executed_demo.cs)] So now we have a streamlined post-execution pipeline, great! What's next? We can take this further by using [RuntimeResult]. @@ -69,7 +69,7 @@ class. The following creates a bare-minimum required for a sub-class of `RuntimeResult`, -[!code[Base Use](samples/customresult_base.cs)] +[!code[Base Use](samples/post-execution/customresult_base.cs)] The sky is the limit from here. You can add any additional information you would like regarding the execution result. @@ -78,7 +78,7 @@ For example, you may want to add your result type or other helpful information regarding the execution, or something simple like static methods to help you create return types easily. -[!code[Extended Use](samples/customresult_extended.cs)] +[!code[Extended Use](samples/post-execution/customresult_extended.cs)] After you're done creating your [RuntimeResult], you can implement it in your command by marking the command return type to @@ -91,11 +91,11 @@ implement it in your command by marking the command return type to Here's an example of a command that utilizes such logic: -[!code[Usage](samples/customresult_usage.cs)] +[!code[Usage](samples/post-execution/customresult_usage.cs)] And now we can check for it in our [CommandExecuted] handler: -[!code[Usage](samples/command_executed_adv_demo.cs)] +[!code[Usage](samples/post-execution/command_executed_adv_demo.cs)] ## CommandService.Log Event @@ -110,7 +110,7 @@ as a [CommandException] type. The [CommandException] class allows us to access the exception thrown, as well as the context of the command. -[!code[Logger Sample](samples/command_exception_log.cs)] +[!code[Logger Sample](samples/post-execution/command_exception_log.cs)] [CommandException]: xref:Discord.Commands.CommandException [LogMessage.Exception]: xref:Discord.LogMessage.Exception diff --git a/docs/guides/commands/samples/dependency_map_setup.cs b/docs/guides/commands/samples/dependency-injection/dependency_map_setup.cs similarity index 100% rename from docs/guides/commands/samples/dependency_map_setup.cs rename to docs/guides/commands/samples/dependency-injection/dependency_map_setup.cs diff --git a/docs/guides/commands/samples/dependency-injection/dependency_module.cs b/docs/guides/commands/samples/dependency-injection/dependency_module.cs new file mode 100644 index 000000000..f0625e503 --- /dev/null +++ b/docs/guides/commands/samples/dependency-injection/dependency_module.cs @@ -0,0 +1,37 @@ +// After setting up dependency injection, modules will need to request +// the dependencies to let the library know to pass +// them along during execution. + +// Dependency can be injected in two ways with Discord.Net. +// You may inject any required dependencies via... +// the module constructor +// -or- +// public settable properties + +// Injection via constructor +public class DatabaseModule : ModuleBase +{ + private readonly DatabaseService _database; + public DatabaseModule(DatabaseService database) + { + _database = database; + } + + [Command("read")] + public async Task ReadFromDbAsync() + { + await ReplyAsync(_database.GetData()); + } +} + +// Injection via public settable properties +public class DatabaseModule : ModuleBase +{ + public DatabaseService DbService { get; set; } + + [Command("read")] + public async Task ReadFromDbAsync() + { + await ReplyAsync(_database.GetData()); + } +} \ No newline at end of file diff --git a/docs/guides/commands/samples/dependency-injection/dependency_module_noinject.cs b/docs/guides/commands/samples/dependency-injection/dependency_module_noinject.cs new file mode 100644 index 000000000..48cd52308 --- /dev/null +++ b/docs/guides/commands/samples/dependency-injection/dependency_module_noinject.cs @@ -0,0 +1,29 @@ +// Sometimes injecting dependencies automatically with the provided +// methods in the prior example may not be desired. + +// You may explicitly tell Discord.Net to **not** inject the properties +// by either... +// restricting the access modifier +// -or- +// applying DontInjectAttribute to the property + +// Restricting the access modifier of the property +public class ImageModule : ModuleBase +{ + public ImageService ImageService { get; } + public ImageModule() + { + ImageService = new ImageService(); + } +} + +// Applying DontInjectAttribute +public class ImageModule : ModuleBase +{ + [DontInject] + public ImageService ImageService { get; set; } + public ImageModule() + { + ImageService = new ImageService(); + } +} diff --git a/docs/guides/commands/samples/dependency_module.cs b/docs/guides/commands/samples/dependency_module.cs deleted file mode 100644 index 3c9b51d7d..000000000 --- a/docs/guides/commands/samples/dependency_module.cs +++ /dev/null @@ -1,30 +0,0 @@ -public class DatabaseModule : ModuleBase -{ - private readonly DatabaseService _database; - - // Dependencies can be injected via the constructor - public DatabaseModule(DatabaseService database) - { - _database = database; - } - - [Command("read")] - public async Task ReadFromDbAsync() - { - await ReplyAsync(_database.GetData()); - } -} - -public class MixModule : ModuleBase -{ - // Public settable properties will be injected - public AnnounceService AnnounceService { get; set; } - - // Public properties without setters will not be injected - public ImageService ImageService { get; } - - // Public properties annotated with [DontInject] will not - // be injected - [DontInject] - public NotificationService NotificationService { get; set; } -} \ No newline at end of file diff --git a/docs/guides/commands/samples/command_handler.cs b/docs/guides/commands/samples/intro/command_handler.cs similarity index 100% rename from docs/guides/commands/samples/command_handler.cs rename to docs/guides/commands/samples/intro/command_handler.cs diff --git a/docs/guides/commands/samples/empty-module.cs b/docs/guides/commands/samples/intro/empty-module.cs similarity index 100% rename from docs/guides/commands/samples/empty-module.cs rename to docs/guides/commands/samples/intro/empty-module.cs diff --git a/docs/guides/commands/samples/groups.cs b/docs/guides/commands/samples/intro/groups.cs similarity index 100% rename from docs/guides/commands/samples/groups.cs rename to docs/guides/commands/samples/intro/groups.cs diff --git a/docs/guides/commands/samples/module.cs b/docs/guides/commands/samples/intro/module.cs similarity index 100% rename from docs/guides/commands/samples/module.cs rename to docs/guides/commands/samples/intro/module.cs diff --git a/docs/guides/commands/samples/command_exception_log.cs b/docs/guides/commands/samples/post-execution/command_exception_log.cs similarity index 100% rename from docs/guides/commands/samples/command_exception_log.cs rename to docs/guides/commands/samples/post-execution/command_exception_log.cs diff --git a/docs/guides/commands/samples/command_executed_adv_demo.cs b/docs/guides/commands/samples/post-execution/command_executed_adv_demo.cs similarity index 100% rename from docs/guides/commands/samples/command_executed_adv_demo.cs rename to docs/guides/commands/samples/post-execution/command_executed_adv_demo.cs diff --git a/docs/guides/commands/samples/command_executed_demo.cs b/docs/guides/commands/samples/post-execution/command_executed_demo.cs similarity index 100% rename from docs/guides/commands/samples/command_executed_demo.cs rename to docs/guides/commands/samples/post-execution/command_executed_demo.cs diff --git a/docs/guides/commands/samples/customresult_base.cs b/docs/guides/commands/samples/post-execution/customresult_base.cs similarity index 100% rename from docs/guides/commands/samples/customresult_base.cs rename to docs/guides/commands/samples/post-execution/customresult_base.cs diff --git a/docs/guides/commands/samples/customresult_extended.cs b/docs/guides/commands/samples/post-execution/customresult_extended.cs similarity index 100% rename from docs/guides/commands/samples/customresult_extended.cs rename to docs/guides/commands/samples/post-execution/customresult_extended.cs diff --git a/docs/guides/commands/samples/customresult_usage.cs b/docs/guides/commands/samples/post-execution/customresult_usage.cs similarity index 100% rename from docs/guides/commands/samples/customresult_usage.cs rename to docs/guides/commands/samples/post-execution/customresult_usage.cs diff --git a/docs/guides/commands/samples/post-execution_basic.cs b/docs/guides/commands/samples/post-execution/post-execution_basic.cs similarity index 100% rename from docs/guides/commands/samples/post-execution_basic.cs rename to docs/guides/commands/samples/post-execution/post-execution_basic.cs diff --git a/docs/guides/commands/samples/typereader-register.cs b/docs/guides/commands/samples/typereaders/typereader-register.cs similarity index 100% rename from docs/guides/commands/samples/typereader-register.cs rename to docs/guides/commands/samples/typereaders/typereader-register.cs diff --git a/docs/guides/commands/samples/typereader.cs b/docs/guides/commands/samples/typereaders/typereader.cs similarity index 100% rename from docs/guides/commands/samples/typereader.cs rename to docs/guides/commands/samples/typereaders/typereader.cs diff --git a/docs/guides/commands/typereaders.md b/docs/guides/commands/typereaders.md index a502fb3c8..d11e42425 100644 --- a/docs/guides/commands/typereaders.md +++ b/docs/guides/commands/typereaders.md @@ -18,8 +18,9 @@ By default, the following Types are supported arguments: * `ulong`/`long` * `float`, `double`, `decimal` * `string` +* `enum` * `DateTime`/`DateTimeOffset`/`TimeSpan` -* `Nullable` where applicible +* `Nullable` where applicable * Any implementation of `IChannel`/`IMessage`/`IUser`/`IRole` ## Creating a Type Reader @@ -49,7 +50,7 @@ necessary. ### Example - Creating a Type Reader -[!code-csharp[TypeReaders](samples/typereader.cs)] +[!code-csharp[TypeReaders](samples/typereaders/typereader.cs)] ## Registering a Type Reader @@ -66,4 +67,4 @@ To register a TypeReader, invoke [CommandService.AddTypeReader]. ### Example - Adding a Type Reader -[!code-csharp[Adding TypeReaders](samples/typereader-register.cs)] \ No newline at end of file +[!code-csharp[Adding TypeReaders](samples/typereaders/typereader-register.cs)] \ No newline at end of file