From b3d05c8af9439ce4237481cbaeee58a2158ffc3b Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Sat, 18 Oct 2025 11:49:18 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`refacto?= =?UTF-8?q?r/cleanup`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docstrings generation was requested by @deemonic. * https://github.com/Blaspsoft/forerunner/pull/1#issuecomment-3417396618 The following files were modified: * `src/ForerunnerServiceProvider.php` * `src/Schema/Property.php` * `src/Schema/PropertyBuilder.php` * `src/Schema/Struct.php` --- src/ForerunnerServiceProvider.php | 11 ++++++++--- src/Schema/Property.php | 23 ++++++++++++++++++----- src/Schema/PropertyBuilder.php | 13 ++++++++++--- src/Schema/Struct.php | 28 +++++++++++++++++++++------- 4 files changed, 57 insertions(+), 18 deletions(-) diff --git a/src/ForerunnerServiceProvider.php b/src/ForerunnerServiceProvider.php index 7a8f825..8b15ef1 100644 --- a/src/ForerunnerServiceProvider.php +++ b/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 ]); } } -} +} \ No newline at end of file diff --git a/src/Schema/Property.php b/src/Schema/Property.php index 65e8ed0..01a00c6 100644 --- a/src/Schema/Property.php +++ b/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); } -} +} \ No newline at end of file diff --git a/src/Schema/PropertyBuilder.php b/src/Schema/PropertyBuilder.php index d638cc6..613917f 100644 --- a/src/Schema/PropertyBuilder.php +++ b/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; } -} +} \ No newline at end of file diff --git a/src/Schema/Struct.php b/src/Schema/Struct.php index f1321c1..866c2cd 100644 --- a/src/Schema/Struct.php +++ b/src/Schema/Struct.php @@ -13,6 +13,12 @@ class Struct implements \JsonSerializable /** @var array|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; @@ -20,7 +26,12 @@ protected function __construct(string $name, Property $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 + * @return array 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 + * @return array The struct schema as an associative array suitable for json_encode(). */ public function jsonSerialize(): array { return $this->toArray(); } -} +} \ No newline at end of file