Updates, extensions and fixes in phpDoc descriptions

src/CompositeContainer.php

@@ -14,6 +14,10 @@
 use Psr\Container\ContainerInterface;
 
 
+/**
+ * RecordContainer merged with additional sub-containers accessed
+ * with separated prefix identifier.
+ */
 class CompositeContainer implements ContainerInterface
 {
     public const SEPARATOR = '.';
@@ -22,6 +26,10 @@ class CompositeContainer implements ContainerInterface
     private $containers;
 
     /**
+     * Container identifiers cannot contain separator.
+     * Records will not be called when existing container
+     * identifier is used (as prefix).
+     *
      * @param Records              $records
      * @param ContainerInterface[] $containers
      */

src/ConfigContainer.php

@@ -16,7 +16,8 @@
 
 /**
  * Container with multidimensional array values accessed using path notation identifiers.
- * Example: $config['key']['sub-key']['id'] is accessed with $instance->get('key.sub-key.id').
+ *
+ * @example $instance->get('key.sub-key.id') === $config['key']['sub-key']['id']
  */
 class ConfigContainer implements ContainerInterface
 {
@@ -25,8 +26,8 @@ class ConfigContainer implements ContainerInterface
     private $config;
 
     /**
-     * $config keys MUST NOT contain path separator, because values
-     * stored under these keys will not be accessible.
+     * $config keys MUST NOT contain path separator on any level,
+     * because values stored under these keys will not be accessible.
      *
      * @param array $config Associative (multidimensional) array of config values
      */

src/RecordContainer.php

@@ -14,6 +14,10 @@
 use Psr\Container\ContainerInterface;
 
 
+/**
+ * ContainerInterface implementation using Records instance
+ * with various strategies to deliver values.
+ */
 class RecordContainer implements ContainerInterface
 {
     protected $records;

src/Records.php

@@ -14,6 +14,9 @@
 use Psr\Container\ContainerInterface;
 
 
+/**
+ * Container of Record strategies to produce container values.
+ */
 class Records
 {
     private $records;
@@ -27,7 +30,8 @@ public function __construct(array $records = [])
     }
 
     /**
-     * Checks if Record is stored at given identifier.
+     * Checks if Record is stored at given identifier without
+     * calling for its value.
      *
      * @param string $id
      *
@@ -39,7 +43,9 @@ public function has(string $id): bool
     }
 
     /**
-     * Returns Record stored at given identifier.
+     * Returns Record value stored at given identifier.
+     * ContainerInterface is given for possibility of producing
+     * Record's value using another container entries.
      *
      * @param string             $id
      * @param ContainerInterface $container

src/Records/Record.php

@@ -23,11 +23,11 @@ interface Record
      * Unwraps value requested from container.
      *
      * Container instance is passed as parameter because value
-     * may derive from other Container entries.
+     * may need other container entries to be created.
      *
      * @param ContainerInterface $container
      *
-     * @return mixed unwrapped record value
+     * @return mixed
      */
     public function value(ContainerInterface $container);
 }

src/Records/Record/CallbackRecord.php

@@ -16,10 +16,10 @@
 
 
 /**
- * Record that returns value invoked from callable property.
+ * Record that returns value invoked from given callback, called with
+ * ContainerInterface instance as parameter.
  *
- * Returned value is cached and returned directly when
- * value() method is called again.
+ * Returned value is cached and returned directly on subsequent calls.
  */
 class CallbackRecord implements Record
 {

src/Records/Record/ComposeRecord.php

@@ -19,8 +19,7 @@
  * Record that creates and returns object of given class name
  * created with Container entries as its constructor parameters.
  *
- * Returned object is cached and returned directly when
- * value() method is called again.
+ * Returned value is cached and returned directly on subsequent calls.
  */
 class ComposeRecord implements Record
 {
@@ -31,8 +30,8 @@ class ComposeRecord implements Record
     private $object;
 
     /**
-     * @param string   $className
-     * @param string[] $dependencies ContainerInterface ids to get constructor values from
+     * @param string $className       class to instantiate
+     * @param string ...$dependencies container identifiers for class constructor parameters
      */
     public function __construct(string $className, string ...$dependencies)
     {

src/Records/Record/CreateMethodRecord.php

@@ -16,10 +16,11 @@
 
 
 /**
- * Record that creates its value by calling a method on (factory) object.
+ * Record that creates returned value by calling method name
+ * and container entries both as method's parameters and factory
+ * object the call is made on.
  *
- * Returned value is cached and returned directly when
- * value() method is called again.
+ * Returned value is cached and returned directly on subsequent calls.
  */
 class CreateMethodRecord implements Record
 {
@@ -31,9 +32,9 @@ class CreateMethodRecord implements Record
     private $product;
 
     /**
-     * @param string $method
-     * @param string $factoryId
-     * @param string ...$arguments
+     * @param string $factoryId    container identifier for factory object
+     * @param string $method       factory method name
+     * @param string ...$arguments container identifiers for method parameters
      */
     public function __construct(string $factoryId, string $method, string ...$arguments)
     {

src/Records/Record/ValueRecord.php

@@ -16,7 +16,7 @@
 
 
 /**
- * Record that returns its property value directly.
+ * Record that directly returns its property value.
  */
 class ValueRecord implements Record
 {

src/Records/TrackedRecords.php

@@ -16,6 +16,11 @@
 use Psr\Container\ContainerInterface;
 
 
+/**
+ * Instance of Records with nested call tracking, detecting
+ * circular calls to passed ContainerInterface and appending
+ * call stack paths to exception messages.
+ */
 class TrackedRecords extends Records
 {
     private $callStack = [];

src/Setup.php

@@ -23,12 +23,27 @@ public function __construct(Setup\Collection $collection = null)
         $this->collection = $collection ?: new Setup\Collection();
     }
 
+    /**
+     * Creates Setup with validated collection.
+     *
+     * Added entries will be validated for identifier conflicts and
+     * created container will be monitored for circular references.
+     *
+     * @return self
+     */
     public static function secure(): self
     {
         return new self(new Setup\ValidatedCollection());
     }
 
     /**
+     * Creates Setup with predefined configuration.
+     *
+     * If `true` is passed as $validate param secure version of Setup
+     * will be created and predefined configuration will be validated.
+     *
+     * @see Setup::secure()
+     *
      * @param Records\Record[]     $records
      * @param ContainerInterface[] $containers
      * @param bool                 $validate
@@ -44,14 +59,11 @@ public static function withData(array $records = [], array $containers = [], boo
     }
 
     /**
-     * Returns Container instance with provided records.
-     *
-     * Adding new entries to container is still possible, but only
-     * using this instance's entry() method.
+     * Returns immutable Container instance with provided data.
      *
-     * Strict immutability can be ensured only when this instance is
-     * encapsulated and not passed to uncontrolled parts of application
-     * (including container itself).
+     * Adding new entries to this setup is still possible, but created
+     * container will not be affected and this method will create new
+     * container instance with those added entries.
      *
      * @return ContainerInterface
      */
@@ -61,8 +73,8 @@ public function container(): ContainerInterface
     }
 
     /**
-     * Returns Entry object able to configure Container's
-     * data slot for given name id.
+     * Returns Entry object able to add new data to container configuration
+     * for given identifier.
      *
      * @param string $name
      *
@@ -74,7 +86,7 @@ public function entry(string $name): Setup\Entry
     }
 
     /**
-     * Stores Records instantiated directly in container.
+     * Adds Record instances directly to container configuration.
      *
      * @param Records\Record[] $records Flat associative array of Record instances
      *

src/Setup/Entry.php

@@ -17,8 +17,8 @@
 
 
 /**
- * Write-only proxy with helper methods to instantiate and
- * set Record implementations for given Container name id.
+ * Write-only proxy with helper methods to instantiate and set
+ * Record implementations for given Container name identifier.
  */
 class Entry
 {
@@ -32,7 +32,7 @@ public function __construct(string $name, Collection $records)
     }
 
     /**
-     * Pushes given Record instance directly into Container's records
+     * Adds given Record instance directly into container records
      * using this instance's name property.
      *
      * @param Record $record
@@ -45,7 +45,7 @@ public function record(Record $record): void
     }
 
     /**
-     * Pushes ValueRecord with given value into Container's records.
+     * Adds ValueRecord with given value into container records.
      *
      * @see ValueRecord
      *
@@ -59,12 +59,12 @@ public function value($value): void
     }
 
     /**
-     * Pushes CallbackRecord with given callable into Container's records.
+     * Adds CallbackRecord with given callable into container records.
      * Callback receives ContainerInterface instance as parameter.
      *
      * @see CallbackRecord
      *
-     * @param callable $callback
+     * @param callable $callback function (ContainerInterface): mixed
      *
      * @throws Exception\InvalidIdException
      */
@@ -74,15 +74,15 @@ public function callback(callable $callback): void
     }
 
     /**
-     * Pushes ComposeRecord with given className and its constructor
-     * parameters given as Container id names. Each dependency has
-     * to be defined within collection (otherwise circular references
-     * cannot be avoided).
+     * Adds ComposeRecord to container records with given className
+     * and its constructor parameters given as Container id names.
+     * Each dependency has to be defined within collection (otherwise
+     * circular references cannot be avoided).
      *
-     * When dependency id equals this instance name it is not overwritten and
-     * circular dependency is not created - it is decorated instead.
-     * Now every class depending on decorated object will take product of this
-     * record as its dependency. Objects can be decorated multiple times.
+     * When dependency id equals this instance name it is not overwritten
+     * and circular dependency is not created - it is decorated instead.
+     * Now every class depending on decorated object will take product of
+     * this record as its dependency. Objects can be wrapped multiple times.
      *
      * @see ComposeRecord
      *
@@ -102,22 +102,32 @@ public function compose(string $className, string ...$dependencies): void
     }
 
     /**
-     * Pushes CreateMethodRecord with given method of container identified
-     * factory and its parameter values as container identifiers.
+     * Adds CreateMethodRecord to container records with given container
+     * identifier of factory class, factory method name and container
+     * identifiers of its parameters.
      *
      * @see CreateMethodRecord
      *
      * @param string $factoryId
      * @param string $method
-     * @param string ...$arguments Container identifiers of stored arguments
+     * @param string ...$arguments
      *
-     * @throws Exception\InvalidIdException | Exception\RecordNotFoundException
+     * @throws Exception\InvalidIdException
      */
     public function create(string $factoryId, string $method, string ...$arguments): void
     {
         $this->record(new Record\CreateMethodRecord($factoryId, $method, ...$arguments));
     }
 
+    /**
+     * Adds ContainerInterface instance as sub-container that may
+     * be accessed with current entry name prefix (entry name
+     * cannot contain prefix separator).
+     *
+     * @param ContainerInterface $container
+     *
+     * @throws Exception\InvalidIdException
+     */
     public function container(ContainerInterface $container)
     {
         $this->records->addContainer($this->name, $container);