From 25f2dadd2d9e5be79ad29c755dd735d1c2000ea1 Mon Sep 17 00:00:00 2001
From: Eric Joanis <eric.joanis@nrc-cnrc.gc.ca>
Date: Tue, 17 Dec 2024 14:33:14 -0500
Subject: [PATCH] refactor: give the API convert functions self-documenting
 names

%s/convert_to_readalong/convert_prealigned_text_to_readalong/g
%s/convert_to_offline_html/convert_prealigned_text_to_offline_html/g
---
 readalongs/api.py | 17 +++++++++++------
 test/test_api.py  |  4 ++--
 2 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/readalongs/api.py b/readalongs/api.py
index afea9f68..4a7f2b30 100644
--- a/readalongs/api.py
+++ b/readalongs/api.py
@@ -34,12 +34,17 @@ class like pathlib.Path. Warning: don't just use "/some/path/config.json"
 
 Additional API function:
 
-convert_to_readalong(sentences: Sequence[Sequence[Token]], language: Sequence[str]) -> str:
+convert_prealigned_text_to_readalong():
     convert a list of sentences into a readalong XML string ready to print to file.
     Just like align and make_xml, this function expects a black line (empty list) to
     make a paragraph break, and two consecutive blank lines to make a page break.
     Unlike the other functions here, this function is not a wrapper around the CLI and
-    it just returns the string, non status.
+    it just returns the string, with no status.
+
+convert_prealigned_text_to_offline_html():
+    same as convert_prealigned_text_to_readalong, but also creates an offline HTML file.
+
+See their respective docstrings for more details.
 """
 
 import io
@@ -218,7 +223,7 @@ def __init__(
         self.is_word = is_word if is_word is not None else bool(time is not None)
 
 
-def convert_to_readalong(
+def convert_prealigned_text_to_readalong(
     sentences: Sequence[Sequence[Token]],
     language: Sequence[str] = ("und",),
 ) -> str:
@@ -267,7 +272,7 @@ def convert_to_readalong(
     return xml_text + "\n"
 
 
-def convert_to_offline_html(
+def convert_prealigned_text_to_offline_html(
     sentences: Sequence[Sequence[Token]],
     audio_file_name: Union[str, os.PathLike],
     language: Sequence[str] = ("und",),
@@ -275,7 +280,7 @@ def convert_to_offline_html(
     header: str = DEFAULT_HEADER,
     subheader: str = DEFAULT_SUBHEADER,
 ) -> Tuple[str, str]:
-    """Convert a list of sentences/paragraphs/pages of tokens, with corresponding autdio,
+    """Convert a list of sentences/paragraphs/pages of tokens, with corresponding audio,
     into a readalong Offline HTML
 
     Args:
@@ -295,7 +300,7 @@ def convert_to_offline_html(
          - the readalong XML file contents, ready to print to .readalong
     """
 
-    readalong_xml = convert_to_readalong(sentences, language)
+    readalong_xml = convert_prealigned_text_to_readalong(sentences, language)
     try:
         readalong_file = tempfile.NamedTemporaryFile(
             "w", encoding="utf8", delete=False, suffix=".readalong"
diff --git a/test/test_api.py b/test/test_api.py
index 732f7eea..70a1bfdc 100755
--- a/test/test_api.py
+++ b/test/test_api.py
@@ -121,7 +121,7 @@ def test_deprecated_prepare(self):
 
     def test_convert_to_readalong(self):
 
-        readalong = api.convert_to_readalong(self.sentences_to_convert)
+        readalong = api.convert_prealigned_text_to_readalong(self.sentences_to_convert)
         # print(readalong)
 
         # Make the reference by calling align with the same text and adjusting
@@ -155,7 +155,7 @@ def test_convert_to_readalong(self):
         self.assertEqual(readalong, align_result)
 
     def test_convert_to_offline_html(self):
-        html, _ = api.convert_to_offline_html(
+        html, _ = api.convert_prealigned_text_to_offline_html(
             self.sentences_to_convert,
             str(self.data_dir / "noise.mp3"),
             subheader="by Jove!",