Enhance the String documentation

Author: georgedeploy

src/Integer/Alias/WeekDay.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Integer\Alias;
+
+use PhpTypedValues\Integer\IntegerWeekDay;
+
+/**
+ * @psalm-immutable
+ */
+readonly class WeekDay extends IntegerWeekDay
+{
+}

src/String/Alias/CountryCode.php

@@ -7,6 +7,15 @@
 use PhpTypedValues\String\StringCountryCode;
 
 /**
+ * Alias for ISO 3166-1 alpha‑2 country code string.
+ *
+ * Provides the same behavior as StringCountryCode while exposing a concise
+ * name suitable for APIs that prefer "CountryCode".
+ *
+ * Example
+ *  - $c = CountryCode::fromString('US');
+ *    $c->toString(); // "US"
+ *
  * @psalm-immutable
  */
 readonly class CountryCode extends StringCountryCode

src/String/Alias/Email.php

@@ -7,6 +7,15 @@
 use PhpTypedValues\String\StringEmail;
 
 /**
+ * Alias for email address string.
+ *
+ * Provides the same behavior as StringEmail while exposing a concise
+ * name suitable for APIs that prefer "Email".
+ *
+ * Example
+ *  - $e = Email::fromString('user@example.com');
+ *    (string) $e; // "user@example.com"
+ *
  * @psalm-immutable
  */
 readonly class Email extends StringEmail

src/String/Alias/Json.php

@@ -7,6 +7,15 @@
 use PhpTypedValues\String\StringJson;
 
 /**
+ * Alias for JSON text string.
+ *
+ * Provides the same behavior as StringJson while exposing a concise
+ * name suitable for APIs that prefer "Json".
+ *
+ * Example
+ *  - $j = Json::fromString('{"a":1}');
+ *    $j->toArray(); // ['a' => 1]
+ *
  * @psalm-immutable
  */
 readonly class Json extends StringJson

src/String/Alias/MariaDb/Decimal.php

@@ -7,6 +7,15 @@
 use PhpTypedValues\String\MariaDb\StringDecimal;
 
 /**
+ * Alias for MariaDB DECIMAL value represented as a string.
+ *
+ * Provides the same behavior as StringDecimal while exposing a concise
+ * name suitable for APIs that prefer "Decimal" in the MariaDb namespace.
+ *
+ * Example
+ *  - $d = Decimal::fromString('3.14');
+ *    $d->toFloat(); // 3.14 (only if exact)
+ *
  * @psalm-immutable
  */
 readonly class Decimal extends StringDecimal

src/String/Alias/MariaDb/Text.php

@@ -7,6 +7,15 @@
 use PhpTypedValues\String\MariaDb\StringText;
 
 /**
+ * Alias for MariaDB TEXT string (up to 65,535 characters).
+ *
+ * Provides the same behavior as StringText while exposing a concise
+ * name suitable for APIs that prefer "Text" in the MariaDb namespace.
+ *
+ * Example
+ *  - $t = Text::fromString('lorem ipsum');
+ *    $t->toString(); // 'lorem ipsum'
+ *
  * @psalm-immutable
  */
 readonly class Text extends StringText

src/String/Alias/MariaDb/VarChar255.php

@@ -7,6 +7,15 @@
 use PhpTypedValues\String\MariaDb\StringVarChar255;
 
 /**
+ * Alias for MariaDB VARCHAR(255) string.
+ *
+ * Provides the same behavior as StringVarChar255 while exposing a concise
+ * name suitable for APIs that prefer "VarChar255" in the MariaDb namespace.
+ *
+ * Example
+ *  - $v = VarChar255::fromString('Hello world');
+ *    $v->toString(); // 'Hello world'
+ *
  * @psalm-immutable
  */
 readonly class VarChar255 extends StringVarChar255

src/String/Alias/NonBlank.php

@@ -7,9 +7,14 @@
 use PhpTypedValues\String\StringNonBlank;
 
 /**
- * Alias of Non-blank string value.
+ * Alias for non‑blank string typed value.
  *
- * Example "hello", blank string like " " will fail.
+ * Provides the same behavior as StringNonBlank while exposing a concise
+ * name suitable for APIs that prefer "NonBlank".
+ *
+ * Example
+ *  - $v = NonBlank::fromString(' hello ');
+ *    $v->toString(); // ' hello '
  *
  * @psalm-immutable
  */

src/String/Alias/NonEmpty.php

@@ -7,9 +7,14 @@
 use PhpTypedValues\String\StringNonEmpty;
 
 /**
- * Alias of Non-empty string value.
+ * Alias for non-empty string typed value.
  *
- * Example "hello"
+ * Provides the same behavior as StringNonEmpty while exposing a concise
+ * name suitable for APIs that prefer "NonEmpty".
+ *
+ * Example
+ *  - $v = NonEmpty::fromString('hello');
+ *    $v->value(); // 'hello'
  *
  * @psalm-immutable
  */

src/String/Alias/Str.php

@@ -7,6 +7,15 @@
 use PhpTypedValues\String\StringStandard;
 
 /**
+ * Alias for the generic string typed value.
+ *
+ * Provides the same behavior as StringStandard while exposing a concise
+ * name suitable for APIs that prefer "Str".
+ *
+ * Example
+ *  - $s = Str::fromString('hello');
+ *    $s->toString(); // "hello"
+ *
  * @psalm-immutable
  */
 readonly class Str extends StringStandard