Clean up code comments and docstrings (#318)

Signed-off-by: rany <[email protected]>

src/edge_playback/__init__.py

@@ -1,8 +1,5 @@
-#!/usr/bin/env python3
-
-"""
-Init file for the package.
-"""
+"""The edge_playback package wraps the functionality of mpv and edge-tts to generate
+text-to-speech (TTS) using edge-tts and then plays back the generated audio using mpv."""
 
 from .__main__ import _main
 

src/edge_playback/__main__.py

@@ -1,8 +1,4 @@
-#!/usr/bin/env python3
-
-"""
-Playback TTS with subtitles using edge-tts and mpv.
-"""
+"""Main entrypoint for the edge-playback package."""
 
 import os
 import subprocess

src/edge_tts/__init__.py

@@ -1,6 +1,6 @@
-"""
-__init__ for edge_tts
-"""
+"""edge-tts allows you to use Microsoft Edge's online text-to-speech service without
+needing Windows or the Edge browser. It Microsoft Edge's internal API to generate
+speech from text."""
 
 from . import exceptions
 from .communicate import Communicate

src/edge_tts/__main__.py

@@ -1,6 +1,4 @@
-"""
-__main__ for edge_tts.
-"""
+"""Main entrypoint for the edge-tts package."""
 
 from .util import main
 

src/edge_tts/communicate.py

@@ -1,6 +1,5 @@
-"""
-Communicate package.
-"""
+"""Communicate with the service. Only the Communicate class should be used by
+end-users. The other classes and functions are for internal use only."""
 
 import asyncio
 import concurrent.futures

src/edge_tts/constants.py

@@ -1,6 +1,4 @@
-"""
-Constants for the Edge TTS project.
-"""
+"""Constants for the edge_tts package."""
 
 BASE_URL = "speech.platform.bing.com/consumer/speech/synthesize/readaloud"
 TRUSTED_CLIENT_TOKEN = "6A5AA1D4EAFF4E9FB37E23D68491D6F4"

src/edge_tts/drm.py

@@ -1,4 +1,6 @@
-"""DRM module for handling DRM operations with clock skew correction."""
+"""DRM module is used to handle DRM operations with clock skew correction.
+Currently the only DRM operation is generating the Sec-MS-GEC token value
+used in all API requests to Microsoft Edge's online text-to-speech service."""
 
 import hashlib
 from datetime import datetime as dt
@@ -40,10 +42,10 @@ def adj_clock_skew_seconds(skew_seconds: float) -> None:
     @staticmethod
     def get_unix_timestamp() -> float:
         """
-        Gets the current timestamp in Windows file time format with clock skew correction.
+        Gets the current timestamp in Unix format with clock skew correction.
 
         Returns:
-            float: The current timestamp in Windows file time format.
+            float: The current timestamp in Unix format with clock skew correction.
         """
         return dt.now(tz.utc).timestamp() + DRM.clock_skew_seconds
 
@@ -101,7 +103,7 @@ def generate_sec_ms_gec() -> str:
         """
         Generates the Sec-MS-GEC token value.
 
-        This function generates a token value based on the current time in Windows file time format,
+        This function generates a token value based on the current time in Windows file time format
         adjusted for clock skew, and rounded down to the nearest 5 minutes. The token is then hashed
         using SHA256 and returned as an uppercased hex digest.
 
@@ -112,7 +114,7 @@ def generate_sec_ms_gec() -> str:
             https://github.com/rany2/edge-tts/issues/290#issuecomment-2464956570
         """
 
-        # Get the current timestamp in Windows file time format with clock skew correction
+        # Get the current timestamp in Unix format with clock skew correction
         ticks = DRM.get_unix_timestamp()
 
         # Switch to Windows file time epoch (1601-01-01 00:00:00 UTC)

src/edge_tts/exceptions.py

@@ -1,28 +1,28 @@
-"""Exceptions for the Edge TTS project."""
+"""Custom exceptions for the edge-tts package."""
 
 
-class BaseEdgeTTSException(Exception):
-    """Base exception for the Edge TTS project."""
+class EdgeTTSException(Exception):
+    """Base exception for the edge-tts package."""
 
 
-class UnknownResponse(BaseEdgeTTSException):
+class UnknownResponse(EdgeTTSException):
     """Raised when an unknown response is received from the server."""
 
 
-class UnexpectedResponse(BaseEdgeTTSException):
+class UnexpectedResponse(EdgeTTSException):
     """Raised when an unexpected response is received from the server.
 
     This hasn't happened yet, but it's possible that the server will
     change its response format in the future."""
 
 
-class NoAudioReceived(BaseEdgeTTSException):
+class NoAudioReceived(EdgeTTSException):
     """Raised when no audio is received from the server."""
 
 
-class WebSocketError(BaseEdgeTTSException):
+class WebSocketError(EdgeTTSException):
     """Raised when a WebSocket error occurs."""
 
 
-class SkewAdjustmentError(BaseEdgeTTSException):
+class SkewAdjustmentError(EdgeTTSException):
     """Raised when an error occurs while adjusting the clock skew."""

src/edge_tts/models.py

@@ -1,4 +1,5 @@
-"""Models for the Edge TTS module."""
+"""This module contains the TTSConfig dataclass, which represents the
+internal TTS configuration for edge-tts's Communicate class."""
 
 import re
 from dataclasses import dataclass
@@ -7,7 +8,7 @@
 @dataclass
 class TTSConfig:
     """
-    Represents the internal TTS configuration for Edge TTS's communicate class.
+    Represents the internal TTS configuration for edge-tts's Communicate class.
     """
 
     voice: str

src/edge_tts/submaker.py

@@ -1,9 +1,4 @@
-"""
-SubMaker package for the Edge TTS project.
-
-SubMaker is a package that makes the process of creating subtitles with
-information provided by the service easier.
-"""
+"""SubMaker module is used to generate subtitles from WordBoundary events."""
 
 import math
 from typing import List, Tuple
@@ -37,20 +32,23 @@ def mktimestamp(time_unit: float) -> str:
 
 class SubMaker:
     """
-    SubMaker class
+    SubMaker is used to generate subtitles from WordBoundary messages.
     """
 
     def __init__(self) -> None:
         """
-        SubMaker constructor.
+        SubMaker constructor initializes the list of subtitles and the list of offsets.
+
+        Returns:
+            None
         """
         self.offset: List[Tuple[float, float]] = []
         self.subs: List[str] = []
 
     def create_sub(self, timestamp: Tuple[float, float], text: str) -> None:
         """
-        create_sub creates a subtitle with the given timestamp and text
-        and adds it to the list of subtitles
+        create_sub creates a subtitle from the given timestamp and text,
+        and appends it to the list of subtitles.
 
         Args:
             timestamp (tuple): The offset and duration of the subtitle.

src/edge_tts/util.py

@@ -1,6 +1,4 @@
-"""
-Main package.
-"""
+"""Utility functions for the command line interface. Used by the main module."""
 
 import argparse
 import asyncio

src/edge_tts/version.py

@@ -1,4 +1,4 @@
-"""Edge TTS version information."""
+"""Version information for the edge_tts package."""
 
 __version__ = "6.1.19"
 __version_info__ = tuple(int(num) for num in __version__.split("."))

src/edge_tts/voices.py

@@ -1,6 +1,5 @@
-"""
-list_voices package for edge_tts.
-"""
+"""This module contains functions to list all available voices and a class to find the
+correct voice based on their attributes."""
 
 import json
 import ssl