feat: add inline documentation on all namespaced functions (#616)

Co-authored-by: Brent Roose <[email protected]>

Author: innocenzi

src/Tempest/CommandBus/src/functions.php

@@ -6,6 +6,9 @@
 
     use Tempest\CommandBus\CommandBus;
 
+    /**
+     * Dispatches the given `$command` to the {@see CommandBus}, triggering all associated command handlers.
+     */
     function command(object $command): void
     {
         $commandBus = get(CommandBus::class);

src/Tempest/Container/src/functions.php

@@ -9,6 +9,8 @@
     use Tempest\Reflection\MethodReflector;
 
     /**
+     * Retrieves an instance of the specified `$className` from the container.
+     *
      * @template TClassName of object
      * @param class-string<TClassName> $className
      * @return TClassName
@@ -20,6 +22,19 @@ function get(string $className, ?string $tag = null, mixed ...$params): object
         return $container->get($className, $tag, ...$params);
     }
 
+    /**
+     * Invokes the given method, function, callable or invokable class from the container. If no named parameters are specified, they will be resolved from the container.
+     *
+     * #### Examples
+     * ```php
+     * \Tempest\invoke(function (MyService $service) {
+     *   $service->execute();
+     * });
+     * ```
+     * ```php
+     * \Tempest\invoke(MyService::class, key: $apiKey);
+     * ```
+     */
     function invoke(MethodReflector|FunctionReflector|callable|string $callable, mixed ...$params): mixed
     {
         $container = GenericContainer::instance();

src/Tempest/Core/src/functions.php

@@ -10,6 +10,9 @@
     use Tempest\Core\Kernel;
     use function Tempest\Support\str;
 
+    /**
+     * Creates and sanitizes a file system path from the given `$parts`. The resulting path is not checked against the file system.
+     */
     function path(string ...$parts): string
     {
         $path = implode('/', $parts);
@@ -21,18 +24,27 @@ function path(string ...$parts): string
         );
     }
 
+    /**
+     * Creates a path scoped within the root of the project
+     */
     function root_path(string ...$parts): string
     {
         return path(realpath(get(Kernel::class)->root), ...$parts);
     }
 
+    /**
+     * Creates a path scoped within the src folder of the project
+     */
     function src_path(string ...$parts): string
     {
         $composer = get(Composer::class);
 
         return path($composer->mainNamespace->path, ...$parts);
     }
 
+    /**
+     * Creates a namespace scoped within the main namespace of the project
+     */
     function src_namespace(?string $append = null): string
     {
         $composer = get(Composer::class);
@@ -44,6 +56,9 @@ function src_namespace(?string $append = null): string
             ->toString();
     }
 
+    /**
+     * Retrieves the given `$key` from the environment variables. If `$key` is not defined, `$default` is returned instead.
+     */
     function env(string $key, mixed $default = null): mixed
     {
         $value = getenv($key);
@@ -60,6 +75,9 @@ function env(string $key, mixed $default = null): mixed
         };
     }
 
+    /**
+     * Defer a task, will be run after a request has been sent or a command has executed
+     */
     function defer(Closure $closure): void
     {
         get(DeferredTasks::class)->add($closure);

src/Tempest/Debug/src/functions.php

@@ -7,13 +7,21 @@
     use Tempest\Debug\Debug;
 
     if (! function_exists('lw')) {
+        /**
+         * Writes the given `$input` to the logs, and dumps it.
+         * @see \Tempest\Debug\Debug::log()
+         */
         function lw(mixed ...$input): void
         {
             Debug::resolve()->log($input);
         }
     }
 
     if (! function_exists('ld')) {
+        /**
+         * Writes the given `$input` to the logs, dumps it, and stops the execution of the script.
+         * @see \Tempest\Debug\Debug::log()
+         */
         function ld(mixed ...$input): void
         {
             Debug::resolve()->log($input);
@@ -22,22 +30,34 @@ function ld(mixed ...$input): void
     }
 
     if (! function_exists('ll')) {
+        /**
+         * Writes the given `$input` to the logs.
+         * @see \Tempest\Debug\Debug::log()
+         */
         function ll(mixed ...$input): void
         {
             Debug::resolve()->log($input, writeToOut: false);
         }
     }
 
-    // Alias dd to ld
     if (! function_exists('dd')) {
+        /**
+         * Writes the given `$input` to the logs, dumps it, and stops the execution of the script.
+         * @see ld()
+         * @see \Tempest\Debug\Debug::log()
+         */
         function dd(mixed ...$input): void
         {
             ld(...$input);
         }
     }
 
-    // Alias dump to lw
     if (! function_exists('dump')) {
+        /**
+         * Writes the given `$input` to the logs, and dumps it.
+         * @see lw()
+         * @see \Tempest\Debug\Debug::log()
+         */
         function dump(mixed ...$input): void
         {
             lw(...$input);

src/Tempest/EventBus/src/functions.php

@@ -8,13 +8,19 @@
     use Tempest\EventBus\EventBus;
     use Tempest\EventBus\EventBusConfig;
 
+    /**
+     * Dispatches the given `$event`, triggering all associated event listeners.
+     */
     function event(string|object $event): void
     {
         $eventBus = get(EventBus::class);
 
         $eventBus->dispatch($event);
     }
 
+    /**
+     * Registers a closure-based event listener for the given `$event`.
+     */
     function listen(string|object $event, Closure $handler): void
     {
         $config = get(EventBusConfig::class);

src/Tempest/Http/src/functions.php

@@ -7,6 +7,9 @@
     use Tempest\Http\Router;
     use Tempest\Reflection\MethodReflector;
 
+    /**
+     * Creates a valid URI to the given controller `$action`.
+     */
     function uri(array|string|MethodReflector $action, ...$params): string
     {
         if ($action instanceof MethodReflector) {

src/Tempest/Mapper/src/functions.php

@@ -3,9 +3,20 @@
 declare(strict_types=1);
 
 namespace Tempest {
+
     use Tempest\Mapper\ObjectFactory;
 
     /**
+     * Creates a factory which allows instanciating `$objectOrClass` with the data specified by the {@see \Tempest\Mapper\ObjectFactory::from()} method.
+     *
+     * ### Example
+     * ```php
+     * make(Author::class)->from([
+     *   'first_name' => 'Jon',
+     *   'last_name' => 'Doe',
+     * ])
+     * ```
+     *
      * @template T of object
      * @param T|class-string<T> $objectOrClass
      * @return ObjectFactory<T>
@@ -17,6 +28,17 @@ function make(object|string $objectOrClass): ObjectFactory
         return $factory->forClass($objectOrClass);
     }
 
+    /**
+     * Creates a factory which allows instanciating the object or class specified by {@see \Tempest\Mapper\ObjectFactory::to()} the given `$data`.
+     *
+     * ### Example
+     * ```php
+     * map([
+     *   'first_name' => 'Jon',
+     *   'last_name' => 'Doe',
+     * ])->to($author);
+     * ```
+     */
     function map(mixed $data): ObjectFactory
     {
         $factory = get(ObjectFactory::class);

src/Tempest/Reflection/src/functions.php

@@ -9,6 +9,9 @@
     use Tempest\Reflection\ClassReflector;
     use Tempest\Reflection\PropertyReflector;
 
+    /**
+     * Creates a new {@see Reflector} instance based on the given `$classOrProperty`.
+     */
     function reflect(mixed $classOrProperty, ?string $propertyName = null): ClassReflector|PropertyReflector
     {
         if ($classOrProperty instanceof PHPReflectionClass) {

src/Tempest/Support/src/functions.php

@@ -3,11 +3,17 @@
 declare(strict_types=1);
 
 namespace Tempest\Support {
+    /**
+     * Creates an instance of {@see StringHelper} using the given `$string`.
+     */
     function str(string $string = ''): StringHelper
     {
         return new StringHelper($string);
     }
 
+    /**
+     * Creates an instance of {@see ArrayHelper} using the given `$input`. If `$input` is not an array, it will be wrapped in one.
+     */
     function arr(mixed $input = []): ArrayHelper
     {
         return new ArrayHelper($input);

src/Tempest/View/src/functions.php

@@ -8,6 +8,9 @@
     use Tempest\View\GenericView;
     use Tempest\View\View;
 
+    /**
+     * Returns a {@see View} instance for the specified `$path`.
+     */
     function view(string $path, mixed ...$params): View
     {
         return (new GenericView($path))->data(...$params);