From b0f2b367467bf69c9a66fde09a12d061aa72c33c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Guillot?=
 <323546+fguillot@users.noreply.github.com>
Date: Mon, 23 Mar 2026 21:26:18 -0700
Subject: [PATCH] docs(client): fix inaccurate and misleading docstrings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Fix typos: "excepted" → "except", "belongs" → "belong"
- Remove "False otherwise" from methods that only return True or raise
- Correct return descriptions for get_entries, get_feed_entries, and
  get_category_entries to reflect the actual dict return type
- Remove bogus Returns section from mark_feed_entries_as_read
---
 miniflux.py | 30 ++++++++++++++----------------
 1 file changed, 14 insertions(+), 16 deletions(-)

diff --git a/miniflux.py b/miniflux.py
index 2157046..05c2e93 100644
--- a/miniflux.py
+++ b/miniflux.py
@@ -180,10 +180,10 @@ def _handle_error_response(self, response: requests.Response) -> NoReturn:
 
     def flush_history(self) -> bool:
         """
-        Mark all read entries as removed excepted the starred ones.
+        Mark all read entries as removed except the starred ones.
 
         Returns:
-            bool: True if the operation was successfully scheduled, False otherwise.
+            bool: True if the operation was successfully scheduled.
         """
         endpoint = self._get_endpoint("/flush-history")
         response = self._session.delete(endpoint, timeout=self._timeout)
@@ -440,7 +440,7 @@ def refresh_all_feeds(self) -> bool:
         Refresh all feeds.
 
         Returns:
-            bool: True if the operation was successfully scheduled, False otherwise.
+            bool: True if the operation was successfully scheduled.
         Raises:
             ClientError: If the request fails.
         """
@@ -457,7 +457,7 @@ def refresh_feed(self, feed_id: int) -> bool:
         Args:
             feed_id (int): The feed ID.
         Returns:
-            bool: True if the operation was successfully scheduled, False otherwise.
+            bool: True if the operation was successfully scheduled.
         Raises:
             ClientError: If the request fails.
         """
@@ -469,12 +469,12 @@ def refresh_feed(self, feed_id: int) -> bool:
 
     def refresh_category(self, category_id: int) -> bool:
         """
-        Refreshes all feeds that belongs to the given category.
+        Refreshes all feeds that belong to the given category.
 
         Args:
             category_id (int): The category ID.
         Returns:
-            bool: True if the operation was successfully scheduled, False otherwise.
+            bool: True if the operation was successfully scheduled.
         Raises:
             ClientError: If the request fails.
         """
@@ -518,12 +518,12 @@ def get_feed_entry(self, feed_id: int, entry_id: int) -> dict:
 
     def get_feed_entries(self, feed_id: int, **kwargs) -> dict:
         """
-        Fetch all entries that belongs to the given feed.
+        Fetch all entries that belong to the given feed.
 
         Args:
             feed_id (int): The feed ID.
         Returns:
-            A list of dictionaries representing the entries.
+            A dictionary containing the total count and a list of entries.
         Raises:
             ClientError: If the request fails.
         """
@@ -607,8 +607,6 @@ def mark_feed_entries_as_read(self, feed_id: int) -> None:
 
         Args:
             feed_id (int): The feed ID.
-        Returns:
-            A list of dictionaries representing the entries.
         Raises:
             ClientError: If the request fails.
         """
@@ -639,7 +637,7 @@ def get_entries(self, **kwargs) -> dict:
         Fetch all entries.
 
         Returns:
-            A list of dictionaries representing the entries.
+            A dictionary containing the total count and a list of entries.
         Raises:
             ClientError: If the request fails.
         """
@@ -691,7 +689,7 @@ def update_entries(self, entry_ids: List[int], status: str) -> bool:
             entry_ids (list[int]): The entry IDs.
             status (str): The new status.
         Returns:
-            bool: True if the operation was successful, False otherwise.
+            bool: True if the operation was successful.
         Raises:
             ClientError: If the request fails.
         """
@@ -730,7 +728,7 @@ def toggle_bookmark(self, entry_id: int) -> bool:
         Args:
             entry_id (int): The entry ID.
         Returns:
-            bool: True if the operation was successful, False otherwise.
+            bool: True if the operation was successful.
         Raises:
             ClientError: If the request fails.
         """
@@ -747,7 +745,7 @@ def save_entry(self, entry_id: int) -> bool:
         Args:
             entry_id (int): The entry ID.
         Returns:
-            bool: True if the operation was successfully queued, False otherwise.
+            bool: True if the operation was successfully queued.
         Raises:
             ClientError: If the request fails.
         """
@@ -782,7 +780,7 @@ def update_enclosure(self, enclosure_id: int, media_progression: Optional[int] =
             enclosure_id (int): The enclosure ID.
             media_progression (int): The progression of the media.
         Returns:
-            bool: True if the operation was successful, False otherwise.
+            bool: True if the operation was successful.
         Raises:
             ClientError: If the request fails.
         """
@@ -837,7 +835,7 @@ def get_category_entries(self, category_id: int, **kwargs) -> dict:
         Args:
             category_id (int): The category ID.
         Returns:
-            A list of dictionaries representing the entries.
+            A dictionary containing the total count and a list of entries.
         Raises:
             ClientError: If the request fails.
         """