docs updates for property types, etc.

docs/entity.md

@@ -1,6 +1,6 @@
 ## Entity
 
-Entity is a data crate which, basically, contains data for one table row. Each entity has to implement `Nextras\Orm\Entity\IEntity` interface. Orm has predefined class `Nextras\Orm\Entity\Entity`, which implements the interface and provides other useful features.
+Entity is a data crate which, basically, contains data for one table row. Each entity has to implement `Nextras\Orm\Entity\IEntity` interface. Orm contains predefined `Nextras\Orm\Entity\Entity` class; it implements the interface and provides other useful features.
 
 Data is accessible through properties. You have to annotate all properties that should be available. Properties are defined by Phpdoc annotations. Let's start with a basic entity:
 
@@ -23,13 +23,18 @@ enum AdminLevel: int {
 }
 ```
 
-Phpdoc property definition consists of its type and name. If you would like to use read-only property, define it with `@property-read` annotation; such annotation is useful to define properties which are based on values of other properties. Properties could be optional/nullable; to do that, just provide another type - `null` or you could use it by prefixing the type name with a question mark - `?string`.
+Phpdoc property definition consists of its type and name. If you would like to use read-only property, define it with `@property-read` annotation; such annotation is useful to define properties that are virtual (calculated; e.g. based on values of other properties). Properties could be nullable; to do that, just provide another type - `|null` or prefix by question mark - `?string`.
 
-If you put some value into the property, the value will be validated by property type annotation. Type casting is performed if it is possible and safe. Supported types are `null`, `string`, `int`, `float`, `array`, `mixed`, enum (backed) types and object types. Validation is provided on all properties, except for properties defined with property wrapper - in that case validation is responsibility of the property wrapper. PHP 8.1 enums are validated and their backed value is used for the storage layer.
+If you put some value into the property, the value will be validated against the defined type. Type casting is performed if applicable and safe. Supported types are `null`, `string`, `int`, `float`, `array`, `mixed`, enum (int/string backed) and object types.
 
-Nextras Orm also provides enhanced support for date time handling. However, only "safe" `DateTimeImmutable` instances are supported as a property type. You may put a common `DateTime` instance as a value, but it will be automatically converted to DateTimeImmutable. Also, auto date string conversion is supported.
+- Validation is provided on all properties, except for properties defined with a property wrapper - in that case validation is a responsibility of the property wrapper.
+- PHP 8.1 enums are validated as expected; Enum's backed value is used for the storage layer;
+- Array values are validated only to be an array, i.e. array shapes are not checked in the runtime (use PHPStan to check it during development);
+- Simple object values are validated only to be an object, i.e. object shapes are not checked in the runtime (use PHPStan to check it during development);
 
-"Property access" is the easiest way to work with the data, although such feature is not defined in `IEntity` interface. To conform to the interface, you must use "method access": `getValue()` method for reading, `setValue()` method for writing, `hasValue()`, etc. There is a special `getRawValue()` method, which returns a raw representation of the value. The raw representation is basically the stored value (a primary key for relationship property).
+Nextras Orm provides enhanced support for date time handling. However, only "safe" `DateTimeImmutable` instances are supported as a property type. You may put a common `DateTime` instance as a value, but it will be automatically converted to DateTimeImmutable. Also, auto date string conversion is supported.
+
+Property access is the easiest way to work with the data; this feature is not defined in `IEntity` interface, but is provided by abstract `Nextras\Orm\Entity\AbstractEntity` implementation. To use only the interface, call `getValue()` method for reading, `setValue()` method for writing, `hasValue()`, etc. There is a special `getRawValue()` method, which returns a raw representation of the value. The raw representation is basically the stored value (a primary key for relationship property).
 
 ```php
 $member = new Member();
@@ -47,9 +52,9 @@ echo $member->hasValue('web') ? 'has web' : '-';
 $member->isPersisted(); // false
 ```
 
-Attaching entities to the repository lets Orm know about your entities. Attaching to a repository runs the required dependencies injection into your entity (through inject property annotations or inject methods). If you need some dependency before attaching entity to the repository, feel free to pass the dependency via the constructor, which is by default empty.
+Attaching entities to the repository lets Orm know about your entities. Attaching to a repository runs the optional dependencies injection into your entity (see later). If you need a dependency before attaching entity to the repository, you can pass the dependency via entity's constructor, which is by default available to be inherited.
 
-Each entity can be created "manually". Entities can be simply connected together. Let's see an example:
+Each entity can be created manually. Entities can be simply connected together. Let's see an example:
 
 ```php
 $author = new Author();
@@ -105,7 +110,7 @@ Each property can be annotated with a modifier. Modifiers are optional and provi
 #### `{primary}` and `{primary-proxy}`
 
 Each entity has to have defined the `$id` property.
-By default, the `$id` property is the only primary key of the entity; the `$id` property is defined in `Nextras\Orm\Entity\Entity` class, but it is not marked as primary, because this is the default behavior, which can be changed by the `{primary}` modifier. By adding the modifier to property, you mark it as the new primary key. You can use the modifier multiple times to create a composite primary key. If the modifier is applied to a relationship property, the relationship's primary key is automatically used.
+By default, the `$id` property is the only primary key of the entity; the `$id` property is defined in the base `Nextras\Orm\Entity\Entity` class, but it is not marked as primary, because this is the default behavior, which can be changed by the `{primary}` modifier. By adding the modifier to property, you mark it as the new primary key. You can use the modifier multiple times to create a composite primary key. If the modifier is applied to a relationship property, the relationship's foreign key is automatically used.
 
 ```php
 /**
@@ -117,9 +122,9 @@ class Tag extends Nextras\Orm\Entity\Entity
 }
 
 /**
- * @property mixed  $id        {primary-proxy}
- * @property Tag    $tag       {m:1 Tag::$followers} {primary}
- * @property User   $follower  {m:1 User::$followedTags} {primary}
+ * @property array{Tag, User} $id       {primary-proxy}
+ * @property Tag              $tag      {m:1 Tag::$followers} {primary}
+ * @property User             $follower {m:1 User::$followedTags} {primary}
  */
 class TagFollower extends Nextras\Orm\Entity\Entity
 {