From 94ca53ca3170ac525d9eb0a4f71769ad7dafb452 Mon Sep 17 00:00:00 2001
From: Still Hsu <341464@gmail.com>
Date: Fri, 15 Jun 2018 18:58:57 +0800
Subject: [PATCH] Improve precondition documentation

+ Add precondition usage sample
+ Add precondition group usage sample
+ Move precondition samples to its own sample folder
---
 docs/guides/commands/preconditions.md         | 27 ++++++++++++++++++-
 .../preconditions/group_precondition.cs       |  9 +++++++
 .../preconditions/precondition_usage.cs       |  3 +++
 .../{ => preconditions}/require_owner.cs      |  0
 4 files changed, 38 insertions(+), 1 deletion(-)
 create mode 100644 docs/guides/commands/samples/preconditions/group_precondition.cs
 create mode 100644 docs/guides/commands/samples/preconditions/precondition_usage.cs
 rename docs/guides/commands/samples/{ => preconditions}/require_owner.cs (100%)

diff --git a/docs/guides/commands/preconditions.md b/docs/guides/commands/preconditions.md
index 7fe6dd3a8..27fa1d20d 100644
--- a/docs/guides/commands/preconditions.md
+++ b/docs/guides/commands/preconditions.md
@@ -19,6 +19,31 @@ You may visit their respective API documentation to find out more.
 [PreconditionAttribute]: xref:Discord.Commands.PreconditionAttribute
 [ParameterPreconditionAttribute]: xref:Discord.Commands.ParameterPreconditionAttribute
 
+## Using Preconditions
+
+To use a precondition, simply apply any valid precondition candidate to
+a command method signature as an attribute.
+
+### Example - Using a Precondition
+
+[!code-csharp[Precondition usage](samples/preconditions/precondition_usage.cs)]
+
+### ORing Preconditions
+
+When writing commands, you may want to allow some of them to be
+executed when only some of the precondition checks are passed.
+
+This is where the [Group] property of a precondition attribute comes in
+handy. By assigning two or more preconditions to a group, the command
+system will allow the command to be executed when one of the
+precondition passes.
+
+#### Example - ORing Preconditions
+
+[!code-csharp[OR Precondition](samples/preconditions/group_precondition.cs)]
+
+[Group]: xref:Discord.Commands.PreconditionAttribute.Group
+
 ## Bundled Preconditions
 
 @Discord.Commands ships with several bundled Preconditions for you
@@ -51,7 +76,7 @@ necessary.
 
 ### Example - Creating a Custom Precondition
 
-[!code-csharp[Custom Precondition](samples/require_owner.cs)]
+[!code-csharp[Custom Precondition](samples/preconditions/require_owner.cs)]
 
 [CheckPermissionsAsync]: xref:Discord.Commands.PreconditionAttribute.CheckPermissionsAsync*
 [PreconditionResult.FromSuccess]: xref:Discord.Commands.PreconditionResult.FromSuccess*
diff --git a/docs/guides/commands/samples/preconditions/group_precondition.cs b/docs/guides/commands/samples/preconditions/group_precondition.cs
new file mode 100644
index 000000000..bae102b9a
--- /dev/null
+++ b/docs/guides/commands/samples/preconditions/group_precondition.cs
@@ -0,0 +1,9 @@
+// The following example only requires the user to either have the
+// Administrator permission in this guild or own the bot application.
+[RequireUserPermission(GuildPermission.Administrator, Group = "Permission")]
+[RequireOwner(Group = "Permission")]
+public class AdminModule : ModuleBase<SocketCommandContext>
+{
+    [Command("ban")]
+    public Task BanAsync(IUser user) => Context.Guild.AddBanAsync(user);
+}
\ No newline at end of file
diff --git a/docs/guides/commands/samples/preconditions/precondition_usage.cs b/docs/guides/commands/samples/preconditions/precondition_usage.cs
new file mode 100644
index 000000000..eacee932a
--- /dev/null
+++ b/docs/guides/commands/samples/preconditions/precondition_usage.cs
@@ -0,0 +1,3 @@
+[RequireOwner]
+[Command("echo")]
+public Task EchoAsync(string input) => ReplyAsync(input);
\ No newline at end of file
diff --git a/docs/guides/commands/samples/require_owner.cs b/docs/guides/commands/samples/preconditions/require_owner.cs
similarity index 100%
rename from docs/guides/commands/samples/require_owner.cs
rename to docs/guides/commands/samples/preconditions/require_owner.cs