📝 Add docstrings to refactor/cleanup

src/ForerunnerServiceProvider.php

@@ -11,7 +11,10 @@
 class ForerunnerServiceProvider extends ServiceProvider
 {
     /**
-     * Register any application services.
+     * Register the Forerunner schema service in the application container.
+     *
+     * Binds a singleton under the container key "forerunner.schema" that resolves to an object
+     * which forwards dynamic instance and static calls to the `Struct` class's static methods.
      */
     public function register(): void
     {
@@ -38,7 +41,9 @@ public function __call(string $method, array $args): mixed
     }
 
     /**
-     * Bootstrap any application services.
+     * Register console commands when the application is running in a console.
+     *
+     * Registers the MakeStructCommand so it becomes available to the application's CLI when executed in a console environment.
      */
     public function boot(): void
     {
@@ -48,4 +53,4 @@ public function boot(): void
             ]);
         }
     }
-}
+}

src/Schema/Property.php

@@ -24,6 +24,11 @@ class Property
 
     protected bool $isStrict = false;
 
+    /**
+     * Initialize the Property with the given schema node name.
+     *
+     * @param string $name The property name for this schema node.
+     */
     public function __construct(string $name)
     {
         $this->name = $name;
@@ -94,7 +99,12 @@ public function array(string $name, ?string $description = null): PropertyBuilde
     }
 
     /**
-     * Add a nested object field.
+     * Create and register a nested object property and return its builder.
+     *
+     * @param string $name The property name to create on this object.
+     * @param callable $callback A callback invoked with the newly created nested Property to configure its schema.
+     * @param string|null $description Optional description for the nested property.
+     * @return PropertyBuilder The builder for the created nested object property.
      */
     public function object(string $name, callable $callback, ?string $description = null): PropertyBuilder
     {
@@ -225,8 +235,9 @@ public function additionalProperties(bool $allowed = true): self
     }
 
     /**
-     * Enable strict mode: disallow additional properties and mark all fields as required.
-     * This is useful for LLM APIs like OpenAI that require all properties to be required.
+     * Enables strict mode for the schema: disallows additional properties and marks all defined properties as required.
+     *
+     * @return self The current Property instance.
      */
     public function strict(): self
     {
@@ -242,7 +253,9 @@ public function strict(): self
     }
 
     /**
-     * Check if strict mode is enabled.
+     * Determine whether strict mode is enabled for this schema.
+     *
+     * @return bool `true` if strict mode is enabled, `false` otherwise.
      */
     public function isStrict(): bool
     {
@@ -330,4 +343,4 @@ public function toJson(): string
     {
         return json_encode($this->toArray(), JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR);
     }
-}
+}

src/Schema/PropertyBuilder.php

@@ -96,7 +96,11 @@ public function enum(array $values): self
     }
 
     /**
-     * Define the items type for array fields.
+     * Configure the schema for array items.
+     *
+     * @param string $type The JSON Schema type for items. When set to `'object'`, the optional callback will be used to configure the object item schema.
+     * @param callable|null $callback Optional function that receives a Property builder to configure an object-type item schema.
+     * @return $this The current PropertyBuilder instance.
      */
     public function items(string $type, ?callable $callback = null): self
     {
@@ -232,7 +236,10 @@ public function nullable(bool $nullable = true): self
     }
 
     /**
-     * Set a nested builder for object types.
+     * Assigns a nested Property builder to define the schema for an object-type property.
+     *
+     * @param Property $builder The nested property builder whose schema will be merged into this property's definition.
+     * @return void
      */
     public function setNestedBuilder(Property $builder): void
     {
@@ -339,4 +346,4 @@ public function toArray(): array
 
         return $property;
     }
-}
+}

src/Schema/Struct.php

@@ -13,14 +13,25 @@ class Struct implements \JsonSerializable
     /** @var array<string, mixed>|null */
     protected ?array $cache = null;
 
+    /**
+     * Initialize the struct with its identifier and property builder.
+     *
+     * @param string $name The struct's name used when emitting the schema.
+     * @param Property $builder The Property builder responsible for producing this struct's schema.
+     */
     protected function __construct(string $name, Property $builder)
     {
         $this->name = $name;
         $this->builder = $builder;
     }
 
     /**
-     * Define a new structure schema.
+     * Create a Struct by configuring a Property builder and returning the resulting schema.
+     *
+     * @param string $name The name of the structure.
+     * @param string $description A human-readable description for the structure.
+     * @param callable $callback A callable that receives the Property builder (`function(Property $builder): void`) used to configure the structure.
+     * @return self A new Struct instance representing the defined schema.
      */
     public static function define(string $name, string $description, callable $callback): self
     {
@@ -33,10 +44,13 @@ public static function define(string $name, string $description, callable $callb
     }
 
     /**
-     * Convert the schema to an array.
-     * If strict mode is enabled, wraps the schema in OpenAI's format.
+     * Converts the struct to an associative array representation.
+     *
+     * When the builder is in strict mode the returned array is in OpenAI-compatible format with keys
+     * 'name' (the struct name), 'strict' set to true, and 'schema' containing the builder's schema.
+     * The result is cached for subsequent calls.
      *
-     * @return array<string, mixed>
+     * @return array<string,mixed> The schema array, or the OpenAI-compatible wrapper when strict mode is enabled.
      */
     public function toArray(): array
     {
@@ -59,12 +73,12 @@ public function toArray(): array
     }
 
     /**
-     * Specify data which should be serialized to JSON.
+     * Provide this struct's array representation for JSON serialization.
      *
-     * @return array<string, mixed>
+     * @return array<string,mixed> The struct schema as an associative array suitable for json_encode().
      */
     public function jsonSerialize(): array
     {
         return $this->toArray();
     }
-}
+}