[doc] Update ROADMAP.rst

Also update APISite.compare() and diff.html_comparator() documentation

Change-Id: I695e5262d631617628552bc3e76b1915695aed1f
---
M ROADMAP.rst
M pywikibot/diff.py
M pywikibot/site/_apisite.py
3 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/ROADMAP.rst b/ROADMAP.rst
index 1789436..3ddf33e 100644
--- a/ROADMAP.rst
+++ b/ROADMAP.rst
@@ -1,6 +1,9 @@
 Current release
 ---------------
 
+* Remove incorrect time normalization in :class:`page.Claim` (:phab:`T338748`, :phab:`T325860`, :phab:`T57755`)
+* Add support for other types of diffs in :meth:`Site.compare()<pywikibot.site._apisite.APISite.compare>`
+* Improvements for :func:`textlib.extract_sections` function (:phab:`T338748`)
 * Backport ``itertools.batched()`` from Python 3.12 which replaces :func:`tools.itertools.itergroup`
 * Upcast page types in :func:`pagegenerators.RecentChangesPageGenerator` (:phab:`T340450`)
 * Enable :meth:`FilePage.download()<pywikibot.FilePage.download>` to download thumbnails (:phab:`T247095`)
diff --git a/pywikibot/diff.py b/pywikibot/diff.py
index 7e3f78a..09caf2a 100644
--- a/pywikibot/diff.py
+++ b/pywikibot/diff.py
@@ -589,12 +589,16 @@
 
 
 def html_comparator(compare_string: str) -> Dict[str, List[str]]:
-    """List of added and deleted contexts from 'action=compare' html string.
+    """List of added and deleted contexts from ``action=compare`` html string.
 
-    This function is useful when combineds with site.py's "compare" method.
-    Site.compare() returns HTML that is useful for displaying on a page.
-    Here we use BeautifulSoup to get the un-HTML-ify the context of changes.
+    This function is useful when combined with :meth:`Site.compare()
+    <pywikibot.site._apisite.APISite.compare>` method. ``compare()``
+    returns HTML that is useful for displaying on a page. Here we use
+    ``BeautifulSoup`` to get the un-HTML-ify the context of changes.
     Finally we present the added and deleted contexts.
+
+    .. note:: ``beautifulsoup4`` package is needed for this function.
+
     :param compare_string: HTML string from MediaWiki API
     :return: deleted and added list of contexts
     """
diff --git a/pywikibot/site/_apisite.py b/pywikibot/site/_apisite.py
index 0674085..be67d92 100644
--- a/pywikibot/site/_apisite.py
+++ b/pywikibot/site/_apisite.py
@@ -2860,10 +2860,11 @@
         """
         Corresponding method to the 'action=compare' API action.
 
+        .. hint:: Use :func:`diff.html_comparator` function to parse
+           result.
+
         .. seealso: :api:`Compare`
 
-        See: https://en.wikipedia.org/w/api.php?action=help&modules=compare
-        Use pywikibot.diff's html_comparator() method to parse result.
         :param old: starting revision ID, title, Page, or Revision
         :param diff: ending revision ID, title, Page, or Revision
         :param difftype: type of diff. One of 'table' or 'inline'.

