Update services documentation

Sources/SwiftKit/Services/Decorator.swift

@@ -10,10 +10,24 @@ import Foundation
 
 /**
  This class can be inherited by any class that wraps another
- class that implements a protocol that the class implements.
+ class that implements the same protocol.
  
- This can be used to implement service decorators to use the
- decorator pattern to compose functionality.
+ This can be used to implement the "decorator pattern" which
+ lets you compose functionality without inheritance.
+ 
+ For instance, say that you have an external movie api, from
+ which you fetch moves. A `MovieService` protocol could then
+ be used to generally describe how to fetch movies, while an
+ `ApiMovieService` class could provide a pure implementation
+ of the protocol, by communicating directly with the api. In
+ order to add things like caching, offline support etc. your
+ app could now implement other `MovieService` implementation
+ classes, that instead of inheriting `ApiMovieService` apply
+ aisolated features on top of any `MovieService`.
+ 
+ This gives you a more modular way of composing features. It
+ lets you avoid long dependency chains, makes it easier when
+ unit testing etc.
 */
 open class Decorator<T> {
     

Sources/SwiftKit/Services/EmailValidator.swift

@@ -8,6 +8,9 @@
 
 import Foundation
 
+/**
+ This `Validator` can be used to validate e-mail addresses.
+ */
 public class EmailValidator: Validator {
     
     public init() {}

Sources/SwiftKit/Services/MultiProxy.swift

@@ -14,9 +14,6 @@ import Foundation
  
  This can be a useful approach when an operation or any kind
  of action could be performed by several unrelated receivers.
- 
- This approach should not be used when a certain action must
- be performed in a certain way.
  */
 open class MultiProxy<T> {