From 584c69d93c7d5cae2f25773789ae860a8472aca6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20Koch-Kramer?= <koch-kramer@web.de>
Date: Fri, 24 Aug 2018 00:23:19 +0200
Subject: [PATCH] Update docs and docstrings concerning highlights

---
 docs/cli-options.rst       |  7 +++++++
 instaloader/instaloader.py |  8 ++++++--
 instaloader/structures.py  | 22 ++++++++++++++++++++++
 3 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/docs/cli-options.rst b/docs/cli-options.rst
index 34d3511..afc971a 100644
--- a/docs/cli-options.rst
+++ b/docs/cli-options.rst
@@ -115,6 +115,13 @@ What to Download of each Profile
    Also **download stories** of each profile that is downloaded. Requires
    :option:`--login`.
 
+.. option:: --highlights
+
+   Also **download highlights** of each profile that is downloaded. Requires
+   :option:`--login`.
+
+   .. versionadded:: 4.1
+
 .. option:: --tagged
 
    Also download posts where each profile is tagged.
diff --git a/instaloader/instaloader.py b/instaloader/instaloader.py
index bcd2228..f5ac2eb 100644
--- a/instaloader/instaloader.py
+++ b/instaloader/instaloader.py
@@ -494,7 +494,9 @@ class Instaloader:
     @_requires_login
     def get_highlights(self, user: Union[int, Profile]) -> Iterator[Highlight]:
         """Get all highlights from a user.
-        To use this, one needs to be logged in
+        To use this, one needs to be logged in.
+
+        .. versionadded:: 4.1
 
         :param user: ID or Profile of the user whose highlights should get fetched.
         """
@@ -517,7 +519,9 @@ class Instaloader:
                             storyitem_filter: Optional[Callable[[StoryItem], bool]] = None) -> None:
         """
         Download available highlights from a user whose ID is given.
-        To use this, one needs to be logged in
+        To use this, one needs to be logged in.
+
+        .. versionadded:: 4.1
 
         :param user: ID or Profile of the user whose highlights should get downloaded.
         :param fast_update: If true, abort when first already-downloaded picture is encountered
diff --git a/instaloader/structures.py b/instaloader/structures.py
index 96de483..69bdcb8 100644
--- a/instaloader/structures.py
+++ b/instaloader/structures.py
@@ -869,6 +869,28 @@ class Story:
 
 
 class Highlight(Story):
+    """
+    Structure representing a user's highlight with its associated story items.
+
+    Provides methods for accessing highlight properties, as well as :meth:`Highlight.get_items` to request associated
+    :class:`StoryItem` nodes. Highlights are returned by :meth:`Instaloader.get_highlights`.
+
+    With a logged-in :class:`Instaloader` instance `L`, you may download all highlights of a :class:`Profile` instance
+    USER with::
+
+       for highlight in L.get_highlights(USER):
+           # highlight is a Highlight object
+           for item in highlight.get_items():
+               # item is a StoryItem object
+               L.download_storyitem(item, '{}/{}'.format(highlight.owner_username, highlight.title))
+
+    This class implements == and is hashable.
+
+    :param context: :class:`InstaloaderContext` instance used for additional queries if necessary.
+    :param node: Dictionary containing the available information of the highlight as returned by Instagram.
+    :param owner: :class:`Profile` instance representing the owner profile of the highlight.
+
+    .. versionadded:: 4.1"""
 
     def __init__(self, context: InstaloaderContext, node: Dict[str, Any], owner: Optional[Profile] = None):
         super().__init__(context, node)