docs: shorten the readme and trim code comments

tests/test_audible.py

@@ -31,8 +31,7 @@ def calls(monkeypatch):
 
 
 def test_search_asks_for_the_first_page(calls):
-    """Audible's page parameter is 0-based: page=1 skips the only page of results
-    and a search like "Der Superpapagei" comes back empty."""
+    """Audible's page parameter is 0-based, page=1 skips the only page of hits."""
     results = asyncio.run(audible.search("Der Superpapagei"))
     assert [r.title for r in results] == ["Die drei ??? und der Super-Papagei"]
     assert calls and all(int(c["page"]) == 0 for c in calls)

tests/test_import_flow.py

@@ -316,8 +316,7 @@ def test_natural_track_order_in_flat_folder(client):
 
 
 def test_real_world_series_tree(client):
-    """Downloads laid out as Serie/Folgen/<Sammelordner>/<NNN - Titel>/CD/*.mp3,
-    with a Cover/ folder next to the CD folder."""
+    """Serie/Folgen/<Sammelordner>/<NNN - Titel>/CD/*.mp3, next to a Cover folder."""
     base = client.downloads / "Die Drei Fragezeichen" / "Folgen" / "3478632869 001-010"
     episodes = ["001 - Der Super - Papagei", "002 - Der Phantomsee", "003 - Der Karpatenhund"]
     for ep in episodes:
@@ -419,8 +418,7 @@ def test_bulk_items_series_then_scan_matches_by_episode_number(client):
 
 
 def test_merged_multipart_import(client):
-    """A multi-part episode ("Teil 1/2/3") imported as one audiobook: the client
-    merges the scanned entries and posts their files as a single item."""
+    """A multi-part episode ("Teil 1/2/3") imported as one audiobook."""
     root = client.tmp_path / "library" / "ddf"
     lib_id = client.post("/api/libraries", json={
         "name": "DDF", "media_type": "audiobook", "root_path": str(root),
@@ -484,8 +482,7 @@ def test_import_rejects_files_outside_download_dir(client):
 
 
 def test_merge_at_download_root_keeps_the_download_dir(client):
-    """Merging entries that sit directly in the download dir makes the item path
-    the download dir itself - which must never be removed."""
+    """Merging at the download root must not remove the download dir."""
     lib_id = client.post("/api/libraries", json={
         "name": "L", "media_type": "audiobook", "root_path": str(client.tmp_path / "l"),
     }).json()["id"]
@@ -509,8 +506,7 @@ def test_merge_at_download_root_keeps_the_download_dir(client):
 
 
 def test_merged_parts_clean_up_nested_source_folders(client):
-    """"100 - Toteninsel/A - Sphinx/CD/*.mp3" - every emptied level below the
-    merged item goes away, the cover folder keeps its parent alive."""
+    """Every emptied level below a merged item goes away, the cover folder stays."""
     lib_id = client.post("/api/libraries", json={
         "name": "L", "media_type": "audiobook", "root_path": str(client.tmp_path / "l"),
         "folder_template": "{Title}", "file_template": "{Title}",
@@ -584,8 +580,7 @@ def test_letter_folders_that_are_not_parts_stay_separate(client):
 
 
 def test_append_to_an_already_imported_audiobook(client):
-    """The Toteninsel case: part A got imported, B and C failed. They can be
-    added afterwards without moving anything back by hand."""
+    """The Toteninsel case: part A got imported, B and C failed."""
     root = client.tmp_path / "library" / "kids"
     lib_id = client.post("/api/libraries", json={
         "name": "K", "media_type": "audiobook", "root_path": str(root),
@@ -692,8 +687,7 @@ def test_search_passes_language_to_the_provider(client, monkeypatch):
 
 
 def test_folder_of_separate_books_is_flagged(client):
-    """One book per file (a series bought as single titles) still scans as one
-    entry - but gets flagged so the UI can offer to split it."""
+    """One book per file scans as one entry, but gets flagged for the UI."""
     got = client.downloads / "George R. R. Martin" / "A Game of Thrones"
     got.mkdir(parents=True)
     for name in ("1 - A Game of Thrones- A Song of Ice and Fire, Book 1 (Unabridged)",
@@ -734,8 +728,7 @@ def test_split_dirs_still_lists_every_file(client):
 
 
 def test_relocate_after_fixing_the_series(client):
-    """Audible files Harry Potter under "Wizarding World"; after correcting the
-    series the folder on disk should follow."""
+    """After correcting the series the folder on disk follows."""
     root = client.tmp_path / "library" / "english"
     lib_id = client.post("/api/libraries", json={
         "name": "english", "media_type": "audiobook", "root_path": str(root),
@@ -825,8 +818,7 @@ def test_relocate_refuses_to_overwrite(client):
 
 
 def test_files_moved_back_are_matched_against_imported_requests(client):
-    """Moving a library folder back into the download dir: the request still says
-    "imported", but its files are gone - the scan should suggest it anyway."""
+    """A request whose files left the library is suggested again."""
     root = client.tmp_path / "library" / "kids"
     lib_id = client.post("/api/libraries", json={
         "name": "kids", "media_type": "audiobook", "root_path": str(root),
@@ -893,8 +885,7 @@ def test_imported_request_with_files_in_place_is_still_refused(client):
 
 
 def test_two_titles_rendering_to_the_same_name_do_not_overwrite(client):
-    """Two books whose templates produce the same folder and file names must not
-    silently replace each other - that loses files and confuses ABS."""
+    """Two titles rendering to the same name must not overwrite each other."""
     root = client.tmp_path / "library" / "dcc"
     lib_id = client.post("/api/libraries", json={
         "name": "DCC", "media_type": "audiobook", "root_path": str(root),
@@ -932,8 +923,7 @@ def test_two_titles_rendering_to_the_same_name_do_not_overwrite(client):
 
 
 def test_scan_and_import_survive_a_name_that_is_not_utf8(client):
-    """A single Latin-1 byte in a folder name used to fail the whole scan with a
-    500 (UnicodeEncodeError: surrogates not allowed)."""
+    """A single Latin-1 byte in a folder name used to fail the whole scan."""
     broken = os.fsdecode(b"Die drei ??? - Die Fu\xdfball-Falle")
     folder = client.downloads / broken
     folder.mkdir()
@@ -968,8 +958,7 @@ def test_scan_and_import_survive_a_name_that_is_not_utf8(client):
 
 
 def test_loose_files_in_the_download_root_do_not_swallow_everything(client):
-    """Two loose audio files directly in the download dir used to make the whole
-    root look like one audiobook - and its early return hid every subfolder."""
+    """Loose files in the download root must not hide the subfolders."""
     (client.downloads / "Teil 01.mp3").write_bytes(b"")
     (client.downloads / "Teil 02.mp3").write_bytes(b"")
     for folge in ("Folge 1", "Folge 2"):

tests/test_naming.py

@@ -62,8 +62,7 @@ def test_missing_values_do_not_leave_dangling_separators():
 
 
 def test_narrator_uses_the_first_name_only():
-    """Two editions of one book differ by narrator; a full cast must not blow up
-    the folder name."""
+    """A full cast must not blow up the folder name."""
     fry = SimpleNamespace(title="Philosopher's Stone", authors="J.K. Rowling",
                           series="Harry Potter", volume=1, year=None,
                           narrator="Stephen Fry")

tests/test_ui_dialogs.py

@@ -78,8 +78,7 @@ def test_dialogs_start_closed(page):
 
 
 def test_hidden_elements_really_are_hidden(page):
-    """A CSS display rule can override the hidden attribute - it did for the
-    dialog and again for the progress bar."""
+    """A CSS display rule can override the hidden attribute."""
     page.click("nav button[data-view=import]")
     for sel in ("#import-progress", "#import-btn", "#import-table", "#missing-badge"):
         assert not page.locator(sel).is_visible(), sel