Add documentation for List

diff --git a/docs/v2_models.rst b/docs/v2_models.rst
index 0923791e0bed697496026a8431b39a04a7bffa9f..93cd0cd41a725da30696b9730a0c6f3fdc8f1b05 100644 (file)
--- a/docs/v2_models.rst
+++ b/docs/v2_models.rst
@@ -1,16 +1,17 @@
 .. _v2_models_reference:
 
+.. currentmodule:: tweepy
+
 ******
 Models
 ******
 
 .. versionadded:: 4.0
 
-.. class:: tweepy.List
-
-   .. versionadded:: 4.4
+:class:`List`
+=============
 
-   :reference: https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/lists
+.. autoclass:: List()
 
 .. class:: tweepy.Media
 

diff --git a/tweepy/list.py b/tweepy/list.py
index 3c36ed5c7d069cdc4c4c9e60d2e2b4db614bb1b5..b2a5044246f2b6210fb07e5302defe2a08bf1907 100644 (file)
--- a/tweepy/list.py
+++ b/tweepy/list.py
@@ -7,6 +7,48 @@ from tweepy.utils import parse_datetime
 
 
 class List(HashableID, DataMapping):
+    """The list object contains `Twitter Lists`_ metadata describing the
+    referenced List. The List object is the primary object returned in the List
+    lookup endpoint. When requesting additional List fields on this endpoint,
+    simply use the fields parameter ``list.fields``.
+
+    At the moment, the List object cannot be found as a child object from any
+    other data object. However, user objects can be found and expanded in the
+    user resource. These objects are available for expansion by adding
+    ``owner_id`` to the ``expansions`` query parameter. Use the expansion with
+    the field parameter: ``list.fields`` when requesting additional fields to
+    complete the primary List object and ``user.fields`` to complete the
+    expansion object.
+
+    .. versionadded:: 4.4
+
+    Attributes
+    ----------
+    data : dict
+        The JSON data representing the List.
+    id : str
+        The unique identifier of this List.
+    name : str
+        The name of the List, as defined when creating the List.
+    created_at : datetime.datetime | None
+        The UTC datetime that the List was created on Twitter.
+    description : str | None
+        A brief description to let users know about the List.
+    follower_count : int | None
+        Shows how many users follow this List,
+    member_count : int | None
+        Shows how many members are part of this List.
+    private : bool | None
+        Indicates if the List is private.
+    owner_id : str | None
+        Unique identifier of this List's owner.
+
+    References
+    ----------
+    https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/lists
+
+    .. _Twitter Lists: https://help.twitter.com/en/using-twitter/twitter-lists
+    """
 
     __slots__ = (
         "data", "id", "name", "created_at", "description", "follower_count",