Clarified comments and docstrings.

tests/test_commands.py

@@ -60,15 +60,15 @@ class TestEscapeMarkdown:
         ],
     )
     def test_escapes_special_chars(self, input_text: str, expected: str) -> None:
-        """Escape the given Markdown special character."""
+        """Escape Markdown special characters in input text."""
         assert _escape_markdown(input_text) == expected
 
 
 class TestSanitizeForMarkdown:
-    """Markdown sanitization combining newline removal and escaping."""
+    """Markdown sanitization combining whitespace normalization and escaping."""
 
     def test_removes_newlines_and_escapes(self) -> None:
-        """Remove newlines and escape Markdown special characters."""
+        """Normalize newlines and escape Markdown special characters."""
         result = _sanitize_for_markdown("*bold*\nnew line")
         assert result == "\\*bold\\* new line"
 
@@ -171,7 +171,7 @@ class TestSubscribeCommand:
     async def test_subscribe_existing_stream_new_room(
         self, maubot_test_bot: TestBot
     ) -> None:
-        """Skip instance validation when subscribing from a new room."""
+        """Skip validation when the domain already has subscriptions."""
         status_url = f"https://stream.logal.dev{_OWNCAST_STATUS_PATH}"
         with aioresponses() as mocked:
             mocked.get(
@@ -180,9 +180,9 @@ class TestSubscribeCommand:
             )
             await maubot_test_bot.send("!subscribe stream.logal.dev")
 
-        # Subscribe from a different room; skips validation and should not
-        # query the remote instance. An empty aioresponses context will raise
-        # ConnectionError if any HTTP request is attempted.
+        # Subscribe from a different room. The existing subscribed domain skips
+        # validation, so an empty aioresponses context will raise ConnectionError
+        # if any HTTP request is attempted.
         with aioresponses():
             await maubot_test_bot.send(
                 "!subscribe stream.logal.dev", room_id="!otherroom:example.com"
@@ -408,8 +408,8 @@ class TestSubscriptionsCommand:
     async def test_shows_multiple_subscriptions(
         self, maubot_test_bot: TestBot, maubot_plugin: OwncastSentry
     ) -> None:
-        """List subscriptions alphabetically with mixed statuses."""
-        # Subscribe in reverse alphabetical order to verify sorted output
+        """List subscriptions ordered by domain with mixed statuses."""
+        # Subscribe in reverse domain order to verify domain-sorted output
         with aioresponses() as mocked:
             mocked.get(
                 f"https://beta.com{_OWNCAST_STATUS_PATH}",
@@ -543,8 +543,8 @@ class TestLiveCommand:
     async def test_shows_multiple_live_streams(
         self, maubot_test_bot: TestBot, maubot_plugin: OwncastSentry
     ) -> None:
-        """List live streams alphabetically with different durations."""
-        # Subscribe in reverse alphabetical order to verify sorted output
+        """List live streams ordered by domain with different durations."""
+        # Subscribe in reverse domain order to verify domain-sorted output
         with aioresponses() as mocked:
             mocked.get(
                 f"https://beta.com{_OWNCAST_STATUS_PATH}",

tests/test_metrics.py

@@ -142,7 +142,7 @@ class TestSetSubscriptionCount:
 
 
 class TestSetCheckFailures:
-    """Check failure counter gauge per domain."""
+    """Consecutive check failure gauge per domain."""
 
     def test_sets_count(self) -> None:
         """Set the failure count for a domain."""
@@ -196,7 +196,7 @@ class TestResponseTimer:
         assert len(matches) == 1
 
     def test_does_not_record_on_exception(self) -> None:
-        """Do not record when the block raises an exception."""
+        """Do not record when the block raises before success() is called."""
         service = MetricsService()
         with (
             pytest.raises(ValueError, match="boom"),

tests/test_notification_service.py

@@ -272,7 +272,7 @@ class TestFormatMessage:
 
 
 class TestNotifyStreamLive:
-    """End-to-end notification sending."""
+    """Live notification sending behavior."""
 
     async def test_sends_to_all_subscribed_rooms(
         self,
@@ -393,7 +393,7 @@ class TestNotifyStreamLive:
         stream_repo: StreamRepository,
         subscription_repo: SubscriptionRepository,
     ) -> None:
-        """Send to remaining rooms after a delivery failure."""
+        """Deliver to other subscribed rooms when one room delivery fails."""
         client = _StubMatrixClient()
         client.should_fail_for_rooms.add("!bad:matrix.org")
         service = _make_service(client=client, subscription_repo=subscription_repo)

tests/test_owncast_client.py

@@ -405,7 +405,7 @@ class TestValidateInstance:
 
 
 class TestResponseTimeMetrics:
-    """Response time histogram recording."""
+    """Response time gauge recording."""
 
     async def test_records_on_success(self) -> None:
         """Record response time on a successful request."""

tests/test_subscription_manager.py

@@ -173,7 +173,7 @@ class TestManagerSubscribe:
         owncast_client: _StubOwncastClient,
         subscription_repo: SubscriptionRepository,
     ) -> None:
-        """Known domains skip remote validation for additional room subscriptions."""
+        """Domains with existing subscriptions skip remote validation."""
         await manager.subscribe("!room1:example.com", "stream.example")
         owncast_client.valid = False
 

tests/test_types.py

@@ -50,7 +50,7 @@ class TestTruncate:
         ],
     )
     def test_truncates(self, text: str, max_length: int, expected: str) -> None:
-        """Truncate text that exceeds the maximum length."""
+        """Return text unchanged within the limit and truncate over-limit text."""
         assert _truncate(text, max_length) == expected
 
 
@@ -117,7 +117,7 @@ class TestStreamStateFromApiResponse:
     """StreamState construction from an API response dictionary."""
 
     def test_typical_response(self) -> None:
-        """Populate all fields from a complete API response."""
+        """Populate API-derived fields from a complete stream state response."""
         response = {
             "streamTitle": "My Stream",
             "lastConnectTime": "2026-01-01T00:00:00Z",