Add Documentation

docs/Auto-Construction.md

@@ -0,0 +1,102 @@
+# Auto Construction
+
+The `PropertyAccessor` provides a way to construct composites based on
+properties with `@construct` annotations. This is used by the
+`AutoConstructTrait` to provide a virtual constructor.
+
+To specify a required parameter, use `@construct required`, to specify
+optional constructor parameter: `@construct optional` and the specify a
+property which will be built in a constructor, `@construct new`.
+
+You can also specify an optional constructor parameter which is built
+when not specified with `@construct optional new`.
+
+The order of parameters is: all required parameters, in the order the
+properties appear in the composite, followed by all optional parameters,
+again in the order of their properties in the composite.
+
+## Full example
+
+```php
+class MyAwesomeComposite
+{
+    use AutoConstructTrait;
+
+    /**
+     * @construct optional
+     * @var DataType
+     */
+    protected $a;
+
+    /**
+     * @construct required
+     * @var int
+     */
+    protected $b;
+
+    /**
+     * @construct optional new
+     * @var ArrayObject
+     */
+    protected $c;
+
+    /**
+     * @construct optional
+     * @var string
+     */
+    protected $d;
+
+    /**
+     * @construct new
+     * @var SomeThing
+     */
+    protected $e;
+
+    /**
+     * Nothing will happen with this
+     */
+    protected $f;
+}
+```
+
+This will create the following 'virtual' constructor:
+
+```php
+public function __construct
+(
+    int $b,
+    ?DataType $a = null,
+    ?ArrayObject $c = null,
+    ?string $d = null
+)
+{
+    $this->b = $b;
+
+    if ($a) $this->a = $a;
+    if ($c) $this->c = $c; else $this->c = new ArrayObject();
+    if ($d) $this->d = $d;
+
+    $this->e = new SomeThing();
+}
+```
+
+## Using your own constructor
+
+Often you still want to specify your own constructor logic. This is easy
+to do to, simply define your construct with whatever parameters you want
+and variadic parameters at the end, pass these to
+`AutoConstructTrait::autoBuild()` method and the rest will be taken
+care of!
+
+### Example
+
+```php
+public function __construct($f, ...$args)
+{
+    $this->autoBuild(...$args);
+
+    $this->f = doSomethingWith($f);
+}
+```
+
+

docs/Property-Access.md

@@ -0,0 +1,51 @@
+# Property Access
+
+There are three kinds of Property Accessor Services provided by this
+package:
+
++ `RawPropertyAccessor`
++ `PropertyAccessor`
++ `ConditionalPropertyAccessor`
+
+## Raw Property Accessor
+
+This provides direct access to a composite's properties, regardless of
+their visibility. This is typically useful for Factories which can be
+trusted to populate an entity with sensible data and need unencumbered
+access.
+
+This service is also used by the `AllReadableTrait` which allows all
+properties on a composite to be read, but none to be written. This is
+useful for objects which are immutable once constructed, especially as
+the `RawPropertyAccessor` does not need to read any annotations so you
+can skip some overhead there.
+
+## Property Accessor
+
+This provides access to all of a composite's properties again regardless
+of their visibility. The one difference is that data type requirements
+are enforced. That is, if a property has been declared with a certain
+datatype using the `@var` annotation, the `PropertyAccessor` will throw
+an exception if the provided data type is incorrect.
+
+### Casting
+
+In cases where a scalar data type has been declared, `PropertyAccessor`
+will accept object inputs if they can be casted using a `__toXXX()`
+method. For example, an object passed to a `string` property will have
+its `__toString()` method called and the value of that used. The same
+goes for `__toBoolean()` and `__toInteger()`.
+
+### Auto Constructing
+
+This service is used by the `AutoConstructTrait` for auto construction.
+See the [Auto Construction Documentation](Auto-Construction.md).
+
+## Conditional Property Accessor
+
+Like the `PropertyAccessor`, the `ConditionalPropertyAccessor` enforces
+required data types, with the addition of access rules. These can be set
+using the `@readable` and `@writable` annotations.
+
+This service is used by the `PropertyAccessTrait` which provides `__get`
+and `__set` magic methods.