Improve docs

Author: Maxim Bovtunov

container.go

@@ -48,7 +48,7 @@ func (c *Container) Extract(target interface{}, options ...ExtractOption) (err e
 	return c.container.Extract(params)
 }
 
-// Cleanup
+// Cleanup cleanup container.
 func (c *Container) Cleanup() {
 	c.container.Cleanup()
 }

options.go

@@ -11,44 +11,34 @@ type Option interface {
 
 // Provide returns container option that explains how to create an instance of a type inside a container.
 //
-// The first argument is the provider. The provider can be constructor function, a pointer to a structure (or just
-// structure) or everything else. There are some differences between these providers.
-//
-// A constructor function is a function that creates an instance of the required type. It can take an unlimited
-// number of arguments needed to create an instance - the first returned value.
+// The first argument is the constructor function. A constructor is a function that creates an instance of the required
+// type. It can take an unlimited number of arguments needed to create an instance - the first returned value.
 //
 //   func NewServer(mux *http.ServeMux) *http.Server {
 //     return &http.Server{
 //       Handle: mux,
 //     }
 //   }
 //
-// Optionally, you can return a initializing error.
+// Optionally, you can return a cleanup function and initializing error.
 //
-//   func NewServer(mux *http.ServeMux) (*http.Server, err error) {
+//   func NewServer(mux *http.ServeMux) (*http.Server, cleanup func(), err error) {
 //     if time.Now().Day = 1 {
-//       return nil, errors.New("the server is down on the first day of a month")
+//       return nil, nil, errors.New("the server is down on the first day of a month")
 //     }
-//     return &http.Server{
+//
+//     server := &http.Server{
 //       Handler: mux,
 //     }
-//   }
-//
-// Other function signatures will cause error.
 //
-// For advanced providing use inject.dependencyProvider.
-//
-//   type AdminServerProvider struct {
-//     inject.dependencyProvider
+//     cleanup := func() {
+//       _ = server.Close()
+//     }
 //
-//     AdminMux http.Handler `inject:"admin"` // use named definition
+//     return &server, cleanup, nil
 //   }
 //
-//   func (p *AdminServerProvider) Provide() *http.Server {
-//     return &http.Server{
-//       Handler: p.AdminMux,
-//     }
-//   }
+// Other function signatures will cause error.
 func Provide(provider interface{}, options ...ProvideOption) Option {
 	return option(func(container *Container) {
 		var po = di.ProvideParams{
@@ -89,7 +79,7 @@ func Bundle(options ...Option) Option {
 	})
 }
 
-// ProvideOption modifies default provide behavior. See inject.WithName(), inject.As(), inject.Exported().
+// ProvideOption modifies default provide behavior. See inject.WithName(), inject.As(), inject.Prototype().
 type ProvideOption interface {
 	apply(params *di.ProvideParams)
 }
@@ -106,8 +96,8 @@ func WithName(name string) ProvideOption {
 	})
 }
 
-// As specifies interfaces that implement provider instance. Provide with As() automatically checks that instance interfaces
-// interface and creates slice group with it.
+// As specifies interfaces that implement provider instance. Provide with As() automatically checks that constructor
+// result implements interface and creates slice group with it.
 //
 //   Provide(&http.ServerMux{}, inject.As(new(http.Handler)))
 //
@@ -123,14 +113,32 @@ func As(ifaces ...interface{}) ProvideOption {
 	})
 }
 
-// Prototype
+// Prototype modifies Provide() behavior. By default, each type resolves as a singleton. This option sets that
+// each type resolving creates a new instance of the type.
+//
+//   Provide(&http.Server{], inject.Prototype())
+//
+//   var server1 *http.Server
+//   container.Extract(&server1, &server1)
+//
+//
 func Prototype() ProvideOption {
 	return provideOption(func(provider *di.ProvideParams) {
 		provider.IsPrototype = true
 	})
 }
 
-// Parameters
+// ParameterBag is a provider parameter bag. It stores a construction parameters.
+//
+//   inject.Provide(NewServer, inject.ParameterBag{
+//     "addr": ":8080",
+//   })
+//
+//   NewServer(pb inject.ParameterBag) *http.Server {
+//     return &http.Server{
+//       Addr: pb.RequireString("addr"),
+//     }
+//   }
 type ParameterBag map[string]interface{}
 
 func (p ParameterBag) apply(provider *di.ProvideParams) {