Add listing generator disclaimer docstrings (#1168)

Update ListingGenerator references and add in disclaimers

praw/models/front.py

@@ -14,7 +14,7 @@ def __init__(self, reddit):
         self._path = "/"
 
     def best(self, **generator_kwargs):
-        """Return a ListingGenerator for best items.
+        """Return a :class:`.ListingGenerator` for best items.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.

praw/models/inbox.py

@@ -9,7 +9,7 @@ class Inbox(PRAWBase):
     """Inbox is a Listing class that represents the Inbox."""
 
     def all(self, **generator_kwargs):
-        """Return a ListingGenerator for all inbox comments and messages.
+        """Return a :class:`.ListingGenerator` for all inbox comments and messages.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.
@@ -55,7 +55,7 @@ def collapse(self, items):
             items = items[25:]
 
     def comment_replies(self, **generator_kwargs):
-        """Return a ListingGenerator for comment replies.
+        """Return a :class:`.ListingGenerator` for comment replies.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.
@@ -129,7 +129,7 @@ def mark_unread(self, items):
             items = items[25:]
 
     def mentions(self, **generator_kwargs):
-        r"""Return a ListingGenerator for mentions.
+        r"""Return a :class:`.ListingGenerator` for mentions.
 
         A mention is :class:`.Comment` in which the authorized redditor is
         named in its body like ``/u/redditor_name``.
@@ -170,7 +170,7 @@ def message(self, message_id):
                 return message
 
     def messages(self, **generator_kwargs):
-        """Return a ListingGenerator for inbox messages.
+        """Return a :class:`.ListingGenerator` for inbox messages.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.
@@ -188,7 +188,7 @@ def messages(self, **generator_kwargs):
         )
 
     def sent(self, **generator_kwargs):
-        """Return a ListingGenerator for sent messages.
+        """Return a :class:`.ListingGenerator` for sent messages.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.
@@ -225,7 +225,7 @@ def stream(self, **stream_options):
         return stream_generator(self.unread, **stream_options)
 
     def submission_replies(self, **generator_kwargs):
-        """Return a ListingGenerator for submission replies.
+        """Return a :class:`.ListingGenerator` for submission replies.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.
@@ -271,7 +271,7 @@ def uncollapse(self, items):
             items = items[25:]
 
     def unread(self, mark_read=False, **generator_kwargs):
-        """Return a ListingGenerator for unread comments and messages.
+        """Return a :class:`.ListingGenerator` for unread comments and messages.
 
         :param mark_read: Marks the inbox as read (default: False).
 

praw/models/listing/mixins/base.py

@@ -29,7 +29,7 @@ def _validate_time_filter(time_filter):
             )
 
     def controversial(self, time_filter="all", **generator_kwargs):
-        """Return a ListingGenerator for controversial submissions.
+        """Return a :class:`.ListingGenerator` for controversial submissions.
 
         :param time_filter: Can be one of: all, day, hour, month, week, year
             (default: all).
@@ -57,7 +57,7 @@ def controversial(self, time_filter="all", **generator_kwargs):
         return ListingGenerator(self._reddit, url, **generator_kwargs)
 
     def hot(self, **generator_kwargs):
-        """Return a ListingGenerator for hot items.
+        """Return a :class:`.ListingGenerator` for hot items.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.
@@ -79,7 +79,7 @@ def hot(self, **generator_kwargs):
         return ListingGenerator(self._reddit, url, **generator_kwargs)
 
     def new(self, **generator_kwargs):
-        """Return a ListingGenerator for new items.
+        """Return a :class:`.ListingGenerator` for new items.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.
@@ -101,7 +101,7 @@ def new(self, **generator_kwargs):
         return ListingGenerator(self._reddit, url, **generator_kwargs)
 
     def top(self, time_filter="all", **generator_kwargs):
-        """Return a ListingGenerator for top submissions.
+        """Return a :class:`.ListingGenerator` for top submissions.
 
         :param time_filter: Can be one of: all, day, hour, month, week, year
             (default: all).

praw/models/listing/mixins/gilded.py

@@ -9,7 +9,7 @@ class GildedListingMixin(PRAWBase):
     """Mixes in the gilded method."""
 
     def gilded(self, **generator_kwargs):
-        """Return a ListingGenerator for gilded items.
+        """Return a :class:`.ListingGenerator` for gilded items.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.

praw/models/listing/mixins/redditor.py

@@ -41,7 +41,7 @@ def submissions(self):
         return SubListing(self._reddit, self._path, "submitted")
 
     def downvoted(self, **generator_kwargs):
-        """Return a ListingGenerator for items the user has downvoted.
+        """Return a :class:`.ListingGenerator` for items the user has downvoted.
 
         May raise ``prawcore.Forbidden`` after issuing the request if the user
         is not authorized to access the list. Note that because this function
@@ -57,7 +57,7 @@ def downvoted(self, **generator_kwargs):
         )
 
     def gildings(self, **generator_kwargs):
-        """Return a ListingGenerator for items the user has gilded.
+        """Return a :class:`.ListingGenerator` for items the user has gilded.
 
         May raise ``prawcore.Forbidden`` after issuing the request if the user
         is not authorized to access the list. Note that because this function
@@ -75,7 +75,7 @@ def gildings(self, **generator_kwargs):
         )
 
     def hidden(self, **generator_kwargs):
-        """Return a ListingGenerator for items the user has hidden.
+        """Return a :class:`.ListingGenerator` for items the user has hidden.
 
         May raise ``prawcore.Forbidden`` after issuing the request if the user
         is not authorized to access the list. Note that because this function
@@ -91,7 +91,7 @@ def hidden(self, **generator_kwargs):
         )
 
     def saved(self, **generator_kwargs):
-        """Return a ListingGenerator for items the user has saved.
+        """Return a :class:`.ListingGenerator` for items the user has saved.
 
         May raise ``prawcore.Forbidden`` after issuing the request if the user
         is not authorized to access the list. Note that because this function
@@ -107,7 +107,7 @@ def saved(self, **generator_kwargs):
         )
 
     def upvoted(self, **generator_kwargs):
-        """Return a ListingGenerator for items the user has upvoted.
+        """Return a :class:`.ListingGenerator` for items the user has upvoted.
 
         May raise ``prawcore.Forbidden`` after issuing the request if the user
         is not authorized to access the list. Note that because this function
@@ -124,7 +124,7 @@ def upvoted(self, **generator_kwargs):
 
 
 class SubListing(BaseListingMixin):
-    """Helper class for generating ListingGenerator objects."""
+    """Helper class for generating :class:`.ListingGenerator` objects."""
 
     def __init__(self, reddit, base_path, subpath):
         """Initialize a SubListing instance.

praw/models/listing/mixins/rising.py

@@ -9,7 +9,7 @@ class RisingListingMixin(PRAWBase):
     """Mixes in the rising methods."""
 
     def random_rising(self, **generator_kwargs):
-        """Return a ListingGenerator for random rising submissions.
+        """Return a :class:`.ListingGenerator` for random rising submissions.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.
@@ -22,7 +22,7 @@ def random_rising(self, **generator_kwargs):
         )
 
     def rising(self, **generator_kwargs):
-        """Return a ListingGenerator for rising submissions.
+        """Return a :class:`.ListingGenerator` for rising submissions.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.

praw/models/listing/mixins/submission.py

@@ -8,7 +8,7 @@ class SubmissionListingMixin(PRAWBase):
     """Adds additional methods pertaining to Submission instances."""
 
     def duplicates(self, **generator_kwargs):
-        """Return a ListingGenerator for the submission's duplicates.
+        """Return a :class:`.ListingGenerator` for the submission's duplicates.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.

praw/models/listing/mixins/subreddit.py

@@ -51,7 +51,7 @@ def __init__(self, subreddit):
         self.subreddit = subreddit
 
     def __call__(self, **generator_kwargs):
-        """Return a ListingGenerator for the Subreddit's comments.
+        """Return a :class:`.ListingGenerator` for the Subreddit's comments.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.

praw/models/reddit/live.py

@@ -371,6 +371,9 @@ def discussions(self, **generator_kwargs):
         :returns: A :class:`.ListingGenerator` object which yields
             :class:`.Submission` object.
 
+        Additional keyword arguments are passed in the initialization of
+        :class:`.ListingGenerator`.
+
         Usage:
 
         .. code-block:: python
@@ -409,6 +412,9 @@ def updates(self, **generator_kwargs):
         :returns: A :class:`.ListingGenerator` object which yields
             :class:`.LiveUpdate` object.
 
+        Additional keyword arguments are passed in the initialization of
+        :class:`.ListingGenerator`.
+
         Usage:
 
         .. code-block:: python

praw/models/reddit/subreddit.py

@@ -581,7 +581,7 @@ def search(
         time_filter="all",
         **generator_kwargs
     ):
-        """Return a ListingGenerator for items that match ``query``.
+        """Return a :class:`.ListingGenerator` for items that match ``query``.
 
         :param query: The query string to search for.
         :param sort: Can be one of: relevance, hot, top, new,
@@ -1057,12 +1057,15 @@ def templates(self):
         return SubredditRedditorFlairTemplates(self.subreddit)
 
     def __call__(self, redditor=None, **generator_kwargs):
-        """Return a generator for Redditors and their associated flair.
+        """Return a :class:`.ListingGenerator` for Redditors and their flairs.
 
         :param redditor: When provided, yield at most a single
             :class:`~.Redditor` instance (default: None).
 
-        This method is intended to be used like:
+        Additional keyword arguments are passed in the initialization of
+        :class:`.ListingGenerator`.
+
+        Usage:
 
         .. code-block:: python
 
@@ -1558,7 +1561,7 @@ def accept_invite(self):
         self.subreddit._reddit.post(url)
 
     def edited(self, only=None, **generator_kwargs):
-        """Return a ListingGenerator for edited comments and submissions.
+        """Return a :class:`.ListingGenerator` for edited comments and submissions.
 
         :param only: If specified, one of ``'comments'``, or ``'submissions'``
             to yield only results of that type.
@@ -1582,7 +1585,7 @@ def edited(self, only=None, **generator_kwargs):
         )
 
     def inbox(self, **generator_kwargs):
-        """Return a ListingGenerator for moderator messages.
+        """Return a :class:`.ListingGenerator` for moderator messages.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.
@@ -1606,13 +1609,16 @@ def inbox(self, **generator_kwargs):
         )
 
     def log(self, action=None, mod=None, **generator_kwargs):
-        """Return a ListingGenerator for moderator log entries.
+        """Return a :class:`.ListingGenerator` for moderator log entries.
 
         :param action: If given, only return log entries for the specified
             action.
         :param mod: If given, only return log entries for actions made by the
             passed in Redditor.
 
+        Additional keyword arguments are passed in the initialization of
+        :class:`.ListingGenerator`.
+
         To print the moderator and subreddit of the last 5 modlog entries try:
 
         .. code:: python
@@ -1630,7 +1636,7 @@ def log(self, action=None, mod=None, **generator_kwargs):
         )
 
     def modqueue(self, only=None, **generator_kwargs):
-        """Return a ListingGenerator for comments/submissions in the modqueue.
+        """Return a :class:`.ListingGenerator` for modqueue items.
 
         :param only: If specified, one of ``'comments'``, or ``'submissions'``
             to yield only results of that type.
@@ -1679,7 +1685,7 @@ def removal_reasons(self):
         return SubredditRemovalReasons(self.subreddit)
 
     def reports(self, only=None, **generator_kwargs):
-        """Return a ListingGenerator for reported comments and submissions.
+        """Return a :class:`.ListingGenerator` for reported comments and submissions.
 
         :param only: If specified, one of ``'comments'``, or ``'submissions'``
             to yield only results of that type.
@@ -1709,7 +1715,7 @@ def settings(self):
         return self.subreddit._reddit.get(url)["data"]
 
     def spam(self, only=None, **generator_kwargs):
-        """Return a ListingGenerator for spam comments and submissions.
+        """Return a :class:`.ListingGenerator` for spam comments and submissions.
 
         :param only: If specified, one of ``'comments'``, or ``'submissions'``
             to yield only results of that type.
@@ -1733,7 +1739,7 @@ def spam(self, only=None, **generator_kwargs):
         )
 
     def unmoderated(self, **generator_kwargs):
-        """Return a ListingGenerator for unmoderated submissions.
+        """Return a :class:`.ListingGenerator` for unmoderated submissions.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.
@@ -1753,7 +1759,7 @@ def unmoderated(self, **generator_kwargs):
         )
 
     def unread(self, **generator_kwargs):
-        """Return a ListingGenerator for unread moderator messages.
+        """Return a :class:`.ListingGenerator` for unread moderator messages.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.
@@ -1947,7 +1953,7 @@ class SubredditRelationship:
     """
 
     def __call__(self, redditor=None, **generator_kwargs):
-        """Return a generator for Redditors belonging to this relationship.
+        """Return a :class:`.ListingGenerator` for Redditors in the relationship.
 
         :param redditor: When provided, yield at most a single
             :class:`~.Redditor` instance. This is useful to confirm if a
@@ -2947,7 +2953,7 @@ def create(self, name, content, reason=None, **other_settings):
         return new
 
     def revisions(self, **generator_kwargs):
-        """Return a generator for recent wiki revisions.
+        """Return a :class:`.ListingGenerator` for recent wiki revisions.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.

praw/models/reddit/wikipage.py

@@ -137,7 +137,7 @@ def revision(self, revision):
         )
 
     def revisions(self, **generator_kwargs):
-        """Return a generator for page revisions.
+        """Return a :class:`.ListingGenerator` for page revisions.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.

praw/models/redditors.py

@@ -12,6 +12,9 @@ def new(self, **generator_kwargs):
         """Return a :class:`.ListingGenerator` for new Redditors.
 
         :returns Redditor profiles, which are a type of :class:`.Subreddit`.
+
+        Additional keyword arguments are passed in the initialization of
+        :class:`.ListingGenerator`.
         """
         return ListingGenerator(
             self._reddit, API_PATH["users_new"], **generator_kwargs
@@ -21,6 +24,9 @@ def popular(self, **generator_kwargs):
         """Return a :class:`.ListingGenerator` for popular Redditors.
 
         :returns Redditor profiles, which are a type of :class:`.Subreddit`.
+
+        Additional keyword arguments are passed in the initialization of
+        :class:`.ListingGenerator`.
         """
         return ListingGenerator(
             self._reddit, API_PATH["users_popular"], **generator_kwargs
@@ -33,6 +39,8 @@ def search(self, query, **generator_kwargs):
 
         :returns :class:`.Redditor`\ s.
 
+        Additional keyword arguments are passed in the initialization of
+        :class:`.ListingGenerator`.
         """
         self._safely_add_arguments(generator_kwargs, "params", q=query)
         return ListingGenerator(