chore: improves property definition docs

Author: JasonTheAdams

src/Models/ModelPropertyDefinition.php

@@ -6,51 +6,80 @@
 
 use Closure;
 
+/**
+ * Defines a model property with its type, default value, and validation rules.
+ *
+ * @since 2.0.0
+ */
 class ModelPropertyDefinition {
 	/**
 	 * The default value of the property.
 	 *
+	 * @since 2.0.0
+	 *
 	 * @var mixed|Closure
 	 */
 	private $default;
 
 	/**
 	 * The method to cast the property value.
 	 *
+	 * @since 2.0.0
+	 *
 	 * @var Closure|null A closure that accepts the value and property instance as parameters and returns the cast value.
 	 */
 	private Closure $castMethod;
 
 	/**
 	 * Whether the definition is locked. Once locked, the definition cannot be changed.
+	 *
+	 * @since 2.0.0
+	 *
+	 * @var bool
 	 */
 	private bool $locked = false;
 
 	/**
 	 * Whether the property is nullable.
+	 *
+	 * @since 2.0.0
+	 *
+	 * @var bool
 	 */
 	private bool $nullable = false;
 
 	/**
 	 * Whether the property is required.
+	 *
+	 * @since 2.0.0
+	 *
+	 * @var bool
 	 */
 	private bool $required = false;
 
 	/**
 	 * Whether the property is required on save.
+	 *
+	 * @since 2.0.0
+	 *
+	 * @var bool
 	 */
 	private bool $requiredOnSave = false;
 
 	/**
 	 * The type of the property.
 	 *
+	 * @since 2.0.0
+	 *
 	 * @var string[]
 	 */
 	private array $type = ['string'];
 
 	/**
 	 * Set the default value of the property.
 	 *
+	 * @since 2.0.0
+	 *
 	 * @param mixed|Closure $default The default value of the property.
 	 */
 	public function default( $default ): self {
@@ -63,6 +92,8 @@ public function default( $default ): self {
 
 	/**
 	 * Whether the property can cast the value.
+	 *
+	 * @since 2.0.0
 	 */
 	public function canCast(): bool {
 		return isset( $this->castMethod );
@@ -71,7 +102,13 @@ public function canCast(): bool {
 	/**
 	 * Cast the property value.
 	 *
+	 * @since 2.0.0
+	 *
 	 * @param mixed $value The value to cast.
+	 *
+	 * @return mixed
+	 *
+	 * @throws \RuntimeException When no cast method is set.
 	 */
 	public function cast( $value ) {
 		$this->checkLock();
@@ -87,6 +124,8 @@ public function cast( $value ) {
 
 	/**
 	 * Provides a method to cast the property value.
+	 *
+	 * @since 2.0.0
 	 */
 	public function castWith( callable $castMethod ): self {
 		$this->checkLock();
@@ -98,6 +137,10 @@ public function castWith( callable $castMethod ): self {
 
 	/**
 	 * Check if the property is locked and throw an exception if it is.
+	 *
+	 * @since 2.0.0
+	 *
+	 * @throws \RuntimeException When the property is locked.
 	 */
 	private function checkLock(): void {
 		if ( $this->locked ) {
@@ -107,7 +150,12 @@ private function checkLock(): void {
 
 	/**
 	 * Create a property definition from a shorthand string or array.
-	 * @param string|array{0:string,1:bool} $definition
+	 *
+	 * @since 2.0.0
+	 *
+	 * @param string|array{0:string,1:mixed} $definition The shorthand definition.
+	 *
+	 * @throws \InvalidArgumentException When the definition is invalid.
 	 */
 	public static function fromShorthand( $definition ): self {
 		$property = new self();
@@ -130,6 +178,8 @@ public static function fromShorthand( $definition ): self {
 	/**
 	 * Get the default value of the property.
 	 *
+	 * @since 2.0.0
+	 *
 	 * @return mixed
 	 */
 	public function getDefault() {
@@ -145,6 +195,8 @@ public function getDefault() {
 	/**
 	 * Get the type of the property.
 	 *
+	 * @since 2.0.0
+	 *
 	 * @return string[]
 	 */
 	public function getType(): array {
@@ -153,6 +205,8 @@ public function getType(): array {
 
 	/**
 	 * Whether the property has a default value.
+	 *
+	 * @since 2.0.0
 	 */
 	public function hasDefault(): bool {
 		return isset( $this->default );
@@ -161,35 +215,45 @@ public function hasDefault(): bool {
 	/**
 	 * Whether the property is locked.
 	 *
-	 * @return bool
+	 * @since 2.0.0
 	 */
 	public function isLocked(): bool {
 		return $this->locked;
 	}
 
 	/**
 	 * Whether the property is nullable.
+	 *
+	 * @since 2.0.0
 	 */
 	public function isNullable(): bool {
 		return $this->nullable;
 	}
 
 	/**
 	 * Whether the property is required.
+	 *
+	 * @since 2.0.0
 	 */
 	public function isRequired(): bool {
 		return $this->required;
 	}
 
 	/**
 	 * Whether the property is required on save.
+	 *
+	 * @since 2.0.0
 	 */
 	public function isRequiredOnSave(): bool {
 		return $this->requiredOnSave;
 	}
 
 	/**
 	 * Whether the property is valid for the given value.
+	 *
+	 * @since 2.0.0
+	 *
+	 * @param mixed $value The value to validate.
 	 */
 	public function isValidValue( $value ): bool {
 		$valueType = gettype( $value );
@@ -222,13 +286,20 @@ public function isValidValue( $value ): bool {
 	/**
 	 * Locks the property so it cannot be changed.
 	 * Note that once locked the property cannot be unlocked.
+	 *
+	 * @since 2.0.0
 	 */
 	public function lock(): self {
 		$this->locked = true;
 
 		return $this;
 	}
 
+	/**
+	 * Makes the property nullable.
+	 *
+	 * @since 2.0.0
+	 */
 	public function nullable(): self {
 		$this->checkLock();
 
@@ -239,6 +310,8 @@ public function nullable(): self {
 
 	/**
 	 * Makes the property required.
+	 *
+	 * @since 2.0.0
 	 */
 	public function required(): self {
 		$this->checkLock();
@@ -250,6 +323,8 @@ public function required(): self {
 
 	/**
 	 * Makes the property required on save.
+	 *
+	 * @since 2.0.0
 	 */
 	public function requiredOnSave(): self {
 		$this->checkLock();
@@ -261,6 +336,8 @@ public function requiredOnSave(): self {
 
 	/**
 	 * Whether the property supports the given type.
+	 *
+	 * @since 2.0.0
 	 */
 	public function supportsType( string $type ): bool {
 		return in_array( $type, $this->type );
@@ -269,7 +346,9 @@ public function supportsType( string $type ): bool {
 	/**
 	 * Set the type of the property.
 	 *
-	 * @param string[] $types The types of the property, multiple types are considered a union type.
+	 * @since 2.0.0
+	 *
+	 * @param string ...$types The types of the property, multiple types are considered a union type.
 	 */
 	public function type( string ...$types ): self {
 		$this->checkLock();