matthew/enhanced-discord.py
1
0
Fork 0
Code Issues 4 Pull Requests 21 Projects Releases Wiki Activity

Improve documentation

Browse Source
This commit is contained in:
NCPlayz
2019-05-18 06:04:54 -04:00
committed by Rapptz
parent 2f05436653
commit 3c9bcc2851
48 changed files with 652 additions and 569 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
discord/ext/commands/bot.py
View File

@ -147,7 +147,7 @@ class BotBase(GroupMixin):
The default command error handler provided by the bot.
By default this prints to ``sys.stderr`` however it could be
By default this prints to :data:`sys.stderr` however it could be
overridden to have a different implementation.
This only fires if you do not specify any listeners for command error.
@ -208,7 +208,7 @@ class BotBase(GroupMixin):
The function that was used as a global check.
call_once: :class:`bool`
If the function should only be called once per
:meth:`.Command.invoke` call.
:meth:`Command.invoke` call.
"""
if call_once:
@ -241,7 +241,7 @@ class BotBase(GroupMixin):
r"""A decorator that adds a "call once" global check to the bot.
Unlike regular global checks, this one is called only once
per :meth:`.Command.invoke` call.
per :meth:`Command.invoke` call.
Regular global checks are called whenever a command is called
or :meth:`.Command.can_run` is called. This type of check
@ -288,6 +288,11 @@ class BotBase(GroupMixin):
-----------
user: :class:`.abc.User`
The user to check for.
Returns
--------
:class:`bool`
Whether the user is the owner.
"""
if self.owner_id is None:
@ -314,7 +319,7 @@ class BotBase(GroupMixin):
Parameters
-----------
coro
coro: :ref:`coroutine <coroutine>`
The coroutine to register as the pre-invoke hook.
Raises
@ -347,7 +352,7 @@ class BotBase(GroupMixin):
Parameters
-----------
coro
coro: :ref:`coroutine <coroutine>`
The coroutine to register as the post-invoke hook.
Raises
@ -420,7 +425,7 @@ class BotBase(GroupMixin):
event listener. Basically this allows you to listen to multiple
events from different places e.g. such as :func:`.on_ready`
The functions being listened to must be a coroutine.
The functions being listened to must be a :ref:`coroutine <coroutine>`.
Example
--------

2
discord/ext/commands/cog.py
View File

@ -34,7 +34,7 @@ __all__ = (
)
class CogMeta(type):
"""A　metaclass for defining a cog.
"""A metaclass for defining a cog.
Note that you should probably not use this directly. It is exposed
purely for documentation purposes along with making custom metaclasses to intermix

6
discord/ext/commands/context.py
View File

@ -34,7 +34,7 @@ class Context(discord.abc.Messageable):
the invocation context. This class is not created manually and is instead
passed around to commands as the first parameter.
This class implements the :class:`abc.Messageable` ABC.
This class implements the :class:`~discord.abc.Messageable` ABC.
Attributes
-----------
@ -61,12 +61,12 @@ class Context(discord.abc.Messageable):
invoked_subcommand
The subcommand (i.e. :class:`.Command` or its subclasses) that was
invoked. If no valid subcommand was invoked then this is equal to
`None`.
``None``.
subcommand_passed: Optional[:class:`str`]
The string that was attempted to call a subcommand. This does not have
to point to a valid registered subcommand and could just point to a
nonsense string. If nothing was passed to attempt a call to a
subcommand then this is set to `None`.
subcommand then this is set to ``None``.
command_failed: :class:`bool`
A boolean that indicates if the command failed to be parsed, checked,
or invoked.

26
discord/ext/commands/converter.py
View File

@ -66,7 +66,7 @@ class Converter:
special cased ``discord`` classes.
Classes that derive from this should override the :meth:`~.Converter.convert`
method to do its conversion logic. This method must be a coroutine.
method to do its conversion logic. This method must be a :ref:`coroutine <coroutine>`.
"""
async def convert(self, ctx, argument):
@ -96,7 +96,7 @@ class IDConverter(Converter):
return self._id_regex.match(argument)
class MemberConverter(IDConverter):
"""Converts to a :class:`Member`.
"""Converts to a :class:`~discord.Member`.
All lookups are via the local guild. If in a DM context, then the lookup
is done by the global cache.
@ -134,7 +134,7 @@ class MemberConverter(IDConverter):
return result
class UserConverter(IDConverter):
"""Converts to a :class:`User`.
"""Converts to a :class:`~discord.User`.
All lookups are via the global user cache.
@ -210,7 +210,7 @@ class MessageConverter(Converter):
raise BadArgument("Can't read messages in {channel}".format(channel=channel.mention))
class TextChannelConverter(IDConverter):
"""Converts to a :class:`TextChannel`.
"""Converts to a :class:`~discord.TextChannel`.
All lookups are via the local guild. If in a DM context, then the lookup
is done by the global cache.
@ -249,7 +249,7 @@ class TextChannelConverter(IDConverter):
return result
class VoiceChannelConverter(IDConverter):
"""Converts to a :class:`VoiceChannel`.
"""Converts to a :class:`~discord.VoiceChannel`.
All lookups are via the local guild. If in a DM context, then the lookup
is done by the global cache.
@ -287,7 +287,7 @@ class VoiceChannelConverter(IDConverter):
return result
class CategoryChannelConverter(IDConverter):
"""Converts to a :class:`CategoryChannel`.
"""Converts to a :class:`~discord.CategoryChannel`.
All lookups are via the local guild. If in a DM context, then the lookup
is done by the global cache.
@ -326,7 +326,7 @@ class CategoryChannelConverter(IDConverter):
return result
class ColourConverter(Converter):
"""Converts to a :class:`Colour`.
"""Converts to a :class:`~discord.Colour`.
The following formats are accepted:
@ -355,7 +355,7 @@ class ColourConverter(Converter):
return method()
class RoleConverter(IDConverter):
"""Converts to a :class:`Role`.
"""Converts to a :class:`~discord.Role`.
All lookups are via the local guild. If in a DM context, then the lookup
is done by the global cache.
@ -382,12 +382,12 @@ class RoleConverter(IDConverter):
return result
class GameConverter(Converter):
"""Converts to :class:`Game`."""
"""Converts to :class:`~discord.Game`."""
async def convert(self, ctx, argument):
return discord.Game(name=argument)
class InviteConverter(Converter):
"""Converts to a :class:`Invite`.
"""Converts to a :class:`~discord.Invite`.
This is done via an HTTP request using :meth:`.Bot.fetch_invite`.
"""
@ -399,7 +399,7 @@ class InviteConverter(Converter):
raise BadArgument('Invite is invalid or expired') from exc
class EmojiConverter(IDConverter):
"""Converts to a :class:`Emoji`.
"""Converts to a :class:`~discord.Emoji`.
All lookups are done for the local guild first, if available. If that lookup
fails, then it checks the client's global cache.
@ -439,7 +439,7 @@ class EmojiConverter(IDConverter):
return result
class PartialEmojiConverter(Converter):
"""Converts to a :class:`PartialEmoji`.
"""Converts to a :class:`~discord.PartialEmoji`.
This is done by extracting the animated flag, name and ID from the emoji.
"""
@ -460,7 +460,7 @@ class clean_content(Converter):
"""Converts the argument to mention scrubbed version of
said content.
This behaves similarly to :attr:`.Message.clean_content`.
This behaves similarly to :attr:`~discord.Message.clean_content`.
Attributes
------------

28
discord/ext/commands/core.py
View File

@ -145,10 +145,10 @@ class Command(_BaseCommand):
If the command is invoked while it is disabled, then
:exc:`.DisabledCommand` is raised to the :func:`.on_command_error`
event. Defaults to ``True``.
parent: Optional[command]
parent: Optional[:class:`Command`]
The parent command that this command belongs to. ``None`` if there
isn't one.
checks
checks: List[Callable[..., :class:`bool`]]
A list of predicates that verifies if the command could be executed
with the given :class:`.Context` as the sole parameter. If an exception
is necessary to be thrown to signal failure, then one inherited from
@ -297,7 +297,7 @@ class Command(_BaseCommand):
return other
def copy(self):
"""Creates a copy of this :class:`Command`."""
"""Creates a copy of this command."""
ret = self.__class__(self.callback, **self.__original_kwargs__)
return self._ensure_assignment_on_copy(ret)
@ -505,7 +505,7 @@ class Command(_BaseCommand):
@property
def full_parent_name(self):
"""Retrieves the fully qualified parent command name.
""":class:`str`: Retrieves the fully qualified parent command name.
This the base command name required to execute it. For example,
in ``?one two three`` the parent name would be ``one two``.
@ -520,7 +520,7 @@ class Command(_BaseCommand):
@property
def parents(self):
"""Retrieves the parents of this command.
""":class:`Command`: Retrieves the parents of this command.
If the command has no parents then it returns an empty :class:`list`.
@ -550,7 +550,7 @@ class Command(_BaseCommand):
@property
def qualified_name(self):
"""Retrieves the fully qualified command name.
""":class:`str`: Retrieves the fully qualified command name.
This is the full parent name with the command name as well.
For example, in ``?one two three`` the qualified name would be
@ -688,7 +688,7 @@ class Command(_BaseCommand):
Parameters
-----------
ctx: :class:`.Context.`
ctx: :class:`.Context`
The invocation context to use when checking the commands cooldown status.
Returns
@ -821,12 +821,12 @@ class Command(_BaseCommand):
@property
def cog_name(self):
"""The name of the cog this command belongs to. None otherwise."""
""":class:`str`: The name of the cog this command belongs to. None otherwise."""
return type(self.cog).__cog_name__ if self.cog is not None else None
@property
def short_doc(self):
"""Gets the "short" documentation of a command.
""":class:`str`: Gets the "short" documentation of a command.
By default, this is the :attr:`brief` attribute.
If that lookup leads to an empty string then the first line of the
@ -851,7 +851,7 @@ class Command(_BaseCommand):
@property
def signature(self):
"""Returns a POSIX-like signature useful for help command output."""
""":class:`str`: Returns a POSIX-like signature useful for help command output."""
if self.usage is not None:
return self.usage
@ -971,7 +971,7 @@ class GroupMixin:
Parameters
-----------
command
command: :class:`Command`
The command to add.
Raises
@ -1107,7 +1107,7 @@ class Group(GroupMixin, Command):
Attributes
-----------
invoke_without_command: :class:`bool`
invoke_without_command: Optional[:class:`bool`]
Indicates if the group callback should begin parsing and
invocation only if no subcommand was found. Useful for
making it an error handling function to tell the user that
@ -1116,7 +1116,7 @@ class Group(GroupMixin, Command):
the group callback will always be invoked first. This means
that the checks and the parsing dictated by its parameters
will be executed. Defaults to ``False``.
case_insensitive: :class:`bool`
case_insensitive: Optional[:class:`bool`]
Indicates if the group's commands should be case insensitive.
Defaults to ``False``.
"""
@ -1301,7 +1301,7 @@ def check(predicate):
Parameters
-----------
predicate: Callable[:class:`Context`, :class:`bool`]
predicate: Callable[[:class:`Context`], :class:`bool`]
The predicate to check if the command should be invoked.
"""

2
discord/ext/commands/errors.py
View File

@ -374,7 +374,7 @@ class BotMissingPermissions(CheckFailure):
super().__init__(message, *args)
class BadUnionArgument(UserInputError):
"""Exception raised when a :class:`typing.Union` converter fails for all
"""Exception raised when a :data:`typing.Union` converter fails for all
its associated types.
This inherits from :exc:`UserInputError`

2
discord/ext/commands/help.py
View File

@ -550,7 +550,7 @@ class HelpCommand:
return max(as_lengths, default=0)
def get_destination(self):
"""Returns the :class:`abc.Messageable` where the help command will be output.
"""Returns the :class:`~discord.abc.Messageable` where the help command will be output.
You can override this method to customise the behaviour.