docs: docstring simplification and other improvements

britishcycling_clubs/manager.py

@@ -16,11 +16,14 @@
 
 
 class MemberCounts(TypedDict):
-    """Return type for `get_manager_member_counts()`."""
+    """Return type for `get_manager_member_counts()` function."""
 
     active: int
+    """Value from 'Active Club Members' tab."""
     new: int
+    """Value from 'New Club Subscriptions' tab."""
     expired: int
+    """Value from 'Expired Club Members' tab."""
 
 
 def get_manager_member_counts(
@@ -32,11 +35,6 @@ def get_manager_member_counts(
     """Get number of active, new, expired members from the Club Manager page.
 
     This is a slow operation (circa 10s), so get them all in one go.
-    From the club manager page, return the values from these tabs:
-
-    - 'Active Club Members'
-    - 'New Club Subscriptions'
-    - 'Expired Club Members'
 
     Parameters
     ----------
@@ -55,15 +53,13 @@ def get_manager_member_counts(
 
     Returns
     -------
-    dict[str, int]
-        keys: 'active', 'new', 'expired'
-        values: corresponding ints
+    `MemberCounts`
 
     Raises
     ------
-    ValueError if zero 'active members' would be returned, as this probably means
-    values hadn't populated correctly.
-
+    `ValueError`
+        if zero 'active members' would be returned, as this probably means
+        values hadn't populated correctly.
     """
     start_time = time.time()
     _log_info("Started timer for Playwright operations", start_time)

britishcycling_clubs/profile.py

@@ -1,4 +1,4 @@
-"""Functions to get info from a club's profile page."""
+"""Functions to get information from a club's profile page."""
 
 from typing import TypedDict
 
@@ -26,9 +26,12 @@ def get_profile_info(club_id: str) -> ProfileInfo:
 
     Returns
     -------
-    dict[str, str | int]
-        keys: 'club_name', 'total_members'
-        values: corresponding str or int
+    `ProfileInfo`
+
+    Raises
+    ------
+    `ValueError`
+        if information can't be located.
     """
     profile_url = club_profile_url(club_id)
     r = requests.get(profile_url, timeout=_REQUESTS_TIMEOUT)