From 3e80edcdfdc334156e3051827040669296e55883 Mon Sep 17 00:00:00 2001
From: jack1142 <6032823+jack1142@users.noreply.github.com>
Date: Sun, 14 Jul 2019 03:30:11 +0200
Subject: [PATCH] [Docs] Add awaits and missing imports in usage examples
 (#2860)

Well, the modlog examples had to be changed a lot, because `await` obviously won't work in regular method.
---
 docs/framework_bank.rst   | 11 +++---
 docs/framework_modlog.rst | 71 ++++++++++++++++++++++++---------------
 2 files changed, 49 insertions(+), 33 deletions(-)

diff --git a/docs/framework_bank.rst b/docs/framework_bank.rst
index b6cfb4ec4..9f5e676f8 100644
--- a/docs/framework_bank.rst
+++ b/docs/framework_bank.rst
@@ -16,15 +16,16 @@ Basic Usage
 
 .. code-block:: python
 
-    from redbot.core import bank
+    from redbot.core import bank, commands
+    import discord
 
-    class MyCog:
+    class MyCog(commands.Cog):
         @commands.command()
-        async def balance(self, ctx, user: discord.Member=None):
+        async def balance(self, ctx, user: discord.Member = None):
             if user is None:
                 user = ctx.author
-            bal = bank.get_balance(user)
-            currency = bank.get_currency_name(ctx.guild)
+            bal = await bank.get_balance(user)
+            currency = await bank.get_currency_name(ctx.guild)
             await ctx.send(
                 "{}'s balance is {} {}".format(
                     user.display_name, bal, currency
diff --git a/docs/framework_modlog.rst b/docs/framework_modlog.rst
index 5baa45ffe..a9f66d817 100644
--- a/docs/framework_modlog.rst
+++ b/docs/framework_modlog.rst
@@ -16,17 +16,17 @@ Basic Usage
 
 .. code-block:: python
 
-    from redbot.core import modlog
+    from redbot.core import commands, modlog
     import discord
 
-    class MyCog:
+    class MyCog(commands.Cog):
         @commands.command()
         @checks.admin_or_permissions(ban_members=True)
-        async def ban(self, ctx, user: discord.Member, reason: str=None):
+        async def ban(self, ctx, user: discord.Member, reason: str = None):
             await ctx.guild.ban(user)
-            case = modlog.create_case(
-                ctx.guild, ctx.message.created_at, "ban", user,
-                ctx.author, reason, until=None, channel=None
+            case = await modlog.create_case(
+                ctx.bot, ctx.guild, ctx.message.created_at, action="ban",
+                user=user, moderator=ctx.author, reason=reason
             )
             await ctx.send("Done. It was about time.")
 
@@ -35,50 +35,65 @@ Basic Usage
 Registering Case types
 **********************
 
-To register a single case type:
+To register case types, use an asynchronous ``initialize()`` method and call
+it from your setup function:
 
 .. code-block:: python
 
-    from redbot.core import modlog
+    # mycog/mycog.py
+    from redbot.core import modlog, commands
     import discord
 
-    class MyCog:
-        def __init__(self, bot):
+    class MyCog(commands.Cog):
+
+        async def initialize(self):
+            await self.register_casetypes()
+
+        @staticmethod
+        async def register_casetypes():
+            # Registering a single casetype
             ban_case = {
                 "name": "ban",
                 "default_setting": True,
-                "image": ":hammer:",
+                "image": "\N{HAMMER}",
                 "case_str": "Ban",
-                "audit_type": "ban"
+                # audit_type should be omitted if the action doesn't show
+                # up in the audit log.
+                "audit_type": "ban",
             }
-            modlog.register_casetype(**ban_case)
+            try:
+                await modlog.register_casetype(**ban_case)
+            except RuntimeError:
+                pass
 
-To register multiple case types:
-
-.. code-block:: python
-
-    from redbot.core import modlog
-    import discord
-
-    class MyCog:
-        def __init__(self, bot):
+            # Registering multiple casetypes
             new_types = [
                 {
-                    "name": "ban",
+                    "name": "hackban",
                     "default_setting": True,
-                    "image": ":hammer:",
-                    "case_str": "Ban",
-                    "audit_type": "ban"
+                    "image": "\N{BUST IN SILHOUETTE}\N{HAMMER}",
+                    "case_str": "Hackban",
+                    "audit_type": "ban",
                 },
                 {
                     "name": "kick",
                     "default_setting": True,
-                    "image": ":boot:",
+                    "image": "\N{WOMANS BOOTS}",
                     "case_str": "Kick",
                     "audit_type": "kick"
                 }
             ]
-            modlog.register_casetypes(new_types)
+            await modlog.register_casetypes(new_types)
+
+.. code-block:: python
+
+    # mycog/__init__.py
+    from .mycog import MyCog
+
+    async def setup(bot):
+        cog = MyCog()
+        await cog.initialize()
+        bot.add_cog(cog)
 
 .. important::
     Image should be the emoji you want to represent your case type with.