From 134c4a60e9106a9c677512b52e34f82f01c361c3 Mon Sep 17 00:00:00 2001
From: Mizaki <jinxybob@hotmail.com>
Date: Thu, 24 Nov 2022 23:26:48 +0000
Subject: [PATCH] Add some docstrings.

---
 comictalker/comictalkerapi.py |  3 ++-
 comictalker/talker_utils.py   |  5 +++--
 comictalker/talkerbase.py     | 20 ++++++++++++--------
 3 files changed, 17 insertions(+), 11 deletions(-)

diff --git a/comictalker/comictalkerapi.py b/comictalker/comictalkerapi.py
index 04614fc..e9c3bbe 100644
--- a/comictalker/comictalkerapi.py
+++ b/comictalker/comictalkerapi.py
@@ -24,7 +24,7 @@ logger = logging.getLogger(__name__)
 
 
 def get_comic_talker(source_name: str) -> type[ComicTalker]:
-    # Retrieve the available sources modules
+    """Retrieve the available sources modules"""
     sources = get_talkers()
     if source_name not in sources:
         raise TalkerError(source=source_name, code=4, desc="The talker does not exist")
@@ -34,4 +34,5 @@ def get_comic_talker(source_name: str) -> type[ComicTalker]:
 
 
 def get_talkers():
+    """Returns all comic talker modules NOT objects"""
     return {"comicvine": comictalker.talkers.comicvine.ComicVineTalker}
diff --git a/comictalker/talker_utils.py b/comictalker/talker_utils.py
index 4ea7ca2..a039cfc 100644
--- a/comictalker/talker_utils.py
+++ b/comictalker/talker_utils.py
@@ -33,7 +33,7 @@ logger = logging.getLogger(__name__)
 def map_comic_issue_to_metadata(
     issue_results: ComicIssue, source: str, remove_html_tables: bool = False, use_year_volume: bool = False
 ) -> GenericMetadata:
-    # Now, map the ComicIssue data to generic metadata
+    """Maps ComicIssue to generic metadata"""
     metadata = GenericMetadata()
     metadata.is_empty = False
 
@@ -101,7 +101,8 @@ def parse_date_str(date_str: str) -> tuple[int | None, int | None, int | None]:
     return day, month, year
 
 
-def cleanup_html(string: str, remove_html_tables: bool) -> str:
+def cleanup_html(string: str, remove_html_tables: bool = False) -> str:
+    """Cleans HTML code from any text. Will remove any HTML tables with remove_html_tables"""
     if string is None:
         return ""
     # find any tables
diff --git a/comictalker/talkerbase.py b/comictalker/talkerbase.py
index 82417c2..52617b7 100644
--- a/comictalker/talkerbase.py
+++ b/comictalker/talkerbase.py
@@ -156,7 +156,7 @@ class TalkerDataError(TalkerError):
 
 # Class talkers instance
 class ComicTalker:
-    """This is the class for mysource."""
+    """The base class for all comic source talkers"""
 
     def __init__(self) -> None:
         # Identity name for the information source etc.
@@ -165,10 +165,10 @@ class ComicTalker:
         )  # Can use this to test if custom talker has been configured
         self.static_options: SourceStaticOptions = SourceStaticOptions()
 
-    def check_api_key(self, key: str, url: str):
+    def check_api_key(self, key: str, url: str) -> bool:
+        """If the talker has or requires an API key, this function should test its validity"""
         raise NotImplementedError
 
-    # Search for series/volumes
     def search_for_series(
         self,
         series_name: str,
@@ -176,21 +176,25 @@ class ComicTalker:
         refresh_cache: bool = False,
         literal: bool = False,
     ) -> list[ComicVolume]:
+        """Searches for the series/volumes with the given series_name
+        callback is used for...
+        refresh_cache signals if the data in the cache should be used
+        literal indicates that no articles (a, the, etc.) should be removed when searching"""
         raise NotImplementedError
 
-    # Get issues in a series/volume
     def fetch_issues_by_volume(self, series_id: int) -> list[ComicIssue]:
+        """Expected to return a list of issues with a given series/volume ID"""
         raise NotImplementedError
 
-    # Get issue or volume information
     def fetch_comic_data(self, issue_id: int = 0, series_id: int = 0, issue_number: str = "") -> GenericMetadata:
         """This function is expected to handle a few possibilities:
-        1. Only series_id. Retrieve the SERIES/VOLUME information only.
-        2. series_id and issue_number. Retrieve the ISSUE information.
-        3. Only issue_id. Retrieve the ISSUE information."""
+        1. Only series_id passed in: Retrieve the SERIES/VOLUME information only
+        2. series_id and issue_number: Retrieve the ISSUE information
+        3. Only issue_id: Retrieve the ISSUE information"""
         raise NotImplementedError
 
     def fetch_issues_by_volume_issue_num_and_year(
         self, volume_id_list: list[int], issue_number: str, year: str | int | None
     ) -> list[ComicIssue]:
+        """Searches for a list of issues within the given year. Used solely by issueidentifer"""
         raise NotImplementedError