Add class level docs (#21)

Author: cspray

README.md

@@ -42,12 +42,12 @@ class FooImplementation {}
 
 // app bootstrap in __DIR__ . '/app.php'
 
-use Cspray\AnnotatedContainer\AurynInjectorFactory;
+use Cspray\AnnotatedContainer\AurynContainerFactory;
 use Cspray\AnnotatedContainer\PhpParserInjectorDefinitionCompiler;
 
 $compiler = new PhpParserInjectorDefinitionCompiler();
 $injectorDefinition = $compiler->compileDirectory('env_identifier', __DIR__ . '/src');
-$injector = (new AurynInjectorFactory)->createContainer($injectorDefinition);
+$injector = (new AurynContainerFactory)->createContainer($injectorDefinition);
 
 var_dump($injector->make(Foo::class));
 ```

examples/getting_started/dev_app.php

@@ -4,7 +4,7 @@
 
 $compiler = new \Cspray\AnnotatedContainer\PhpParserContainerDefinitionCompiler();
 $injectorDefinition = $compiler->compile('dev', __DIR__ . '/src');
-$injector = (new Cspray\AnnotatedContainer\AurynInjectorFactory)->createInjector($injectorDefinition);
+$injector = (new Cspray\AnnotatedContainer\AurynContainerFactory)->createInjector($injectorDefinition);
 
 $blobStorage = $injector->make(\Acme\AnnotatedContainerDemo\BlobStorage::class);
 

examples/getting_started/prod_app.php

@@ -4,7 +4,7 @@
 
 $compiler = new \Cspray\AnnotatedContainer\PhpParserContainerDefinitionCompiler();
 $injectorDefinition = $compiler->compile('prod', __DIR__ . '/src');
-$injector = (new Cspray\AnnotatedContainer\AurynInjectorFactory)->createInjector($injectorDefinition);
+$injector = (new Cspray\AnnotatedContainer\AurynContainerFactory)->createInjector($injectorDefinition);
 
 $blobStorage = $injector->make(\Acme\AnnotatedContainerDemo\BlobStorage::class);
 

examples/getting_started/test_app.php

@@ -4,7 +4,7 @@
 
 $compiler = new \Cspray\AnnotatedContainer\PhpParserContainerDefinitionCompiler();
 $injectorDefinition = $compiler->compile('test', __DIR__ . '/src');
-$injector = (new Cspray\AnnotatedContainer\AurynInjectorFactory)->createInjector($injectorDefinition);
+$injector = (new Cspray\AnnotatedContainer\AurynContainerFactory)->createInjector($injectorDefinition);
 
 $blobStorage = $injector->make(\Acme\AnnotatedContainerDemo\BlobStorage::class);
 

examples/scalar_and_service_defines/constructor_injection_app.php

@@ -4,7 +4,7 @@
 
 $compiler = new \Cspray\AnnotatedContainer\PhpParserInjectorDefinitionCompiler();
 $injectorDefinition = $compiler->compileDirectory('dev', __DIR__ . '/src');
-$injector = (new Cspray\AnnotatedContainer\AurynInjectorFactory)->createContainer($injectorDefinition);
+$injector = (new Cspray\AnnotatedContainer\AurynContainerFactory)->createContainer($injectorDefinition);
 
 $subject = $injector->make(\Acme\AnnotatedContainerDemo\MixedDefinesConstructorInjection::class);
 

examples/scalar_and_service_defines/prepare_injection_app.php

@@ -4,7 +4,7 @@
 
 $compiler = new \Cspray\AnnotatedContainer\PhpParserContainerDefinitionCompiler();
 $injectorDefinition = $compiler->compile('dev', __DIR__ . '/src');
-$injector = (new Cspray\AnnotatedContainer\AurynInjectorFactory)->createInjector($injectorDefinition);
+$injector = (new Cspray\AnnotatedContainer\AurynContainerFactory)->createInjector($injectorDefinition);
 
 $subject = $injector->make(\Acme\AnnotatedContainerDemo\MixedDefinesSetterInjection::class);
 

examples/scalar_values/dev_app.php

@@ -4,7 +4,7 @@
 
 $compiler = new \Cspray\AnnotatedContainer\PhpParserInjectorDefinitionCompiler();
 $injectorDefinition = $compiler->compileDirectory('dev', __DIR__ . '/src');
-$injector = (new Cspray\AnnotatedContainer\AurynInjectorFactory)->createContainer($injectorDefinition);
+$injector = (new Cspray\AnnotatedContainer\AurynContainerFactory)->createContainer($injectorDefinition);
 
 $scalarGetter = $injector->make(\Acme\AnnotatedContainerDemo\ScalarGetter::class);
 

examples/scalar_values/prod_app.php

@@ -4,7 +4,7 @@
 
 $compiler = new \Cspray\AnnotatedContainer\PhpParserInjectorDefinitionCompiler();
 $injectorDefinition = $compiler->compileDirectory('prod', __DIR__ . '/src');
-$injector = (new Cspray\AnnotatedContainer\AurynInjectorFactory)->createContainer($injectorDefinition);
+$injector = (new Cspray\AnnotatedContainer\AurynContainerFactory)->createContainer($injectorDefinition);
 
 $scalarGetter = $injector->make(\Acme\AnnotatedContainerDemo\ScalarGetter::class);
 

examples/scalar_values/test_app.php

@@ -4,7 +4,7 @@
 
 $compiler = new \Cspray\AnnotatedContainer\PhpParserInjectorDefinitionCompiler();
 $injectorDefinition = $compiler->compileDirectory('test', __DIR__ . '/src');
-$injector = (new Cspray\AnnotatedContainer\AurynInjectorFactory)->createContainer($injectorDefinition);
+$injector = (new Cspray\AnnotatedContainer\AurynContainerFactory)->createContainer($injectorDefinition);
 
 $scalarGetter = $injector->make(\Acme\AnnotatedContainerDemo\ScalarGetter::class);
 

src/AliasDefinition.php

@@ -3,16 +3,32 @@
 namespace Cspray\AnnotatedContainer;
 
 /**
- * Defines the ServiceDefinition that should be used to generate aliases on the wired Injector.
+ * Define the concrete Service that should be used when constructing an abstract Service.
  *
- * @package Cspray\AnnotatedContainer
+ * @see AliasDefinitionBuilder
  */
 interface AliasDefinition {
 
+    /**
+     * An abstract Service used by your application but cannot be constructed directly.
+     *
+     * @return ServiceDefinition
+     */
     public function getAbstractService() : ServiceDefinition;
 
+    /**
+     * The concrete Service that should be used where your applications requires the corresponding abstract Service.
+     *
+     * @return ServiceDefinition
+     */
     public function getConcreteService() : ServiceDefinition;
 
+    /**
+     * Returns whether the given $aliasDefinition has matching abstract and concrete services.
+     *
+     * @param AliasDefinition $aliasDefinition
+     * @return bool
+     */
     public function equals(AliasDefinition $aliasDefinition) : bool;
 
 }

src/AliasDefinitionBuilder.php

@@ -4,13 +4,23 @@
 
 use Cspray\AnnotatedContainer\Exception\DefinitionBuilderException;
 
+/**
+ * The preferred method for constructing AliasDefinition instances.
+ */
 final class AliasDefinitionBuilder {
 
     private ServiceDefinition $abstractType;
     private ServiceDefinition $concreteType;
 
     private function __construct() {}
 
+    /**
+     * Define the abstract Service that should have an alias defined for it.
+     *
+     * @param ServiceDefinition $serviceDefinition
+     * @return static
+     * @throws DefinitionBuilderException
+     */
     public static function forAbstract(ServiceDefinition $serviceDefinition) : self {
         if (!$serviceDefinition->isAbstract()) {
             throw new DefinitionBuilderException(sprintf(
@@ -23,6 +33,15 @@ public static function forAbstract(ServiceDefinition $serviceDefinition) : self
         return $instance;
     }
 
+    /**
+     * Define the concrete Service that acts as an alias for the given abstract Service.
+     *
+     * This method is immutable and a new AliasDefinitionBuilder will be returned.
+     *
+     * @param ServiceDefinition $serviceDefinition
+     * @return $this
+     * @throws DefinitionBuilderException
+     */
     public function withConcrete(ServiceDefinition $serviceDefinition) : self {
         if ($serviceDefinition->isAbstract()) {
             throw new DefinitionBuilderException(sprintf(
@@ -35,6 +54,11 @@ public function withConcrete(ServiceDefinition $serviceDefinition) : self {
         return $instance;
     }
 
+    /**
+     * Returns an AliasDefinition with the provided abstract and concrete Services.
+     *
+     * @return AliasDefinition
+     */
     public function build() : AliasDefinition {
         return new class($this->abstractType, $this->concreteType) implements AliasDefinition {
             private ServiceDefinition $abstractService;

src/Attribute/InjectService.php

@@ -13,8 +13,6 @@
 #[Attribute(Attribute::TARGET_PARAMETER)]
 final class InjectService {
 
-    public function __construct(
-        private string $name
-    ) {}
+    public function __construct(private string $name) {}
 
 }

src/Attribute/ServiceDelegate.php

@@ -7,14 +7,6 @@
 #[Attribute(Attribute::TARGET_METHOD)]
 final class ServiceDelegate {
 
-    private string $forService;
-
-    public function __construct(string $forService) {
-        $this->forService = $forService;
-    }
-
-    public function getForService() : string {
-        return $this->forService;
-    }
+    public function __construct(private string $forService) {}
 
 }

src/Attribute/ServiceProfile.php

@@ -7,10 +7,7 @@
 #[Attribute(Attribute::TARGET_CLASS)]
 final class ServiceProfile {
 
-    private array $profiles;
 
-    public function __construct(array $profiles) {
-        $this->profiles = $profiles;
-    }
+    public function __construct(private array $profiles) {}
 
 }

src/AurynInjectorFactory.php src/AurynContainerFactory.php

@@ -5,17 +5,31 @@
 use Auryn\InjectionException;
 use Auryn\Injector;
 use Cspray\AnnotatedContainer\Exception\ContainerException;
-use Psr\Container\ContainerExceptionInterface;
 use Psr\Container\ContainerInterface;
-use Psr\Container\NotFoundExceptionInterface;
 
 /**
- * Wires together an Injector from an ContainerDefinition or a JSON serialization of an ContainerDefinition.
- *
- * @package Cspray\AnnotatedContainer
+ * Creates a PSR Container from a ContainerDefinition backed by an Auryn\Injector.
  */
-final class AurynInjectorFactory implements ContainerFactory {
-
+final class AurynContainerFactory implements ContainerFactory {
+
+    /**
+     * Returns a PSR ContainerInterface that uses an Auryn\Injector to create services.
+     *
+     * Because Auryn does not provide a PSR compatible Container we wrap the injector in an anonymous class that
+     * implements the PSR ContainerInterface. Auryn has the capacity to recursively autowire Services at time of
+     * construction and does not necessarily need to have the Service defined ahead of time if the constructor
+     * dependencies can be reliably determined. This fact makes the has() method for this particular Container a little
+     * tricky in that a service could be successfully constructed but if we don't have something specifically defined
+     * stating how to construct some aspect of it we can't reliably determine whether or not the Container "has" the
+     * Service.
+     *
+     * This limitation should be short-lived as the Auryn Injector is being migrated to a new organization and codebase.
+     * Once that migration has been completed a new ContainerFactory using that implementation will be used and this
+     * implementation will be deprecated.
+     *
+     * @param ContainerDefinition $containerDefinition
+     * @return ContainerInterface
+     */
     public function createContainer(ContainerDefinition $containerDefinition) : ContainerInterface {
         return new class($this->createInjector($containerDefinition)) implements ContainerInterface {
 

src/CacheAwareContainerDefinitionCompiler.php

@@ -3,20 +3,42 @@
 namespace Cspray\AnnotatedContainer;
 
 use Cspray\AnnotatedContainer\Exception\InvalidCacheException;
-use InvalidArgumentException;
 
+/**
+ * A ContainerDefinitionCompiler decorator that allows for a ContainerDefinition to be serialized and cached to the
+ * filesystem; this could potentially save time on very large codebases or be used when building production to not
+ * require Container compilation on every request.
+ */
 final class CacheAwareContainerDefinitionCompiler implements ContainerDefinitionCompiler {
 
     private ContainerDefinitionCompiler $containerDefinitionCompiler;
     private ContainerDefinitionSerializer $containerDefinitionSerializer;
     private string $cacheDir;
 
+    /**
+     * @param ContainerDefinitionCompiler $containerDefinitionCompiler The compiler to use if the cache file is not present
+     * @param ContainerDefinitionSerializer $containerDefinitionSerializer The serializer to serialize/deserialize the cached ContainerDefinition
+     * @param string $cacheDir The directory that the cache files should be generated
+     */
     public function __construct(ContainerDefinitionCompiler $containerDefinitionCompiler, ContainerDefinitionSerializer $containerDefinitionSerializer, string $cacheDir) {
         $this->containerDefinitionCompiler = $containerDefinitionCompiler;
         $this->containerDefinitionSerializer = $containerDefinitionSerializer;
         $this->cacheDir = $cacheDir;
     }
 
+    /**
+     * Will generate a ContainerDefinition from a serialized cache file.
+     *
+     * If the cached file is not present will generate a ContainerDefinition from the passed ContainerDefinitionCompiler
+     * and save it to the $cacheDir based off of the directories to scan and the active profiles for the given compile
+     * options.
+     *
+     * Please see bin/annotated-container compile --help for more information on pre-generating the cached ContainerDefinition.
+     *
+     * @param ContainerDefinitionCompileOptions $containerDefinitionCompileOptions
+     * @return ContainerDefinition
+     * @throws InvalidCacheException
+     */
     public function compile(ContainerDefinitionCompileOptions $containerDefinitionCompileOptions): ContainerDefinition {
         $cacheFile = $this->getCacheFile(
             $containerDefinitionCompileOptions->getProfiles(),

src/ContainerDefinition.php

@@ -2,54 +2,79 @@
 
 namespace Cspray\AnnotatedContainer;
 
+use Cspray\AnnotatedContainer\Exception\ContainerDefinitionMergeException;
+
 /**
+ * The heart of the AnnotatedContainer; the ContainerDefinition, an object which defines how a Container should be
+ * configured.
  *
- *
- * @package Cspray\AnnotatedContainer
+ * @see ContainerDefinitionBuilder
  */
 interface ContainerDefinition {
 
+    /**
+     * An immutable method that will return new ContainerDefinition that has the contents of this ContainerDefinition and
+     * the passed $containerDefinition.
+     *
+     * @param ContainerDefinition $containerDefinition
+     * @return ContainerDefinition
+     * @throws ContainerDefinitionMergeException An exception that can be thrown if the given $containerDefinition can't be merged for some reason
+     */
     public function merge(ContainerDefinition $containerDefinition) : ContainerDefinition;
 
     /**
-     * Returns a set of ServiceDefinition that are shared with the Injector.
+     * Return a set of ServiceDefinitions that this Container is aware of.
      *
      * Note that this IS NOT necessarily an exhaustive list of every class and interface annotated with Service. It is
-     * possible, and likely, that a concrete implementation is listed as an alias or is not meant to be loaded with this
-     * Injector due to the environment it is supposed to be running in.
+     * possible, and likely, that a concrete implementation is marked as belonging to a profile that isn't currently
+     * active. This, and potentially other valid reasons, might exclude a type annotated with Service from appearing
+     * this collection.
      *
      * @return ServiceDefinition[]
      */
     public function getServiceDefinitions() : array;
 
     /**
-     * Returns a set of AliasDefinition that define which concrete implementations are meant to be used for a given
-     * interface.
+     * Returns a set of AliasDefinition that define which concrete services are possible candidate for a given abstract
+     * service.
      *
-     * Please note that as of 0.1.x multiple alias conflict resolution is not in place and it is possible to have
-     * multiple AliasDefinitions for the same interface that could result in unexpected services from being injected.
-     * Multiple alias conflict resolution is scheduled for the 0.2.x release series.
+     * Note that it is possible for an abstract service to have multiple AliasDefinition defined for it. It is not the
+     * job of the ContainerDefinition to determine what should be done in this situation; it is meant to simply provide
+     * the results of a configuration for a Container and an annotated configuration is possible to have multiple
+     * concrete services that could satisfy an abstract service. It is the responsibility of the ContainerFactory
+     * or a LogicalConstraintValidator to recognize multiple aliases are possible and take the appropriate steps.
      *
      * @return AliasDefinition[]
      */
     public function getAliasDefinitions() : array;
 
     /**
+     * Returns a set of ServicePrepareDefinition that determine which service methods will be automatically invoked
+     * after service construction.
+     *
      * @return ServicePrepareDefinition[]
      */
     public function getServicePrepareDefinitions() : array;
 
     /**
+     * Returns a set of InjectScalarDefinition that determine what values to use when a service parameter requires a
+     * scalar or non-object value injected into it.
+     *
      * @return InjectScalarDefinition[]
      */
     public function getInjectScalarDefinitions() : array;
 
     /**
+     * Returns a set of InjectServiceDefinition that determine a specific service to inject into a parameter where
+     * normal alias resolution might not be possible.
+     *
      * @return InjectServiceDefinition[]
      */
     public function getInjectServiceDefinitions() : array;
 
     /**
+     * Returns a set of ServiceDelegateDefinition that determine which services require factories to be constructed.
+     *
      * @return ServiceDelegateDefinition[]
      */
     public function getServiceDelegateDefinitions() : array;