Changelog and user guide for #254.

CHANGES.rst

@@ -15,14 +15,27 @@ Unreleased
   reduce false negatives by using approximate content matching,
   and make it possible to re-run the plugin for existing entries.
   (:issue:`202`)
-* Add :attr:`~Reader.after_feed_update_hooks`,
-  which allow running arbitrary actions for updated feeds.
+* Allow running arbitrary actions for updated feeds
+  via :attr:`~Reader.after_feed_update_hooks`.
   (:issue:`202`)
+
 * Allow :meth:`~Reader.mark_entry_as_read`
   and :meth:`~Reader.mark_entry_as_important`
   to mark an entry as unread/unimportant through a boolean flag.
   (:issue:`256`)
 
+* Record the time an entry is marked as read/important,
+  and make it available through :attr:`~Entry.read_modified` and
+  :attr:`~Entry.important_modified`.
+  Allow setting it to a user-provided value using the ``modified``
+  argument of :meth:`~Reader.mark_entry_as_read`
+  and :meth:`~Reader.mark_entry_as_important`.
+  (:issue:`254`)
+* Make :mod:`~reader.plugins.entry_dedupe` copy
+  :attr:`~Entry.read_modified` and :attr:`~Entry.important_modified`
+  from the duplicates to the new entry.
+  (:issue:`254`)
+
 * In the web application, allow marking an entry as "don't care"
   (read + unimportant explicitly set by the user) with a single button.
   (:issue:`254`)

docs/guide.rst

@@ -289,15 +289,25 @@ Entry flags
 Entries can be marked as :meth:`read <Reader.mark_entry_as_read>`
 or as :meth:`important <Reader.mark_entry_as_important>`.
 
-These flags can be used for filtering::
+The flags can be used for filtering::
 
     >>> reader.mark_entry_as_read(entries[0])
     >>> entries = list(reader.get_entries(feed=feed, read=False))
     >>> for entry in entries[:2]:
-    ...     print(entry.feed.title, '-', entry.title)
+    ...     printentry.title)
     ...
-    Hello Internet - H.I. #135: Place Your Bets
-    Hello Internet - # H.I. 134: Boxing Day
+    H.I. #135: Place Your Bets
+    # H.I. 134: Boxing Day
+
+
+The time when a flag was last modified is recorded, and is available via
+:attr:`~Entry.read_modified` and :attr:`~Entry.important_modified`::
+
+    >>> for entry in reader.get_entries(feed=feed, limit=2):
+    ...     print(entry.title, '-', entry.read, entry.read_modified)
+    ...
+    H.I. #136: Dog Bingo - True 2021-10-08 08:00:00+00:00
+    H.I. #135: Place Your Bets - False None