Merge pull request #1149 from kungming2/master

Cleaning up models/reddit/mixins

praw/models/reddit/mixins/__init__.py

@@ -27,7 +27,7 @@ def _add_removal_reason(self, mod_note="", reason_id=None):
         It is necessary to first call :meth:`~.remove` on the
         :class:`~.Comment` or :class:`~.Submission`.
 
-        If reason_id is not specified, mod_note cannot be blank.
+        If ``reason_id`` is not specified, ``mod_note`` cannot be blank.
 
         """
         if not reason_id and not mod_note:
@@ -74,9 +74,9 @@ def distinguish(self, how="yes", sticky=False):
         :param how: One of 'yes', 'no', 'admin', 'special'. 'yes' adds a
             moderator level distinguish. 'no' removes any distinction. 'admin'
             and 'special' require special user privileges to use.
-        :param sticky: Comment is stickied if True, placing it at the top of
-            the comment page regardless of score. If thing is not a top-level
-            comment, this parameter is silently ignored.
+        :param sticky: Comment is stickied if ``True``, placing it at the top
+            of the comment page regardless of score. If thing is not a
+            top-level comment, this parameter is silently ignored.
 
         Example usage:
 
@@ -98,7 +98,7 @@ def distinguish(self, how="yes", sticky=False):
         self.thing._reddit.post(API_PATH["distinguish"], data=data)
 
     def ignore_reports(self):
-        """Ignore future reports on a Comment or Submission.
+        """Ignore future reports on a :class:`~.Comment` or :class:`~.Submission`.
 
         Calling this method will prevent future reports on this Comment or
         Submission from both triggering notifications and appearing in the
@@ -112,7 +112,7 @@ def ignore_reports(self):
            # ignore future reports on a comment:
            comment = reddit.comment('dkk4qjd')
            comment.mod.ignore_reports()
-           # ignore future reports on a submission
+           # ignore future reports on a submission:
            submission = reddit.submission(id='5or86n')
            submission.mod.ignore_reports()
 
@@ -124,7 +124,7 @@ def ignore_reports(self):
         )
 
     def lock(self):
-        """Lock the a :class:`~.Comment` or :class:`~.Submission`.
+        """Lock a :class:`~.Comment` or :class:`~.Submission`.
 
         Example usage:
 
@@ -152,8 +152,8 @@ def remove(self, spam=False, mod_note="", reason_id=None):
             spam filter (default: False).
         :param reason_id: The removal reason ID.
 
-        If either reason_id or mod_note are provided, a second API call is made
-        to add the removal reason.
+        If either ``reason_id`` or ``mod_note`` are provided, a second API
+        call is made to add the removal reason.
 
         Example usage:
 
@@ -182,7 +182,7 @@ def send_removal_message(
         title="ignored",
         type="public",  # pylint: disable=redefined-builtin
     ):
-        """Send a removal message for a Comment or Submission.
+        """Send a removal message for a :class:`~.Comment` or :class:`~.Submission`.
 
         Reddit adds human-readable information about the object to the message.
 
@@ -213,7 +213,7 @@ def send_removal_message(
         return self.thing._reddit.post(url, data={"json": dumps(data)}) or None
 
     def undistinguish(self):
-        """Remove mod, admin, or special distinguishing on object.
+        """Remove mod, admin, or special distinguishing from an object.
 
         Also unstickies the object if applicable.
 
@@ -236,8 +236,9 @@ def undistinguish(self):
     def unignore_reports(self):
         """Resume receiving future reports on a Comment or Submission.
 
-        Future reports on this Comment or Submission will cause notifications,
-        and appear in the various moderation listings.
+        Future reports on this :class:`~.Comment` or :class:`~.Submission`
+        will cause notifications, and appear in the various moderation
+        listings.
 
         Example usage:
 
@@ -246,7 +247,7 @@ def unignore_reports(self):
            # accept future reports on a comment:
            comment = reddit.comment('dkk4qjd')
            comment.mod.unignore_reports()
-           # accept future reports on a submission
+           # accept future reports on a submission:
            submission = reddit.submission(id='5or86n')
            submission.mod.unignore_reports()
 
@@ -258,7 +259,7 @@ def unignore_reports(self):
         )
 
     def unlock(self):
-        """Unlock the a :class:`~.Comment` or :class:`~.Submission`.
+        """Unlock a :class:`~.Comment` or :class:`~.Submission`.
 
         Example usage:
 

praw/models/reddit/mixins/editable.py

@@ -24,7 +24,7 @@ def delete(self):
     def edit(self, body):
         """Replace the body of the object with ``body``.
 
-        :param body: The markdown formatted content for the updated object.
+        :param body: The Markdown formatted content for the updated object.
         :returns: The current instance after updating its attributes.
 
         Example usage:
@@ -33,7 +33,8 @@ def edit(self, body):
 
            comment = reddit.comment('dkk4qjd')
 
-           #construct edited comment text by appending to old body
+           # construct the text of an edited comment
+           # by appending to the old body:
            edited_body = comment.body + "Edit: thanks for the gold!"
            comment.edit(edited_body)
 

praw/models/reddit/mixins/gildable.py

@@ -8,8 +8,8 @@ class GildableMixin:
     def gild(self):
         """Gild the author of the item.
 
-        .. note:: Requires the authenticated user to own reddit gold creddits.
-                  Calling this method will consume one reddit gold creddit.
+        .. note:: Requires the authenticated user to own Reddit Coins.
+                  Calling this method will consume Reddit Coins.
 
         Example usage:
 

praw/models/reddit/mixins/messageable.py

@@ -11,13 +11,13 @@ def message(self, subject, message, from_subreddit=None):
 
         :param subject: The subject of the message.
         :param message: The message content.
-        :param from_subreddit: A Subreddit instance or string to send the
-            message from. When provided, messages are sent from the subreddit
-            rather than from the authenticated user. Note that the
-            authenticated user must be a moderator of the subreddit and have
-            mail permissions.
+        :param from_subreddit: A :class:`~.Subreddit` instance or string to
+            send the message from. When provided, messages are sent from
+            the subreddit rather than from the authenticated user.
+            Note that the authenticated user must be a moderator of the
+            subreddit and have the ``mail`` moderator permission.
 
-        For example, to send a private message to ``/u/spez``, try:
+        For example, to send a private message to ``u/spez``, try:
 
         .. code:: python
 
@@ -30,7 +30,7 @@ def message(self, subject, message, from_subreddit=None):
            reddit.redditor('spez').message('TEST', 'test message from r/test',
                                            from_subreddit='test')
 
-        To send a message to the moderators of ``/r/test``, try:
+        To send a message to the moderators of ``r/test``, try:
 
         .. code:: python
 

praw/models/reddit/mixins/replyable.py

@@ -8,7 +8,7 @@ class ReplyableMixin:
     def reply(self, body):
         """Reply to the object.
 
-        :param body: The markdown formatted content for a comment.
+        :param body: The Markdown formatted content for a comment.
         :returns: A :class:`~.Comment` object for the newly created
             comment or ``None`` if Reddit doesn't provide one.
 

praw/models/reddit/mixins/reportable.py

@@ -10,6 +10,9 @@ def report(self, reason):
 
         :param reason: The reason for reporting.
 
+        Raises :class:`.APIException` if ``reason`` is longer than 100
+        characters.
+
         Example usage:
 
         .. code:: python

praw/models/reddit/mixins/savable.py

@@ -8,8 +8,9 @@ class SavableMixin:
     def save(self, category=None):
         """Save the object.
 
-        :param category: (Gold) The category to save to. If your user does not
-            have gold this value is ignored by Reddit (default: None).
+        :param category: (Premium) The category to save to. If your user does
+            not have Reddit Premium this value is ignored by Reddit
+            (default: ``None``).
 
         Example usage:
 

praw/models/reddit/subreddit.py

@@ -1658,8 +1658,8 @@ def removal_reasons(self):
         """Provide an instance of :class:`.SubredditRemovalReasons`.
 
         Use this attribute for interacting with a subreddit's removal reasons.
-        For example to list all the removal reaons for a subreddit which you
-        have the ``posts`` moderator permission on try:
+        For example to list all the removal reasons for a subreddit which you
+        have the ``posts`` moderator permission on, try:
 
         .. code-block:: python