From 9b5307ba2bbcf90944ee0c52b04e956fbf5b9242 Mon Sep 17 00:00:00 2001
From: Dragory <2606411+Dragory@users.noreply.github.com>
Date: Fri, 25 Oct 2019 23:14:21 +0300
Subject: [PATCH] Documentation work. Add command info for all Utility plugin
 commands.

---
 dashboard/src/components/Expandable.vue  |  44 ++++----
 dashboard/src/components/docs/Plugin.vue |  58 ++++++----
 dashboard/src/store/docs.ts              |   9 ++
 src/plugins/Utility.ts                   | 136 +++++++++++++++++++++--
 src/plugins/ZeppelinPlugin.ts            |   2 +
 5 files changed, 197 insertions(+), 52 deletions(-)

diff --git a/dashboard/src/components/Expandable.vue b/dashboard/src/components/Expandable.vue
index 4728570c..455db34c 100644
--- a/dashboard/src/components/Expandable.vue
+++ b/dashboard/src/components/Expandable.vue
@@ -22,35 +22,32 @@
 <style scoped>
   @import "../style/components.pcss";
 
-  :root {
+  .expandable {
     --animation-time: 400ms;
     --target-height: auto;
-  }
+    transition: box-shadow var(--animation-time); /* hi */
 
-  .expandable {
-    transition: box-shadow var(--animation-time);
-  }
+    & > .title {
+      &:hover {
+        & .title-text {
+          @apply underline;
+        }
+      }
 
-  .title {
-    &:hover {
-      & .title-text {
-        @apply underline;
+      .icon {
+        transition: transform var(--animation-time);
+        transform-origin: 50% 60%;
+      }
+
+      .icon-open {
+        transform: rotate(179deg);
       }
     }
-  }
 
-  .icon {
-    transition: transform var(--animation-time);
-    transform-origin: 50% 60%;
-  }
-
-  .icon-open {
-    transform: rotate(179deg);
-  }
-
-  .content {
-    overflow: hidden;
-    display: none;
+    & > .content {
+      overflow: hidden;
+      display: none;
+    }
   }
 
   @keyframes open {
@@ -72,7 +69,8 @@
   }
 
   .inline-code,
-  code:not([class]) {
+  code:not([class]),
+  >>> code:not([class]) {
     @apply bg-gray-900;
   }
 
diff --git a/dashboard/src/components/docs/Plugin.vue b/dashboard/src/components/docs/Plugin.vue
index ca71a604..40249b1f 100644
--- a/dashboard/src/components/docs/Plugin.vue
+++ b/dashboard/src/components/docs/Plugin.vue
@@ -34,24 +34,44 @@
       <div v-if="data.commands.length">
         <h2 id="commands">Commands</h2>
         <div v-for="command in data.commands" class="mb-4">
-          <h3 class="text-xl">!{{ command.trigger }}</h3>
-          <div v-if="command.config.extra.requiredPermission">
-            Permission: <code class="inline-code">{{ command.config.extra.requiredPermission }}</code>
-          </div>
-          <div v-if="command.config.extra.info && command.config.extra.info.basicUsage">
-            Basic usage: <code class="inline-code">{{ command.config.extra.info.basicUsage }}</code>
-          </div>
-          <div v-if="command.config.aliases && command.config.aliases.length">
-            Shortcut:
-            <code class="inline-code" style="margin-right: 4px" v-for="alias in command.config.aliases">!{{ alias }}</code>
-          </div>
+          <h3 class="text-xl mb-0">
+            !{{ command.trigger }}
+            <span v-for="alias in command.config.aliases"> <span class="text-gray-600">/</span> !{{ alias }}</span>
+          </h3>
+          <MarkdownBlock v-if="command.config.extra.info && command.config.extra.info.description"
+                         :content="command.config.extra.info.description"
+                         class="content">
+          </MarkdownBlock>
 
-          <MarkdownBlock v-if="command.config.extra.info && command.config.extra.info.description" :content="command.config.extra.info.description" class="content"></MarkdownBlock>
+          <div v-bind:class="{'-mt-2': command.config.extra.info && command.config.extra.info.description}">
+            <div v-if="command.config.extra.info && command.config.extra.info.basicUsage">
+              <span class="font-semibold">Basic usage:</span> <code class="inline-code">{{ command.config.extra.info.basicUsage }}</code>
+            </div>
+          </div>
 
           <Expandable class="mt-4">
             <template v-slot:title>Additional information</template>
             <template v-slot:content>
-              Signatures:
+              <div v-if="command.config.extra.info && command.config.extra.info.usageGuide">
+                <div class="font-semibold">Usage guide:</div>
+                <MarkdownBlock :content="command.config.extra.info.usageGuide"
+                               class="content">
+                </MarkdownBlock>
+              </div>
+
+              <div v-if="command.config.extra.info && command.config.extra.info.examples">
+                <div class="font-semibold">Examples:</div>
+                <MarkdownBlock :content="command.config.extra.info.examples"
+                               class="content">
+                </MarkdownBlock>
+              </div>
+
+              <p v-if="command.config.extra.requiredPermission">
+                <span class="font-semibold">Permission:</span>
+                <code class="inline-code">{{ command.config.extra.requiredPermission }}</code>
+              </p>
+
+              <span class="font-semibold">Signatures:</span>
               <ul>
                 <li>
                   <code class="inline-code bg-gray-900">
@@ -62,13 +82,13 @@
               </ul>
 
               <div class="mt-2" v-if="command.parameters.length">
-                Command arguments:
+                <span class="font-semibold">Command arguments:</span>
                 <ul>
                   <li v-for="param in command.parameters">
                     <code>{{ renderParameter(param) }}</code>
                     <router-link :to="'/docs/reference/argument-types#' + (param.type || 'string')">{{ param.type || 'string' }}</router-link>
-                    <MarkdownBlock v-if="command.config.info && command.config.info.parameterDescriptions && command.config.info.parameterDescriptions[param.name]"
-                                   :content="command.config.info.parameterDescriptions[param.name]"
+                    <MarkdownBlock v-if="command.config.extra.info && command.config.extra.info.parameterDescriptions && command.config.extra.info.parameterDescriptions[param.name]"
+                                   :content="command.config.extra.info.parameterDescriptions[param.name]"
                                    class="content">
                     </MarkdownBlock>
                   </li>
@@ -76,13 +96,13 @@
               </div>
 
               <div class="mt-2" v-if="command.config.options && command.config.options.length">
-                Options:
+                <span class="font-semibold">Options:</span>
                 <ul>
                   <li v-for="opt in command.config.options">
                     <code>{{ renderOption(opt) }}</code>
                     <router-link :to="'/docs/reference/argument-types#' + (opt.type || 'string')">{{ opt.type || 'string' }}</router-link>
-                    <MarkdownBlock v-if="command.config.info && command.config.info.optionDescriptions && command.config.info.optionDescriptions[opt.name]"
-                                   :content="command.config.info.optionDescriptions[opt.name]"
+                    <MarkdownBlock v-if="command.config.extra.info && command.config.extra.info.optionDescriptions && command.config.extra.info.optionDescriptions[opt.name]"
+                                   :content="command.config.extra.info.optionDescriptions[opt.name]"
                                    class="content">
                     </MarkdownBlock>
                   </li>
diff --git a/dashboard/src/store/docs.ts b/dashboard/src/store/docs.ts
index 44203c8e..49afa004 100644
--- a/dashboard/src/store/docs.ts
+++ b/dashboard/src/store/docs.ts
@@ -34,6 +34,15 @@ export const DocsStore: Module<DocsState, RootState> = {
       if (state.plugins[name]) return;
 
       const data = await get(`docs/plugins/${name}`);
+      if (data && data.commands) {
+        data.commands.sort((a, b) => {
+          const aName = a.trigger.toLowerCase();
+          const bName = b.trigger.toLowerCase();
+          if (aName > bName) return 1;
+          if (aName < bName) return -1;
+          return 0;
+        });
+      }
       commit("setPluginData", { name, data });
     },
   },
diff --git a/src/plugins/Utility.ts b/src/plugins/Utility.ts
index 8709e4d0..d9a62126 100644
--- a/src/plugins/Utility.ts
+++ b/src/plugins/Utility.ts
@@ -50,7 +50,7 @@ import { CaseTypes } from "../data/CaseTypes";
 import { SavedMessage } from "../data/entities/SavedMessage";
 import { GuildSavedMessages } from "../data/GuildSavedMessages";
 import { GuildArchives } from "../data/GuildArchives";
-import { ZeppelinPlugin } from "./ZeppelinPlugin";
+import { CommandInfo, trimPluginDescription, ZeppelinPlugin } from "./ZeppelinPlugin";
 import { getCurrentUptime } from "../uptime";
 import LCL from "last-commit-log";
 import * as t from "io-ts";
@@ -183,6 +183,12 @@ export class UtilityPlugin extends ZeppelinPlugin<TConfigSchema> {
         type: "string",
       },
     ],
+    extra: {
+      info: <CommandInfo>{
+        description: "List all roles or roles matching a search",
+        basicUsage: "!roles mod",
+      },
+    },
   })
   @d.permission("can_roles")
   async rolesCmd(msg: Message, args: { search?: string; counts?: boolean; sort?: string }) {
@@ -274,7 +280,14 @@ export class UtilityPlugin extends ZeppelinPlugin<TConfigSchema> {
     }
   }
 
-  @d.command("level", "[member:resolvedMember]")
+  @d.command("level", "[member:resolvedMember]", {
+    extra: {
+      info: <CommandInfo>{
+        description: "Show the permission level of a user",
+        basicUsage: "!level 106391128718245888",
+      },
+    },
+  })
   @d.permission("can_level")
   async levelCmd(msg: Message, args: { member?: Member }) {
     const member = args.member || msg.member;
@@ -382,6 +395,21 @@ export class UtilityPlugin extends ZeppelinPlugin<TConfigSchema> {
         isSwitch: true,
       },
     ],
+    extra: {
+      info: <CommandInfo>{
+        description: "Search server members",
+        basicUsage: "!search dragory",
+        optionDescriptions: {
+          role:
+            "Only include members with a specific role. Multiple roles can be specified by separating them with a comma.",
+          voice: "Only include members currently in a voice channel",
+          sort:
+            "Change how the results are sorted. Possible values are 'id' and 'name'. Prefix with a dash, e.g. '-id', to reverse sorting.",
+          "case-sensitive": "By default, the search is case-insensitive. Use this to make it case-sensitive instead.",
+          export: "If set, the full search results are exported as an archive",
+        },
+      },
+    },
   })
   @d.permission("can_search")
   async searchCmd(
@@ -567,6 +595,29 @@ export class UtilityPlugin extends ZeppelinPlugin<TConfigSchema> {
         shortcut: "i",
       },
     ],
+    extra: {
+      info: <CommandInfo>{
+        description: "Remove a number of recent messages",
+        basicUsage: "!clean 20",
+        examples: trimPluginDescription(`
+          To clean 20 messages from a specific user:  
+          \`!clean -user 106391128718245888 20\`
+          
+          To clean messages from another channel:
+          \`!clean -channel #other-channel 20\`
+        `),
+        parameterDescriptions: {
+          count: "Number of messages to remove",
+        },
+        optionDescriptions: {
+          user: "Only remove messages from the specified user",
+          channel:
+            "By default, messages are removed from the channel where the command is used. You can clean a different channel by specifying it with this option.",
+          bots: "Only remove messages sent by bots",
+          "has-invites": "Only remove messages that contain invites",
+        },
+      },
+    },
   })
   @d.permission("can_clean")
   async cleanCmd(
@@ -651,7 +702,14 @@ export class UtilityPlugin extends ZeppelinPlugin<TConfigSchema> {
     }
   }
 
-  @d.command("info", "[user:resolvedUserLoose]")
+  @d.command("info", "[user:resolvedUserLoose]", {
+    extra: {
+      info: <CommandInfo>{
+        description: "Show basic information about a user",
+        basicUsage: "!info 106391128718245888",
+      },
+    },
+  })
   @d.permission("can_info")
   async infoCmd(msg: Message, args: { user?: User | UnknownUser }) {
     const user = args.user || msg.author;
@@ -751,6 +809,12 @@ export class UtilityPlugin extends ZeppelinPlugin<TConfigSchema> {
 
   @d.command("nickname reset", "<member:resolvedMember>", {
     aliases: ["nick reset"],
+    extra: {
+      info: <CommandInfo>{
+        description: "Reset a member's nickname to their username",
+        basicUsage: "!nickname reset 106391128718245888",
+      },
+    },
   })
   @d.permission("can_nickname")
   async nicknameResetCmd(msg: Message, args: { member: Member }) {
@@ -773,6 +837,12 @@ export class UtilityPlugin extends ZeppelinPlugin<TConfigSchema> {
 
   @d.command("nickname", "<member:resolvedMember> <nickname:string$>", {
     aliases: ["nick"],
+    extra: {
+      info: <CommandInfo>{
+        description: "Set a member's nickname",
+        basicUsage: "!nickname 106391128718245888 Drag",
+      },
+    },
   })
   @d.permission("can_nickname")
   async nicknameCmd(msg: Message, args: { member: Member; nickname: string }) {
@@ -803,7 +873,14 @@ export class UtilityPlugin extends ZeppelinPlugin<TConfigSchema> {
     );
   }
 
-  @d.command("server")
+  @d.command("server", "", {
+    extra: {
+      info: <CommandInfo>{
+        description: "Show information about the server",
+        basicUsage: "!server",
+      },
+    },
+  })
   @d.permission("can_server")
   async serverCmd(msg: Message) {
     await this.guild.fetchAllMembers();
@@ -874,7 +951,13 @@ export class UtilityPlugin extends ZeppelinPlugin<TConfigSchema> {
     msg.channel.createMessage({ embed });
   }
 
-  @d.command("ping")
+  @d.command("ping", "", {
+    extra: {
+      info: <CommandInfo>{
+        description: "Test the bot's ping to the Discord API",
+      },
+    },
+  })
   @d.permission("can_ping")
   async pingCmd(msg: Message) {
     const times = [];
@@ -913,7 +996,14 @@ export class UtilityPlugin extends ZeppelinPlugin<TConfigSchema> {
     this.bot.deleteMessages(messages[0].channel.id, messages.map(m => m.id)).catch(noop);
   }
 
-  @d.command("source", "<messageId:string>")
+  @d.command("source", "<messageId:string>", {
+    extra: {
+      info: <CommandInfo>{
+        description: "View the message source of the specified message id",
+        basicUsage: "!source 534722219696455701",
+      },
+    },
+  })
   @d.permission("can_source")
   async sourceCmd(msg: Message, args: { messageId: string }) {
     const savedMessage = await this.savedMessages.find(args.messageId);
@@ -930,7 +1020,14 @@ export class UtilityPlugin extends ZeppelinPlugin<TConfigSchema> {
     msg.channel.createMessage(`Message source: ${url}`);
   }
 
-  @d.command("vcmove", "<member:resolvedMember> <channel:string$>")
+  @d.command("vcmove", "<member:resolvedMember> <channel:string$>", {
+    extra: {
+      info: <CommandInfo>{
+        description: "Move a member to another voice channel",
+        basicUsage: "!vcmove @Dragory 473223047822704651",
+      },
+    },
+  })
   @d.permission("can_vcmove")
   async vcmoveCmd(msg: Message, args: { member: Member; channel: string }) {
     let channel: VoiceChannel;
@@ -1001,7 +1098,14 @@ export class UtilityPlugin extends ZeppelinPlugin<TConfigSchema> {
     );
   }
 
-  @d.command("help", "<command:string$>")
+  @d.command("help", "<command:string$>", {
+    extra: {
+      info: <CommandInfo>{
+        description: "Show a quick reference for the specified command's usage",
+        basicUsage: "!help clean",
+      },
+    },
+  })
   @d.permission("can_help")
   helpCmd(msg: Message, args: { command: string }) {
     const searchStr = args.command.toLowerCase();
@@ -1042,7 +1146,13 @@ export class UtilityPlugin extends ZeppelinPlugin<TConfigSchema> {
     createChunkedMessage(msg.channel, message);
   }
 
-  @d.command("about")
+  @d.command("about", "", {
+    extra: {
+      info: <CommandInfo>{
+        description: "Show information about Zeppelin's status on the server",
+      },
+    },
+  })
   @d.permission("can_about")
   async aboutCmd(msg: Message) {
     const uptime = getCurrentUptime();
@@ -1108,7 +1218,13 @@ export class UtilityPlugin extends ZeppelinPlugin<TConfigSchema> {
     msg.channel.createMessage(aboutContent);
   }
 
-  @d.command("reload_guild")
+  @d.command("reload_guild", "", {
+    extra: {
+      info: <CommandInfo>{
+        description: "Reload the Zeppelin configuration and all plugins for the server. This can sometimes fix issues.",
+      },
+    },
+  })
   @d.permission("can_reload_guild")
   reloadGuildCmd(msg: Message) {
     if (activeReloads.has(this.guildId)) return;
diff --git a/src/plugins/ZeppelinPlugin.ts b/src/plugins/ZeppelinPlugin.ts
index 7d604d31..1a2ad954 100644
--- a/src/plugins/ZeppelinPlugin.ts
+++ b/src/plugins/ZeppelinPlugin.ts
@@ -40,6 +40,8 @@ export interface PluginInfo {
 export interface CommandInfo {
   description?: TMarkdown;
   basicUsage?: TMarkdown;
+  examples?: TMarkdown;
+  usageGuide?: TMarkdown;
   parameterDescriptions?: {
     [key: string]: TMarkdown;
   };