Replace paramater and return value docstring documentation with an extended summary

6 files changed, 34 insertions, 121 deletions

diff --git a/bot/pagination.py b/bot/pagination.py
index e6cea41f..212f9f4e 100644
--- a/bot/pagination.py
+++ b/bot/pagination.py
@@ -22,26 +22,16 @@ class EmptyPaginatorEmbed(Exception):
 
 
 class LinePaginator(Paginator):
-    """
-    A class that aids in paginating code blocks for Discord messages.
-
-    Attributes
-    -----------
-    prefix: :class:`str`
-        The prefix inserted to every page. e.g. three backticks.
-    suffix: :class:`str`
-        The suffix appended at the end of every page. e.g. three backticks.
-    max_size: :class:`int`
-        The maximum amount of codepoints allowed in a page.
-    max_lines: :class:`int`
-        The maximum amount of lines allowed in a page.
-    """
+    """A class that aids in paginating code blocks for Discord messages."""
 
     def __init__(self, prefix='```', suffix='```', max_size=2000, max_lines=None):
         """
         Overrides the Paginator.__init__ from inside discord.ext.commands.
 
-        Allows for configuration of the maximum number of lines per page.
+        `prefix` and `suffix` will be prepended and appended respectively to every page.
+
+        `max_size` and `max_lines` denote the maximum amount of codepoints and lines
+        allowed per page.
         """
         self.prefix = prefix
         self.suffix = suffix
@@ -56,22 +46,12 @@ class LinePaginator(Paginator):
         """
         Adds a line to the current page.
 
-        If the line exceeds the `max_size` then an exception is raised.
+        If the line exceeds the `max_size` then a RuntimeError is raised.
 
         Overrides the Paginator.add_line from inside discord.ext.commands in order to allow
         configuration of the maximum number of lines per page.
 
-        Parameters
-        -----------
-        line: str
-            The line to add.
-        empty: bool
-            Indicates if another empty line should be added.
-
-        Raises
-        ------
-        RuntimeError
-            The line was too big for the current `max_size`.
+        If `empty` is True, an empty line will be placed after the a given `line`.
         """
         if len(line) > self.max_size - len(self.prefix) - 2:
             raise RuntimeError('Line exceeds maximum page size %s' % (self.max_size - len(self.prefix) - 2))
@@ -105,7 +85,11 @@ class LinePaginator(Paginator):
 
         When used, this will send a message using `ctx.send()` and apply a set of reactions to it.
         These reactions may be used to change page, or to remove pagination from the message.
-        Pagination will also be removed automatically if no reaction is added for five minutes (300 seconds).
+
+        Pagination will also be removed automatically if no reaction is added for `timeout` seconds,
+        defaulting to five minutes (300 seconds).
+
+        If `empty` is True, an empty line will be placed between each given line.
 
         >>> embed = Embed()
         >>> embed.set_author(name="Some Operation", url=url, icon_url=icon)
@@ -113,20 +97,6 @@ class LinePaginator(Paginator):
         ...     (line for line in lines),
         ...     ctx, embed
         ... )
-
-        :param lines: The lines to be paginated
-        :param ctx: Current context object
-        :param embed: A pre-configured embed to be used as a template for each page
-        :param prefix: Text to place before each page
-        :param suffix: Text to place after each page
-        :param max_lines: The maximum number of lines on each page
-        :param max_size: The maximum number of characters on each page
-        :param empty: Whether to place an empty line between each given line
-        :param restrict_to_user: A user to lock pagination operations to for this message, if supplied
-        :param exception_on_empty_embed: Should there be an exception if the embed is empty?
-        :param url: the url to use for the embed headline
-        :param timeout: The amount of time in seconds to disable pagination of no reaction is added
-        :param footer_text: Text to prefix the page number in the footer with
         """
         def event_check(reaction_: Reaction, user_: Member):
             """Make sure that this reaction is what we want to operate on."""
@@ -314,8 +284,7 @@ class ImagePaginator(Paginator):
         """
         Adds a line to each page, usually just 1 line in this context.
 
-        :param line: str to be page content / title
-        :param empty: if there should be new lines between entries
+        If `empty` is True, an empty line will be placed after a given `line`.
         """
         if line:
             self._count = len(line)
@@ -326,9 +295,7 @@ class ImagePaginator(Paginator):
 
     def add_image(self, image: str = None) -> None:
         """
-        Adds an image to a page.
-
-        :param image: image url to be appended
+        Adds an image to a page given the url.
         """
         self.images.append(image)
 
@@ -339,33 +306,21 @@ class ImagePaginator(Paginator):
         """
         Use a paginator and set of reactions to provide pagination over a set of title/image pairs.
 
-        The reactions are used to switch page, or to finish with pagination.
+        `pages` is a list of tuples of page title/image url pairs.
+        `prefix` and `suffix` will be prepended and appended respectively to the message.
 
         When used, this will send a message using `ctx.send()` and apply a set of reactions to it.
         These reactions may be used to change page, or to remove pagination from the message.
 
-        Note: Pagination will be removed automatically if no reaction is added for five minutes (300 seconds).
+        Note: Pagination will be removed automatically if no reaction is added for `timeout` seconds,
+              defaulting to five minutes (300 seconds).
 
         >>> embed = Embed()
         >>> embed.set_author(name="Some Operation", url=url, icon_url=icon)
         >>> await ImagePaginator.paginate(pages, ctx, embed)
-
-        Parameters
-        -----------
-        :param pages: An iterable of tuples with title for page, and img url
-        :param ctx: ctx for message
-        :param embed: base embed to modify
-        :param prefix: prefix of message
-        :param suffix: suffix of message
-        :param timeout: timeout for when reactions get auto-removed
         """
         def check_event(reaction_: Reaction, member: Member) -> bool:
-            """
-            Checks each reaction added, if it matches our conditions pass the wait_for.
-
-            :param reaction_: reaction added
-            :param member: reaction added by member
-            """
+            """Checks each reaction added, if it matches our conditions pass the wait_for."""
             return all((
                 # Reaction is on the same message sent
                 reaction_.message.id == message.id,
diff --git a/bot/seasons/evergreen/snakes/snakes_cog.py b/bot/seasons/evergreen/snakes/snakes_cog.py
index 1d138aff..6924a552 100644
--- a/bot/seasons/evergreen/snakes/snakes_cog.py
+++ b/bot/seasons/evergreen/snakes/snakes_cog.py
@@ -303,9 +303,6 @@ class Snakes(Cog):
         Builds a dict that the .get() method can use.
 
         Created by Ava and eivl.
-
-        :param name: The name of the snake to get information for - omit for a random snake
-        :return: A dict containing information on a snake
         """
         snake_info = {}
 
@@ -631,14 +628,10 @@ class Snakes(Cog):
     @snakes_group.command(name='get')
     @bot_has_permissions(manage_messages=True)
     @locked()
-    async def get_command(self, ctx: Context, *, name: Snake = None):
+    async def get_command(self, ctx: Context, *, name: Snake = None) -> None:
         """
         Fetches information about a snake from Wikipedia.
 
-        :param ctx: Context object passed from discord.py
-        :param name: Optional, the name of the snake to get information
-                     for - omit for a random snake
-
         Created by Ava and eivl.
         """
         with ctx.typing():
@@ -1034,10 +1027,8 @@ class Snakes(Cog):
         """
         How would I talk if I were a snake?
 
-        :param ctx: context
-        :param message: If this is passed, it will snakify the message.
-                        If not, it will snakify a random message from
-                        the users history.
+        If `message` is passed, the bot will snakify the message.
+        Otherwise, a random message from the user's history is snakified.
 
         Written by Momo and kel.
         Modified by lemon.
@@ -1077,8 +1068,7 @@ class Snakes(Cog):
         """
         Gets a YouTube video about snakes.
 
-        :param ctx: Context object passed from discord.py
-        :param search: Optional, a name of a snake. Used to search for videos with that name
+        If `search` is given, a snake with that name will be searched on Youtube.
 
         Written by Andrew and Prithaj.
         """
diff --git a/bot/seasons/evergreen/snakes/utils.py b/bot/seasons/evergreen/snakes/utils.py
index 5d3b0dee..e8d2ee44 100644
--- a/bot/seasons/evergreen/snakes/utils.py
+++ b/bot/seasons/evergreen/snakes/utils.py
@@ -285,20 +285,8 @@ def create_snek_frame(
     """
     Creates a single random snek frame using Perlin noise.
 
-    :param perlin_factory: the perlin noise factory used. Required.
-    :param perlin_lookup_vertical_shift: the Perlin noise shift in the Y-dimension for this frame
-    :param image_dimensions: the size of the output image.
-    :param image_margins: the margins to respect inside of the image.
-    :param snake_length: the length of the snake, in segments.
-    :param snake_color: the color of the snake.
-    :param bg_color: the background color.
-    :param segment_length_range: the range of the segment length. Values will be generated inside
-                                 this range, including the bounds.
-    :param snake_width: the width of the snek, in pixels.
-    :param text: the text to display with the snek. Set to None for no text.
-    :param text_position: the position of the text.
-    :param text_color: the color of the text.
-    :return: a PIL image, representing a single frame.
+    `perlin_lookup_vertical_shift` represents the Perlin noise shift in the Y-dimension for this frame.
+    If `text` is given, display the given text with the snek.
     """
     start_x = random.randint(image_margins[X], image_dimensions[X] - image_margins[X])
     start_y = random.randint(image_margins[Y], image_dimensions[Y] - image_margins[Y])
diff --git a/bot/seasons/halloween/monstersurvey.py b/bot/seasons/halloween/monstersurvey.py
index 4e967cca..05e86628 100644
--- a/bot/seasons/halloween/monstersurvey.py
+++ b/bot/seasons/halloween/monstersurvey.py
@@ -36,15 +36,11 @@ class MonsterSurvey(Cog):
         with open(self.registry_location, 'w') as jason:
             json.dump(self.voter_registry, jason, indent=2)
 
-    def cast_vote(self, id: int, monster: str):
+    def cast_vote(self, id: int, monster: str) -> None:
         """
         Cast a user's vote for the specified monster.
 
         If the user has already voted, their existing vote is removed.
-
-        :param id: The id of the person voting
-        :param monster: the string key of the json that represents a monster
-        :return: None
         """
         vr = self.voter_registry
         for m in vr.keys():
@@ -147,13 +143,9 @@ class MonsterSurvey(Cog):
     @monster_group.command(
         name='show'
     )
-    async def monster_show(self, ctx: Context, name=None):
+    async def monster_show(self, ctx: Context, name=None) -> None:
         """
         Shows the named monster. If one is not named, it sends the default voting embed instead.
-
-        :param ctx:
-        :param name:
-        :return:
         """
         if name is None:
             await ctx.invoke(self.monster_leaderboard)
@@ -184,12 +176,9 @@ class MonsterSurvey(Cog):
         name='leaderboard',
         aliases=('lb',)
     )
-    async def monster_leaderboard(self, ctx: Context):
+    async def monster_leaderboard(self, ctx: Context) -> None:
         """
         Shows the current standings.
-
-        :param ctx:
-        :return:
         """
         async with ctx.typing():
             vr = self.voter_registry
diff --git a/bot/seasons/valentines/be_my_valentine.py b/bot/seasons/valentines/be_my_valentine.py
index ac140896..c4acf17a 100644
--- a/bot/seasons/valentines/be_my_valentine.py
+++ b/bot/seasons/valentines/be_my_valentine.py
@@ -184,14 +184,11 @@ class BeMyValentine(commands.Cog):
         return valentine, title
 
     @staticmethod
-    def random_user(author, members):
+    def random_user(author: discord.Member, members: discord.Member):
         """
         Picks a random member from the list provided in `members`.
 
         The invoking author is ignored.
-
-        :param author: member who invoked the command
-        :param members: list of discord.Member objects
         """
         if author in members:
             members.remove(author)
diff --git a/bot/utils/__init__.py b/bot/utils/__init__.py
index ef18a1b9..15c4b5db 100644
--- a/bot/utils/__init__.py
+++ b/bot/utils/__init__.py
@@ -9,21 +9,15 @@ from bot.pagination import LinePaginator
 
 async def disambiguate(
         ctx: Context, entries: List[str], *, timeout: float = 30,
-        per_page: int = 20, empty: bool = False, embed: discord.Embed = None
-):
+        entries_per_page: int = 20, empty: bool = False, embed: discord.Embed = None
+) -> str:
     """
     Has the user choose between multiple entries in case one could not be chosen automatically.
 
+    Disambiguation will be canceled after `timeout` seconds.
+
     This will raise a BadArgument if entries is empty, if the disambiguation event times out,
     or if the user makes an invalid choice.
-
-    :param ctx: Context object from discord.py
-    :param entries: List of items for user to choose from
-    :param timeout: Number of seconds to wait before canceling disambiguation
-    :param per_page: Entries per embed page
-    :param empty: Whether the paginator should have an extra line between items
-    :param embed: The embed that the paginator will use.
-    :return: Users choice for correct entry.
     """
     if len(entries) == 0:
         raise BadArgument('No matches found.')
@@ -43,7 +37,7 @@ async def disambiguate(
             embed = discord.Embed()
 
         coro1 = ctx.bot.wait_for('message', check=check, timeout=timeout)
-        coro2 = LinePaginator.paginate(choices, ctx, embed=embed, max_lines=per_page,
+        coro2 = LinePaginator.paginate(choices, ctx, embed=embed, max_lines=entries_per_page,
                                        empty=empty, max_size=6000, timeout=9000)
 
         # wait_for timeout will go to except instead of the wait_for thing as I expected