refactor: updates docblock with new standards

Author: JasonTheAdams

src/Common/AbstractEnum.php

@@ -55,11 +55,11 @@ abstract class AbstractEnum
     private static array $instances = [];
 
     /**
-     * Constructor is private to ensure instances are created through static methods
+     * Constructor is private to ensure instances are created through static methods.
      *
      * @since n.e.x.t
-     * @param string $value The enum value
-     * @param string $name The constant name
+     * @param string $value The enum value.
+     * @param string $name The constant name.
      */
     final private function __construct(string $value, string $name)
     {
@@ -68,12 +68,12 @@ final private function __construct(string $value, string $name)
     }
 
     /**
-     * Magic getter to provide read-only access to properties
+     * Provides read-only access to properties.
      *
      * @since n.e.x.t
-     * @param string $property The property name
-     * @return mixed
-     * @throws BadMethodCallException If property doesn't exist
+     * @param string $property The property name.
+     * @return mixed The property value.
+     * @throws BadMethodCallException If property doesn't exist.
      */
     final public function __get(string $property)
     {
@@ -87,12 +87,12 @@ final public function __get(string $property)
     }
 
     /**
-     * Magic setter to prevent property modification
+     * Prevents property modification.
      *
      * @since n.e.x.t
-     * @param string $property The property name
-     * @param mixed $value The value to set
-     * @throws BadMethodCallException Always, as enum properties are read-only
+     * @param string $property The property name.
+     * @param mixed $value The value to set.
+     * @throws BadMethodCallException Always, as enum properties are read-only.
      */
     final public function __set(string $property, $value): void
     {
@@ -102,12 +102,12 @@ final public function __set(string $property, $value): void
     }
 
     /**
-     * Create an enum instance from a value, throws exception if invalid
+     * Creates an enum instance from a value, throws exception if invalid.
      *
      * @since n.e.x.t
-     * @param string $value The enum value
-     * @return static
-     * @throws InvalidArgumentException If the value is not valid
+     * @param string $value The enum value.
+     * @return static The enum instance.
+     * @throws InvalidArgumentException If the value is not valid.
      */
     final public static function from(string $value): self
     {
@@ -121,11 +121,11 @@ final public static function from(string $value): self
     }
 
     /**
-     * Try to create an enum instance from a value, returns null if invalid
+     * Tries to create an enum instance from a value, returns null if invalid.
      *
      * @since n.e.x.t
-     * @param string $value The enum value
-     * @return static|null
+     * @param string $value The enum value.
+     * @return static|null The enum instance or null.
      */
     final public static function tryFrom(string $value): ?self
     {
@@ -139,10 +139,10 @@ final public static function tryFrom(string $value): ?self
     }
 
     /**
-     * Get all enum cases
+     * Gets all enum cases.
      *
      * @since n.e.x.t
-     * @return static[]
+     * @return static[] Array of all enum instances.
      */
     final public static function cases(): array
     {
@@ -155,11 +155,11 @@ final public static function cases(): array
     }
 
     /**
-     * Check if this enum has the same value as the given value
+     * Checks if this enum has the same value as the given value.
      *
      * @since n.e.x.t
-     * @param string|self $other The value or enum to compare
-     * @return bool
+     * @param string|self $other The value or enum to compare.
+     * @return bool True if values are equal.
      */
     final public function equals($other): bool
     {
@@ -171,47 +171,47 @@ final public function equals($other): bool
     }
 
     /**
-     * Check if this enum is the same instance type and value as another enum
+     * Checks if this enum is the same instance type and value as another enum.
      *
      * @since n.e.x.t
-     * @param self $other The other enum to compare
-     * @return bool
+     * @param self $other The other enum to compare.
+     * @return bool True if enums are identical.
      */
     final public function is(self $other): bool
     {
         return $this === $other; // Since we're using singletons, we can use identity comparison
     }
 
     /**
-     * Get all valid values for this enum
+     * Gets all valid values for this enum.
      *
      * @since n.e.x.t
-     * @return array<string, string>
+     * @return array<string, string> Map of constant names to values.
      */
     final public static function getValues(): array
     {
         return self::getConstants();
     }
 
     /**
-     * Check if a value is valid for this enum
+     * Checks if a value is valid for this enum.
      *
      * @since n.e.x.t
-     * @param string $value The value to check
-     * @return bool
+     * @param string $value The value to check.
+     * @return bool True if value is valid.
      */
     final public static function isValidValue(string $value): bool
     {
         return in_array($value, self::getValues(), true);
     }
 
     /**
-     * Get or create a singleton instance for the given value and name
+     * Gets or creates a singleton instance for the given value and name.
      *
      * @since n.e.x.t
-     * @param string $value The enum value
-     * @param string $name The constant name
-     * @return static
+     * @param string $value The enum value.
+     * @param string $name The constant name.
+     * @return static The enum instance.
      */
     private static function getInstance(string $value, string $name): self
     {
@@ -231,11 +231,11 @@ private static function getInstance(string $value, string $name): self
     }
 
     /**
-     * Get all constants for this enum class
+     * Gets all constants for this enum class.
      *
      * @since n.e.x.t
-     * @return array<string, string>
-     * @throws \RuntimeException If invalid constant found
+     * @return array<string, string> Map of constant names to values.
+     * @throws \RuntimeException If invalid constant found.
      */
     final protected static function getConstants(): array
     {
@@ -282,13 +282,13 @@ final protected static function getConstants(): array
     }
 
     /**
-     * Handle dynamic method calls for enum checking
+     * Handles dynamic method calls for enum checking.
      *
      * @since n.e.x.t
-     * @param string $name The method name
-     * @param array<mixed> $arguments The method arguments
-     * @return bool
-     * @throws BadMethodCallException If the method doesn't exist
+     * @param string $name The method name.
+     * @param array<mixed> $arguments The method arguments.
+     * @return bool True if the enum value matches.
+     * @throws BadMethodCallException If the method doesn't exist.
      */
     final public function __call(string $name, array $arguments): bool
     {
@@ -308,13 +308,13 @@ final public function __call(string $name, array $arguments): bool
     }
 
     /**
-     * Handle static method calls for enum creation
+     * Handles static method calls for enum creation.
      *
      * @since n.e.x.t
-     * @param string $name The method name
-     * @param array<mixed> $arguments The method arguments
-     * @return static
-     * @throws BadMethodCallException If the method doesn't exist
+     * @param string $name The method name.
+     * @param array<mixed> $arguments The method arguments.
+     * @return static The enum instance.
+     * @throws BadMethodCallException If the method doesn't exist.
      */
     final public static function __callStatic(string $name, array $arguments): self
     {
@@ -331,11 +331,11 @@ final public static function __callStatic(string $name, array $arguments): self
     }
 
     /**
-     * Convert camelCase to CONSTANT_CASE
+     * Converts camelCase to CONSTANT_CASE.
      *
      * @since n.e.x.t
-     * @param string $camelCase The camelCase string
-     * @return string The CONSTANT_CASE version
+     * @param string $camelCase The camelCase string.
+     * @return string The CONSTANT_CASE version.
      */
     private static function camelCaseToConstant(string $camelCase): string
     {
@@ -347,10 +347,10 @@ private static function camelCaseToConstant(string $camelCase): string
     }
 
     /**
-     * String representation of the enum
+     * Returns string representation of the enum.
      *
      * @since n.e.x.t
-     * @return string
+     * @return string The enum value.
      */
     final public function __toString(): string
     {

src/Messages/Enums/MessagePartTypeEnum.php

@@ -7,44 +7,44 @@
 use WordPress\AiClient\Common\AbstractEnum;
 
 /**
- * Enum for message part types
+ * Enum for message part types.
  *
  * @since n.e.x.t
- * @method static self text() Create an instance for TEXT type
- * @method static self inlineFile() Create an instance for INLINE_FILE type
- * @method static self remoteFile() Create an instance for REMOTE_FILE type
- * @method static self functionCall() Create an instance for FUNCTION_CALL type
- * @method static self functionResponse() Create an instance for FUNCTION_RESPONSE type
- * @method bool isText() Check if the type is TEXT
- * @method bool isInlineFile() Check if the type is INLINE_FILE
- * @method bool isRemoteFile() Check if the type is REMOTE_FILE
- * @method bool isFunctionCall() Check if the type is FUNCTION_CALL
- * @method bool isFunctionResponse() Check if the type is FUNCTION_RESPONSE
+ * @method static self text() Creates an instance for TEXT type.
+ * @method static self inlineFile() Creates an instance for INLINE_FILE type.
+ * @method static self remoteFile() Creates an instance for REMOTE_FILE type.
+ * @method static self functionCall() Creates an instance for FUNCTION_CALL type.
+ * @method static self functionResponse() Creates an instance for FUNCTION_RESPONSE type.
+ * @method bool isText() Checks if the type is TEXT.
+ * @method bool isInlineFile() Checks if the type is INLINE_FILE.
+ * @method bool isRemoteFile() Checks if the type is REMOTE_FILE.
+ * @method bool isFunctionCall() Checks if the type is FUNCTION_CALL.
+ * @method bool isFunctionResponse() Checks if the type is FUNCTION_RESPONSE.
  */
 class MessagePartTypeEnum extends AbstractEnum
 {
     /**
-     * Text content
+     * Text content.
      */
     public const TEXT = 'text';
 
     /**
-     * Inline file content (base64 encoded)
+     * Inline file content (base64 encoded).
      */
     public const INLINE_FILE = 'inline_file';
 
     /**
-     * Remote file reference (URL)
+     * Remote file reference (URL).
      */
     public const REMOTE_FILE = 'remote_file';
 
     /**
-     * Function call request
+     * Function call request.
      */
     public const FUNCTION_CALL = 'function_call';
 
     /**
-     * Function response
+     * Function response.
      */
     public const FUNCTION_RESPONSE = 'function_response';
 }

src/Messages/Enums/MessageRoleEnum.php

@@ -7,30 +7,30 @@
 use WordPress\AiClient\Common\AbstractEnum;
 
 /**
- * Enum for message roles in AI conversations
+ * Enum for message roles in AI conversations.
  *
  * @since n.e.x.t
- * @method static self user() Create an instance for USER role
- * @method static self model() Create an instance for MODEL role
- * @method static self system() Create an instance for SYSTEM role
- * @method bool isUser() Check if the role is USER
- * @method bool isModel() Check if the role is MODEL
- * @method bool isSystem() Check if the role is SYSTEM
+ * @method static self user() Creates an instance for USER role.
+ * @method static self model() Creates an instance for MODEL role.
+ * @method static self system() Creates an instance for SYSTEM role.
+ * @method bool isUser() Checks if the role is USER.
+ * @method bool isModel() Checks if the role is MODEL.
+ * @method bool isSystem() Checks if the role is SYSTEM.
  */
 class MessageRoleEnum extends AbstractEnum
 {
     /**
-     * User role - messages from the user
+     * User role - messages from the user.
      */
     public const USER = 'user';
 
     /**
-     * Model role - messages from the AI model
+     * Model role - messages from the AI model.
      */
     public const MODEL = 'model';
 
     /**
-     * System role - system instructions
+     * System role - system instructions.
      */
     public const SYSTEM = 'system';
 }