doc updates

Signed-off-by: Jeff Lindsay <[email protected]>

Author: progrium

README.md

@@ -11,33 +11,25 @@ A component-oriented approach to building Golang applications
 ## Concept
 
 We want to see a world with great "building blocks" where you can quickly build
-whatever you want. Simple and composable is not enough, they need to integrate
-and hook into each other.
+whatever you want. Traditional "composability" is not enough, they need to
+integrate and hook into each other.
 
-This library provides the core mechanisms needed to build out a component
-architecture for your applications that also extend into an ecosystem of reusable
-components.
+This library provides the core mechanisms needed to build out a modular and
+extensible component architecture for your application, which also extend into
+an ecosystem of "drop-in" reusable components.
 
 There are two parts to this package that are designed to work with each other:
 
  * An object registry for interface-based extension points and dependency injection
  * A configuration API for settings, disabling objects, and picking interface backends
 
-The API and even core functionality alone doesn't imply how we build components
-with this tool. We can formalize much of this in a proper framework project once
-we've determined the conventions. Until then, we can focus on examples and our
-small but growing library of [standard components](https://github.com/gliderlabs/stdcom).
-
-In the end, this package helps facilitates structuring Go programs into modular and
-extensible components that become much more drop-in building blocks than
-the usual Go package.
-
 ## Example application
 
 See the [example wiki app repo](https://github.com/gl-prototypes/wiki).
 
-By building out [reusable components](https://github.com/gliderlabs/stdcom), a simple wiki with GitHub authentication
-could be put together in ~200 lines of Go as a single component.
+After building out [reusable components](https://github.com/gliderlabs/stdcom),
+a simple wiki with GitHub authentication could be put together in ~200 lines of
+Go as a single component.
 
 ## Using com
 

com.go

@@ -1,7 +1,7 @@
-// Package com is the user-facing interface to the object registry. Since
+// Package com is a user-facing interface to the object registry. Since
 // the only part of the API you need to use is Register, the rest of the API
-// for interacting with an object registry is in its own package. This is used
-// by other tooling building around com, for example the config subpackage.
+// for interacting with an object registry is in its own subpackage. This is used
+// by other tooling built around com, for example the config subpackage.
 //
 // When you register an object, it will populate fields based on the com struct
 // tags used on them. The object will then also be used to populate fields
@@ -14,14 +14,19 @@
 //  }
 //
 // In the above example component, it has fields with all three possible struct
-// tags. Singleton will pick the first object in the registry that implements
-// that interface. You can also use pointers to concrete types, for example to
-// other components. Extpoint is going to be a slice of all objects in the
-// registry that implement that interface. Config is not populated, but is allowed
-// to be populated via the registry API. If you're using the config package, it
-// will do this for you and populate it based on configuration. In this case,
-// the key would be "DB" and the value could be the name of any registered
-// component that implements api.Store.
+// tags:
+//
+// Singleton will pick the first object in the registry that implements that
+// interface. You can also use pointers to concrete types, for example to other
+// component types.
+//
+// Extpoint is going to be a slice of all objects in the registry that implement
+// that interface.
+//
+// Config is not populated, but is allowed to be populated via the registry API.
+// If you're using the config package, it will do this for you and populate it
+// based on configuration. In this case, the key would be "DB" and the value
+// could be the name of any registered component that implements api.Store.
 package com
 
 import "github.com/gliderlabs/com/objects"

objects/objects.go

@@ -26,6 +26,7 @@ type Object struct {
 	reflectValue reflect.Value
 }
 
+// New creates a new Object by value and name
 func New(v interface{}, name string) *Object {
 	return &Object{Value: v, Name: name}
 }