refactor: drop comments that narrate instead of constrain

Keep a comment only when it says something the code cannot: a
non-obvious why, an external constraint, or an invariant a future edit
would break. Comments that narrate a test, restate an assertion, or
argue the code is correct are deleted; the tests are the explanation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HMKbYgbsoFdKiiaxXB6jh2

Author: claude

src/Http/SerializingClient.php

@@ -102,8 +102,6 @@ private static function serialize_options(array $options): array
             );
 
             if ($serialized === "") {
-                // Nothing serialized must mean no query at all, not a bare
-                // trailing `?`.
                 unset($options["query"]);
             } else {
                 $options["query"] = $serialized;

src/NullValue.php

@@ -32,9 +32,6 @@ enum NullValue
 {
     /**
      * Sentinel for a param explicitly set to null.
-     *
-     * An enum case cannot be instantiated or subclassed, so this is the only
-     * value of this type, and `$value instanceof NullValue` detects it.
      */
     case NULL;
 

src/StrictUrlSearchParamsSerializer.php

@@ -45,8 +45,6 @@ public static function update(
         UrlSearchParamsSerializer::update($search_params, $params);
 
         if (count($search_params) > 0) {
-            // Replaced rather than repeated, and appended after the sort so
-            // it always sits last.
             $search_params->delete("_strict");
             $search_params->append("_strict", "true");
         }

src/UnserializableParamError.php

@@ -3,10 +3,8 @@
 namespace Seam;
 
 /**
- * Error thrown when a request param could not be serialized.
- *
- * It is thrown before any request is sent, so it never means the API
- * rejected the param, only that this SDK could not represent it.
+ * Error thrown when a request param could not be serialized, before any
+ * request is sent.
  */
 class UnserializableParamError extends \InvalidArgumentException
 {

src/UrlSearchParamsSerializer.php

@@ -286,9 +286,8 @@ private static function format_number(string $name, float $value): string
     private static function shortest_digits(float $value): array
     {
         // At -1, PHP's float-to-string conversion produces the shortest
-        // string that round-trips, which is exactly the digit string the
-        // algorithm needs. The ini setting is restored because it also
-        // affects the caller's own serialize() and json_encode() calls.
+        // string that round-trips. Restored because the setting also affects
+        // the caller's own serialize() and json_encode() calls.
         $precision = ini_set("serialize_precision", "-1");
 
         try {
@@ -306,8 +305,6 @@ private static function shortest_digits(float $value): array
                 $matches,
             ) !== 1
         ) {
-            // Unreachable for a finite positive float, but a silent
-            // mis-parse would serialize a wrong number.
             throw new \RuntimeException(
                 "Could not parse the PHP float representation: {$repr}",
             );

tests/NullValueTest.php

@@ -67,7 +67,6 @@ public function testReplaceCopiesStdClassObjectsWithoutMutatingThem(): void
         $this->assertNotSame($payload, $replaced);
         $this->assertNull($replaced->name);
         $this->assertNull($replaced->nested->code);
-        // The caller's payload is untouched.
         $this->assertSame(NullValue::NULL, $payload->name);
         $this->assertSame(NullValue::NULL, $payload->nested->code);
     }

tests/SearchParamsTest.php

@@ -10,10 +10,6 @@
 use Seam\UnserializableParamError;
 use Tests\Support\RecordingClient;
 
-/**
- * Asserts on the raw query string the client puts on the wire, not on a
- * re-parsed version of it, which would hide encoding differences.
- */
 final class SearchParamsTest extends TestCase
 {
     private const DEVICES = ["devices" => []];
@@ -58,12 +54,6 @@ public function testClientSerializesSearchParams(): void
         );
     }
 
-    /**
-     * The serializer and Guzzle disagree on exactly two characters: Guzzle
-     * escapes `*` and leaves `~` alone, so a query Guzzle encodes is not the
-     * one the serializer produced. Handing Guzzle the raw string keeps ours,
-     * including through resolution against the client's base URL.
-     */
     public function testClientDoesNotReencodeTheSerializedSearchParams(): void
     {
         $recording = RecordingClient::repeating(
@@ -90,8 +80,6 @@ public function testClientSerializesEmptyArraysToAnEmptyValue(): void
             "query" => ["device_ids" => []],
         ]);
 
-        // Not omitted and not a bare name: the parser reads `device_ids=`
-        // as the empty array, while no param at all means unfiltered.
         $this->assertSame(
             "device_ids=&_strict=true",
             $recording->request()->getUri()->getQuery(),
@@ -175,10 +163,6 @@ public function testClientSerializesSearchParamsOfEveryVerb(): void
         }
     }
 
-    /**
-     * A query already given as a string is a representation the caller
-     * chose, so it is forwarded to Guzzle untouched.
-     */
     public function testClientPassesSearchParamsItDidNotSerializeToGuzzle(): void
     {
         $recording = RecordingClient::repeating(
@@ -211,7 +195,6 @@ public function testClientRejectsASearchParamItCannotSerialize(): void
             $this->assertSame("search", $error->getName());
         }
 
-        // The error is raised before any request goes out.
         $this->assertSame(0, $recording->request_count());
     }
 

tests/StrictUrlSearchParamsSerializerTest.php

@@ -21,8 +21,6 @@ public function testAddsStrictToNonEmptyQueryStrings(): void
 
     public function testAppendsStrictAfterTheSortedParams(): void
     {
-        // `_strict` would sort between the uppercase and lowercase names;
-        // it is appended after the sort so it always sits last.
         $this->assertSame(
             "B=2&a=1&_strict=true",
             StrictUrlSearchParamsSerializer::serialize(["a" => 1, "B" => 2]),

tests/UrlSearchParamsSerializerTest.php

@@ -36,7 +36,6 @@ public function testSerializesString(): void
 
     public function testRemovesTheEmptyString(): void
     {
-        // Serializing the empty string would conflict with NullValue::NULL.
         $this->assertSame("", self::serialize(["foo" => ""]));
         $this->assertSame(
             "foo=d",
@@ -75,8 +74,6 @@ public function testSerializesFloat(): void
 
     public function testSerializesFloatUsingTheEcmascriptNumberFormat(): void
     {
-        // A float is serialized exactly as JavaScript would serialize the
-        // number, which is not always the same as the PHP string cast.
         $this->assertSame("foo=1", self::serialize(["foo" => 1.0]));
         $this->assertSame("foo=0", self::serialize(["foo" => -0.0]));
         $this->assertSame("foo=100", self::serialize(["foo" => 100.0]));
@@ -200,7 +197,6 @@ public function testSerializesMutableDatetime(): void
             "now=2025-02-24T18%3A44%3A39.000Z",
             self::serialize(["now" => $now]),
         );
-        // Converting to UTC must not mutate the caller's value.
         $this->assertSame("2025-02-24T18:44:39+00:00", $now->format("c"));
     }
 
@@ -342,8 +338,6 @@ public function testSortsParamsByName(): void
 
     public function testSortsParamsByUtf16CodeUnit(): void
     {
-        // UTF-8 byte order and code-point order would both put U+FFFF first;
-        // only UTF-16 code-unit order puts the astral emoji first.
         $this->assertSame(
             "%F0%9F%98%80=2&%EF%BF%BF=1",
             self::serialize(["\u{FFFF}" => 1, "\u{1F600}" => 2]),
@@ -407,8 +401,6 @@ public function testCannotSerializeNestedKeysContainingADot(): void
 
     public function testCannotSerializeNonStringKeys(): void
     {
-        // PHP casts a numeric-string key to an integer, so both spellings
-        // arrive here as the same unserializable key.
         $this->expectException(UnserializableParamError::class);
 
         self::serialize(["foo" => [1 => "a", "b" => "c"]]);