docs: Expand processor/provider docs (#98)

* expand processor/provider doc

* update wording

* grammar

* Update docs/getting_started.md

---------

Co-authored-by: Talley Lambert <[email protected]>

docs/getting_started.md

@@ -14,7 +14,7 @@ in `in-n-out` are *providers* and *processors*.
 
 A [`Store`][in_n_out.Store] is a collection of providers and processors.
 You will usually begin by creating a `Store` instance to manage your providers and
-processors.
+processors. More than one provider/processor can be registered per type.
 
 ```python
 from in_n_out import Store
@@ -38,7 +38,7 @@ store = Store.get_store('my-store')
 ## Registering Providers
 
 Dependency inject works by providing an instance of a type to a function
-or method that requires it.  Let's being by declaring some type that will be
+or method that requires it.  Let's begin by declaring some type that will be
 important to our application:
 
 ```python
@@ -104,6 +104,14 @@ get_things_name = store.inject(get_things_name)
 print(get_things_name())  # prints "Thing"
 ```
 
+!!!note "multiple providers"
+    In the case that more one provider has been registered for a given type. The store will
+    iterate through all providers registered for the required type (ordered by [weight](#weights-and-provider-priority)), stopping at the first one that returns an object that
+    is not `None` .
+
+    Providers should return `None` if it is not able to provide the requested object as
+    this allows `in-n-out` to continue iterating through any other registered providers.
+
 !!!tip "decorators"
     As with registration functions, we can use `Store.inject` as a decorator:
 
@@ -130,8 +138,9 @@ give_me_a_string()
 
 ### Weights and provider priority
 
-You may register multiple providers for the same type.  In this case, the
-store will use the provider with the highest *weight*.
+When registering multiple providers for the same type, you can use the
+`weight` parameter to specify the order in which providers should be tried.
+(Providers with a higher weight will be tried first.)
 
 ```python
 def give_me_another_thing() -> Thing:
@@ -193,6 +202,27 @@ get_things_name(Thing('Bob'))  # prints "Hello, Bob!"  (and still returns "Bob")
     did above. Or, at the very least, we wouldn't inject processors into a
     function that returned `str`.
 
+### Multiple processors
+
+As with providers, you may register multiple processors per return type, and the
+`weight` parameter will be used to specify the order in which they should be run,
+with higher weights running first.
+
+The default behavior is to call all processors that have been registered for a
+given type. However, you can use `first_processor_only=True` when
+injecting processors with [`Store.inject_processors`][in_n_out.Store.inject_processors]
+or when manually calling [`Store.process`][in_n_out.Store.process]
+to specify that only the first processor should be used.
+
+Note that all processors recieve the same object (the return value of the
+function being injected into).  They are *not* chained, and any value returned
+by a processor will be ignored.
+
+If an unhandled exception is raised while executing a processor, it will be caught
+and a warning will be emitted.  If you would prefer to handle raised
+exceptions yourself, you can pass `raise_exception=True` to
+[`Store.inject_processors`][in_n_out.Store.inject_processors].
+
 ## Real world example
 
 Let's look at a more realistic example.