docs: Add docstrings and improve code documentation

examples/async/example.py

@@ -3,7 +3,10 @@
 from gpytranslate import Translator
 
 
+"""Example showing basic translation and language detection."""
+
 async def main() -> None:
+    """Demonstrate translation from Italian to English and language detection."""
     t = Translator()
     # Note: you can use proxies by passing proxies parameter to Translator
     translation = await t.translate("Ciao come stai? Io bene ahah.", targetlang="en")

examples/async/https_proxy.py

@@ -3,7 +3,10 @@
 from gpytranslate import Translator
 
 
+"""Example showing how to use HTTPS proxy with the translator."""
+
 async def main() -> None:
+    """Demonstrate translation using an HTTPS proxy."""
     t = Translator(proxies={"https://": "https://{proxy_ip_here}"})
     # Check out https://www.python-httpx.org/compatibility/#proxy-keys
     translation = await t.translate("Ciao Mondo!", targetlang="en")

examples/async/socks5_proxy.py

@@ -3,7 +3,10 @@
 from gpytranslate import Translator
 
 
+"""Example showing how to use SOCKS5 proxy with the translator."""
+
 async def main() -> None:
+    """Demonstrate translation using a SOCKS5 proxy."""
     t = Translator(proxies={"socks5": "socks5://user:password@127.0.0.1:1080"})
     # Check out https://pypi.org/project/httpx-socks/
     translation = await t.translate("Ciao Mondo!", targetlang="en")

examples/async/tts.py

@@ -5,7 +5,10 @@
 from gpytranslate import Translator
 
 
+"""Example showing how to use text-to-speech functionality."""
+
 async def main() -> None:
+    """Demonstrate text-to-speech generation."""
     translator = Translator()
 
     async with aiofiles.open("test.mp3", "wb") as file:

tests/async/test_detect.py

@@ -3,8 +3,11 @@
 from gpytranslate import Translator
 
 
+"""Tests for the async language detection functionality."""
+
 @pytest.mark.asyncio
 async def test_detect() -> None:
+    """Test that language detection works correctly for Italian text."""
     translator = Translator()
     language = await translator.detect(text="Ciao Mondo.")
     assert isinstance(language, str)

tests/async/test_gather.py

@@ -5,8 +5,11 @@
 from gpytranslate import Translator
 
 
+"""Tests for concurrent translation using asyncio.gather."""
+
 @pytest.mark.asyncio
 async def test_gather() -> None:
+    """Test that multiple translations can be processed concurrently."""
     translator = Translator()
     tasks = [
         translator.translate("Hello world!", targetlang="it"),

tests/sync/test_sync_detect.py

@@ -1,7 +1,10 @@
 from gpytranslate import SyncTranslator
 
 
+"""Tests for the synchronous language detection functionality."""
+
 def test_sync_detect() -> None:
+    """Test that language detection works correctly for Italian text."""
     translator = SyncTranslator()
     language = translator.detect(text="Ciao Mondo.")
     assert isinstance(language, str)

tests/sync/test_sync_tts.py

@@ -4,7 +4,10 @@
 from gpytranslate import SyncTranslator
 
 
+"""Tests for the synchronous text-to-speech functionality."""
+
 def test_sync_tts() -> None:
+    """Test that TTS can generate an audio file."""
     translator = SyncTranslator()
     filename = "test.mp3"