From 40467ee887d2bd190d3b1b351a2e13c375b0e74c Mon Sep 17 00:00:00 2001
From: PokestarFan <13932583+PokestarFan@users.noreply.github.com>
Date: Wed, 25 Dec 2019 12:01:53 -0500
Subject: [PATCH] Add listing generator disclaimer docstrings (#1168)

Update ListingGenerator references and add in disclaimers
---
 praw/models/front.py                     |  2 +-
 praw/models/inbox.py                     | 14 +++++------
 praw/models/listing/mixins/base.py       |  8 +++---
 praw/models/listing/mixins/gilded.py     |  2 +-
 praw/models/listing/mixins/redditor.py   | 12 ++++-----
 praw/models/listing/mixins/rising.py     |  4 +--
 praw/models/listing/mixins/submission.py |  2 +-
 praw/models/listing/mixins/subreddit.py  |  2 +-
 praw/models/reddit/live.py               |  6 +++++
 praw/models/reddit/subreddit.py          | 32 ++++++++++++++----------
 praw/models/reddit/wikipage.py           |  2 +-
 praw/models/redditors.py                 |  8 ++++++
 praw/models/subreddits.py                | 26 ++++++++++++++++---
 praw/models/user.py                      |  6 ++---
 14 files changed, 82 insertions(+), 44 deletions(-)

diff --git a/praw/models/front.py b/praw/models/front.py
index bcf800535..f195621c9 100644
--- a/praw/models/front.py
+++ b/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`.
diff --git a/praw/models/inbox.py b/praw/models/inbox.py
index 8376ebcf6..38a5a34be 100644
--- a/praw/models/inbox.py
+++ b/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).
 
diff --git a/praw/models/listing/mixins/base.py b/praw/models/listing/mixins/base.py
index 12aa32308..fb8dd13f3 100644
--- a/praw/models/listing/mixins/base.py
+++ b/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).
diff --git a/praw/models/listing/mixins/gilded.py b/praw/models/listing/mixins/gilded.py
index 91861cd3d..8975d4cbe 100644
--- a/praw/models/listing/mixins/gilded.py
+++ b/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`.
diff --git a/praw/models/listing/mixins/redditor.py b/praw/models/listing/mixins/redditor.py
index e4f6b7e44..d0bd4498b 100644
--- a/praw/models/listing/mixins/redditor.py
+++ b/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.
diff --git a/praw/models/listing/mixins/rising.py b/praw/models/listing/mixins/rising.py
index 217557a04..b383d1834 100644
--- a/praw/models/listing/mixins/rising.py
+++ b/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`.
diff --git a/praw/models/listing/mixins/submission.py b/praw/models/listing/mixins/submission.py
index 44f2e7bdb..ad255381a 100644
--- a/praw/models/listing/mixins/submission.py
+++ b/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`.
diff --git a/praw/models/listing/mixins/subreddit.py b/praw/models/listing/mixins/subreddit.py
index 5febcbe18..a9c78580f 100644
--- a/praw/models/listing/mixins/subreddit.py
+++ b/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`.
diff --git a/praw/models/reddit/live.py b/praw/models/reddit/live.py
index b044eed1c..481a0b4f3 100644
--- a/praw/models/reddit/live.py
+++ b/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
diff --git a/praw/models/reddit/subreddit.py b/praw/models/reddit/subreddit.py
index 5e93d50de..9768d41f7 100644
--- a/praw/models/reddit/subreddit.py
+++ b/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`.
diff --git a/praw/models/reddit/wikipage.py b/praw/models/reddit/wikipage.py
index 16b09edc6..929c42036 100644
--- a/praw/models/reddit/wikipage.py
+++ b/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`.
diff --git a/praw/models/redditors.py b/praw/models/redditors.py
index c0bf6341e..6587de9de 100644
--- a/praw/models/redditors.py
+++ b/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(
diff --git a/praw/models/subreddits.py b/praw/models/subreddits.py
index b9e73c271..2f60e30c3 100644
--- a/praw/models/subreddits.py
+++ b/praw/models/subreddits.py
@@ -14,25 +14,41 @@ def _to_list(subreddit_list):
         return ",".join([str(x) for x in subreddit_list])
 
     def default(self, **generator_kwargs):
-        """Return a :class:`.ListingGenerator` for default subreddits."""
+        """Return a :class:`.ListingGenerator` for default subreddits.
+
+        Additional keyword arguments are passed in the initialization of
+        :class:`.ListingGenerator`.
+        """
         return ListingGenerator(
             self._reddit, API_PATH["subreddits_default"], **generator_kwargs
         )
 
     def gold(self, **generator_kwargs):
-        """Return a :class:`.ListingGenerator` for gold subreddits."""
+        """Return a :class:`.ListingGenerator` for gold subreddits.
+
+        Additional keyword arguments are passed in the initialization of
+        :class:`.ListingGenerator`.
+        """
         return ListingGenerator(
             self._reddit, API_PATH["subreddits_gold"], **generator_kwargs
         )
 
     def new(self, **generator_kwargs):
-        """Return a :class:`.ListingGenerator` for new subreddits."""
+        """Return a :class:`.ListingGenerator` for new subreddits.
+
+        Additional keyword arguments are passed in the initialization of
+        :class:`.ListingGenerator`.
+        """
         return ListingGenerator(
             self._reddit, API_PATH["subreddits_new"], **generator_kwargs
         )
 
     def popular(self, **generator_kwargs):
-        """Return a :class:`.ListingGenerator` for popular subreddits."""
+        """Return a :class:`.ListingGenerator` for popular subreddits.
+
+        Additional keyword arguments are passed in the initialization of
+        :class:`.ListingGenerator`.
+        """
         return ListingGenerator(
             self._reddit, API_PATH["subreddits_popular"], **generator_kwargs
         )
@@ -71,6 +87,8 @@ def search(self, query, **generator_kwargs):
 
         :param query: The query string to filter subreddits by.
 
+        Additional keyword arguments are passed in the initialization of
+        :class:`.ListingGenerator`.
         """
         self._safely_add_arguments(generator_kwargs, "params", q=query)
         return ListingGenerator(
diff --git a/praw/models/user.py b/praw/models/user.py
index e469fe14c..3c700c4f4 100644
--- a/praw/models/user.py
+++ b/praw/models/user.py
@@ -56,7 +56,7 @@ def blocked(self):
         return self._reddit.get(API_PATH["blocked"])
 
     def contributor_subreddits(self, **generator_kwargs):
-        """Return a ListingGenerator of subreddits user is a contributor of.
+        """Return a :class:`.ListingGenerator` of subreddits user is a contributor of.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.
@@ -100,7 +100,7 @@ def me(self, use_cache=True):  # pylint: disable=invalid-name
         return self._me
 
     def moderator_subreddits(self, **generator_kwargs):
-        """Return a ListingGenerator of subreddits the user moderates (DEPRECATED).
+        """Return a :class:`.ListingGenerator` of moderated subreddits.
 
         ..warning:: (Deprecated) This method will be removed in the next major
                     version of PRAW. Please use :meth:`.Redditor.moderated`
@@ -131,7 +131,7 @@ def multireddits(self):
         return self._reddit.get(API_PATH["my_multireddits"])
 
     def subreddits(self, **generator_kwargs):
-        """Return a ListingGenerator of subreddits the user is subscribed to.
+        """Return a :class:`.ListingGenerator` of subreddits the user is subscribed to.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.