Merge pull request #412 from EnokiUN/master

Docstrings for application command permissions

Author: Middledot

discord/commands/permissions.py

@@ -35,6 +35,25 @@
 )
 
 class Permission:
+    """The class used in the application command decorators
+    to hash permission data into a dictionary using the
+    :meth:`to_dict` method to be sent to the discord API later on.
+
+    .. versionadded:: 2.0
+
+    Attributes
+    -----------
+    id: Union[:class:`int`, :class:`str`]
+        A string or integer that represents or helps get
+        the id of the user or role that the permission is tied to.
+    type: :class:`int`
+        An integer representing the type of the permission.
+    permission: :class:`bool`
+        A boolean representing the permission's value.
+    guild_id: :class:`int`
+        The integer which represents the id of the guild that the
+        permission may be tied to.
+    """
     def __init__(self, id: Union[int, str], type: int, permission: bool = True, guild_id: int = None):
         self.id = id
         self.type = type
@@ -45,6 +64,27 @@ def to_dict(self) -> Dict[str, Union[int, bool]]:
         return {"id": self.id, "type": self.type, "permission": self.permission}
 
 def permission(role_id: int = None, user_id: int = None, permission: bool = True, guild_id: int = None):
+    """The method used to specify application command permissions 
+    for specific users or roles using their id.
+
+    This method is meant to be used as a decorator.
+
+    .. versionadded:: 2.0
+
+    Parameters
+    -----------
+    role_id: :class:`int`
+        An integer which represents the id of the role that the
+        permission may be tied to.
+    user_id: :class:`int`
+        An integer which represents the id of the user that the
+        permission may be tied to.
+    permission: :class:`bool`
+        A boolean representing the permission's value.
+    guild_id: :class:`int`
+        The integer which represents the id of the guild that the
+        permission may be tied to.
+    """
     def decorator(func: Callable):
         if not role_id is None:
             app_cmd_perm = Permission(role_id, 1, permission, guild_id)
@@ -65,6 +105,21 @@ def decorator(func: Callable):
     return decorator
 
 def has_role(item: Union[int, str], guild_id: int = None):
+    """The method used to specify application command role restrictions.
+    
+    This method is meant to be used as a decorator.
+    
+    .. versionadded:: 2.0
+    
+    Parameters
+    -----------
+    item: Union[:class:`int`, :class:`str`]
+        An integer or string that represent the id or name of the role 
+        that the permission is tied to.
+    guild_id: :class:`int`
+        The integer which represents the id of the guild that the
+        permission may be tied to.
+    """
     def decorator(func: Callable):
         # Create __app_cmd_perms__
         if not hasattr(func, '__app_cmd_perms__'):
@@ -81,6 +136,22 @@ def decorator(func: Callable):
     return decorator
 
 def has_any_role(*items: Union[int, str], guild_id: int = None):
+    """The method used to specify multiple application command role restrictions,
+    The application command runs if the invoker has **any** of the specified roles.
+    
+    This method is meant to be used as a decorator.
+    
+    .. versionadded:: 2.0
+    
+    Parameters
+    -----------
+    *items: Union[:class:`int`, :class:`str`]
+        The integers or strings that represent the ids or names of the roles
+        that the permission is tied to.
+    guild_id: :class:`int`
+        The integer which represents the id of the guild that the
+        permission may be tied to.
+    """
     def decorator(func: Callable):
         # Create __app_cmd_perms__
         if not hasattr(func, '__app_cmd_perms__'):
@@ -98,6 +169,20 @@ def decorator(func: Callable):
     return decorator
 
 def is_user(user: int, guild_id: int = None):
+    """The method used to specify application command user restrictions.
+    
+    This method is meant to be used as a decorator.
+    
+    .. versionadded:: 2.0
+    
+    Parameters
+    -----------
+    user: :class:`int`
+        An integer that represent the id of the user that the permission is tied to.
+    guild_id: :class:`int`
+        The integer which represents the id of the guild that the
+        permission may be tied to.
+    """
     def decorator(func: Callable):
         # Create __app_cmd_perms__
         if not hasattr(func, '__app_cmd_perms__'):
@@ -114,6 +199,19 @@ def decorator(func: Callable):
     return decorator
 
 def is_owner(guild_id: int = None):
+    """The method used to limit application commands exclusively
+    to the owner of the bot.
+    
+    This method is meant to be used as a decorator.
+    
+    .. versionadded:: 2.0
+    
+    Parameters
+    -----------
+    guild_id: :class:`int`
+        The integer which represents the id of the guild that the
+        permission may be tied to.
+    """
     def decorator(func: Callable):
         # Create __app_cmd_perms__
         if not hasattr(func, '__app_cmd_perms__'):
@@ -127,4 +225,4 @@ def decorator(func: Callable):
 
         return func
 
-    return decorator
+    return decorator