improve documentation

docs/attributes.md

@@ -1,17 +1,18 @@
 # Injection via attributes
 
 Rather than defining injection via `$di->params`, `$di->setters`, `$di->values` or `$di->types`, you can also annotate 
-parameters using the native attributes available from PHP 8.0.
+parameters using the [native attributes available from PHP 8.0](https://www.php.net/manual/en/language.attributes.overview.php).
 
 The advantage would be that you have the injection decisions included in the class itself, keeping it all 
-together. Moreover, it reduces the size of the construction of your container, even if you have separated it with 
-many `ContainerConfigInterface` instances.
+together. Moreover, when your application grows, the length of your code constructing the container might grow to such size
+that maintaining it becomes a problem. This might even be the case when you have separated it with `ContainerConfigInterface` instances.
+With attributes such a problem does not exist.
 
 For now, only constructor parameters can be annotated.
 
 ## Service Attribute
 
-If the parameter is annotated with the `#[Service]` attribute, you define that a service should be injected. 
+If a parameter is annotated with the `#[Service]` attribute, you define that a service should be injected. 
 
 For example, look at the following class; the `$foo` constructor parameter has such an annotation:
 
@@ -81,18 +82,18 @@ class Example
 }
 ```
 
-The _Container_ will inject a new instance `Foo::class` for `$foo`. It is basically the same as if you would write the following:
+The _Container_ will inject the value `foo.value` for `$foo`. It is basically the same as if you would write the following:
 
 ```php
 $di->params['Example']['foo'] = $di->lazyValue('foo.value');
 ```
 
 ## Custom Attributes
 
-It is also possible to create your attribute. All you have to do is create a class using [the native PHP 8.0 attribute
-annotation](https://www.php.net/manual/en/language.attributes.overview.php), and it has to implement the `Aura\Di\Attribute\AnnotatedInjectInterface` class.
+It is also possible to create your own custom attribute. All you have to do is create a class using [the native PHP 8.0 attribute
+syntax](https://www.php.net/manual/en/language.attributes.syntax.php). On top, it has to implement the `Aura\Di\Attribute\AnnotatedInjectInterface` class.
 
-Suppose you want to inject a string coming from the `ConfigBag` object below, into other classes.
+Suppose you want to inject a config key coming from the `ConfigBag` object below, into other classes.
 
 ```php
 namespace MyApp;
@@ -170,10 +171,10 @@ $di->params['Example']['foo'] = $di->lazyGetCall('config', 'get', 'foo');
 
 ## Overwriting attributes
 
-When you define an annotation and an injection via code, the injection via code has precedence over the annotation.
+When you define both an annotation and an injection via code, the injection via code has precedence over the annotation.
 
-Using the last example of the custom attribute, the following code will overwrite the `#[Config('foo')]` annotation,
-and hence inject the value `"bravo"` and not `"bar"`.
+Using the last example of the custom attribute, the following code will overwrite the `#[Config('foo')]` annotation on
+the `$foo` constructor parameter, and hence inject the value `"bravo"` and not `"bar"`.
 
 ```php
 $di->set('config', new ConfigBag(['foo' => 'bar', 'alpha' => 'bravo']));

docs/migrating.md

@@ -18,10 +18,10 @@ new Container(new InjectionFactory(new Resolver(new Reflector())));
 new Container(new Resolver(new Reflector()));
 ```
 
-### Object interface changes
+### API changes
 
-There a few API changes in the objects. They probably do not have consequences for  client libraries as they were not
-exposed classes.
+There a few API changes in the objects. They probably do not have consequences for client libraries as they were not
+exposed publicly, but the changes are listed below nonetheless.
 
 - The `InjectionFactory` now has no dependencies. The `Resolver` is not injected anymore and the `getResolver()` and `newInstance()` methods have been removed.
 - The `LazyInterface` now requires a `Resolver` to be passed to `__invoke`. Its implementations therefore also have different constructor signatures.