update documentation content

README.md

@@ -1,97 +1,27 @@
-# Snap Plugin Library for Go
+## Snap Plugin Library for Go
 
-This is a library for writing plugins for the [snap](https://github.com/intelsdi-x/snap) telemetry framework. The goal for this library is to make it super simple to write a plugin.
+A library for writing plugins in Go for the [Snap telemetry framework](https://github.com/intelsdi-x/snap) telemetry framework. 
 
-# Writing a plugin
+Snap has three different plugin types and for instructions on how to write a plugin check out the [collector](https://github.com/sarahjhh/snap-plugin-lib-go/blob/docs/examples/collector/README.md), processor, and publisher plugin docs.
 
-In order to write a plugin for snap, it is necessary to define some methods to satisfy the appropriate interfaces. The interface is slightly different depending on what type (collector, processor, or publisher) of plugin is being written. The interfaces are:
+Before writing any Snap plugins, check out the [Plugin Catalog](https://github.com/intelsdi-x/snap/blob/master/docs/PLUGIN_CATALOG.md) to see if any suit your needs. Also check the [plugin wishlist](https://github.com/intelsdi-x/snap/labels/plugin-wishlist) to see if anyone has already requested your desired plugin. If you do decide to write a plugin, open a new issue following the plugin wishlist guidelines and let us know you are working on one! 
 
 
-```go
-type Plugin interface {
-	GetConfigPolicy() (ConfigPolicy, error)
-}
+## Brief Overview of Snap Architecture
 
-// Collector is a plugin which is the source of new data in the Snap pipeline.
-type Collector interface {
-	Plugin
+Snap itself runs as a master daemon with the core functionality that may load and unload plugin processes via either CLI or HTTP APIs.
 
-	GetMetricTypes(Config) ([]Metric, error)
-	CollectMetrics([]Metric) ([]Metric, error)
-}
+A Snap plugin is a program, or a set of functions or services, written in Go or any language; that may seamlessly integrate with Snap as executables.
 
-// Processor is a plugin which filters, agregates, or decorates data in the
-// Snap pipeline.
-type Processor interface {
-	Plugin
+Communication between Snap and plugins uses the gRPC protocol. [gRPC](http://www.grpc.io/docs/) uses HTTP2, which improves performance versus HTTP1, and uses [protocol buffers](https://developers.google.com/protocol-buffers/) for simplicity, performance, and smaller memory size.
 
-	Process([]Metric, Config) ([]Metric, error)
-}
 
-// Publisher is a sink in the Snap pipeline.  It publishes data into another
-// System, completing a Workflow path.
-type Publisher interface {
-	Plugin
+## Snap Plugin Go Library Implementation Files
+You will find all the library packages in the [v1/plugin folder](https://github.com/intelsdi-x/snap-plugin-lib-go/tree/master/v1/plugin).
+The [rpc folder](https://github.com/intelsdi-x/snap-plugin-lib-go/tree/master/v1/plugin/rpc) contents are auto-generated and should not be modified by anyone.
 
-	Publish([]Metric, Config) error
-}
-```
+## Snap Plugin Go Library Examples
+You will find [example plugins](https://github.com/intelsdi-x/snap-plugin-lib-go/tree/master/examples) that cover the basics for writing collector, processor, and publisher plugins in the examples folder.
 
-# Starting a plugin
 
-After implementing a type that satisfies one of {collector, processor, publisher} interfaces, all that is left to do is a call the appropriate plugin.StartX() with your plugin specific options. That could be as simple as:
-
-```go
-	plugin.StartCollector(rand.RandCollector{}, pluginName, pluginVersion)
-```
-
-## Meta options
-
-The available options are defined in [plugin/meta.go](https://github.com/intelsdi-x/snap-plugin-lib-go/tree/master/v/1/plugin/meta.go). You can use some or none of the options. The options with definitions/explanations are below:
-
-```go
-// ConcurrencyCount is the max number of concurrent calls the plugin
-// should take.  For example:
-// If there are 5 tasks using the plugin and its concurrency count is 2,
-// snapd will keep 3 plugin instances running.
-// ConcurrencyCount overwrites the default (5) for a Meta's ConcurrencyCount.
-func ConcurrencyCount(cc int) MetaOpt {
-}
-
-// Exclusive == true results in a single instance of the plugin running
-// regardless of the number of tasks using the plugin.
-// Exclusive overwrites the default (false) for a Meta's Exclusive key.
-func Exclusive(e bool) MetaOpt {
-}
-
-// Unsecure results in unencrypted communication with this plugin.
-// Unsecure overwrites the default (false) for a Meta's Unsecure key.
-func Unsecure(e bool) MetaOpt {
-}
-
-// RoutingStrategy will override the routing strategy this plugin requires.
-// The default routing strategy is Least Recently Used.
-// RoutingStrategy overwrites the default (LRU) for a Meta's RoutingStrategy.
-func RoutingStrategy(r router) MetaOpt {
-}
-
-// CacheTTL will override the default cache TTL for the this plugin. snapd
-// caches metrics on the daemon side for a default of 500ms.
-// CacheTTL overwrites the default (500ms) for a Meta's CacheTTL.
-func CacheTTL(t time.Duration) MetaOpt {
-}
-```
-
-An example of what using all of them would look like:
-
-```go
-	plugin.StartCollector(mypackage.Mytype{},
-				pluginName,
-				pluginVersion,
-				plugin.ConcurrencyCount(a),
-				plugin.Exclusive(b),
-				plugin.Unsecure(c),
-				plugin.RoutingStrategy(d),
-				plugin.CacheTTL(e))
-```
 

examples/collector/README.md

@@ -0,0 +1,135 @@
+
+## Snap Plugin Go Library: Collector Plugin Example
+Here you will find an example plugin that cover the basics for writing a collector plugin.
+
+## Plugin Naming, Files, and Directory
+For your collector plugin, create a new repository and name your plugin project using the following format:
+
+>snap-plugin-[plugin-type]-[plugin-name]
+
+For example: 
+>snap-plugin-collector-rand
+
+
+Example files and directory structure:  
+```
+snap-plugin-[plugin-type]-[plugin-name]
+ |--[plugin-name]
+  |--[plugin-name].go  
+  |--[plugin-name]_test.go  
+ |--main.go
+```
+
+For example:
+```
+snap-plugin-collector-rand
+ |--rand
+  |--rand.go  
+  |--rand_test.go  
+ |--main.go
+```
+
+* The main file (for example `main.go`) allows each plugin to be a stand-alone binary executable. The main file will include: pluginName and pluginVersion.
+* The [plugin-name] folder (for example `rand`) will include all files to implement the appropriate interface methods
+* Your [plugin-name] folder  will also include your test files.
+
+
+
+## Interface Methods
+
+In order to write a plugin for Snap, it is necessary to define a few methods to satisfy the appropriate interfaces. These interfaces must be defined for a collector plugin:
+
+
+```go
+// Plugin is an interface shared by all plugins and must implemented by each plugin to communicate with Snap.
+type Plugin interface {
+	GetConfigPolicy() (ConfigPolicy, error)
+}
+
+// Collector is a plugin which is the source of new data in the Snap pipeline.
+type Collector interface {
+	Plugin
+
+	GetMetricTypes(Config) ([]Metric, error)
+	CollectMetrics([]Metric) ([]Metric, error)
+}
+```
+The interface is slightly different depending on what type (collector, processor, or publisher) of plugin is being written. Please see other plugin types for more details.
+
+
+
+## Starting a plugin
+
+After implementing a type that satisfies one of {collector, processor, publisher} interfaces, all that is left to do is a call the appropriate plugin.StartX() with your plugin specific options. That could be as simple as:
+
+```go
+	plugin.StartCollector(rand.RandCollector{}, pluginName, pluginVersion)
+```
+
+### Meta options
+
+The available options are defined in [plugin/meta.go](https://github.com/intelsdi-x/snap-plugin-lib-go/tree/master/v/1/plugin/meta.go). You can use some or none of the options. The options with definitions/explanations are below:
+
+```go
+// ConcurrencyCount is the max number of concurrent calls the plugin
+// should take.  For example:
+// If there are 5 tasks using the plugin and its concurrency count is 2,
+// snapd will keep 3 plugin instances running.
+// ConcurrencyCount overwrites the default (5) for a Meta's ConcurrencyCount.
+func ConcurrencyCount(cc int) MetaOpt {
+}
+
+// Exclusive == true results in a single instance of the plugin running
+// regardless of the number of tasks using the plugin.
+// Exclusive overwrites the default (false) for a Meta's Exclusive key.
+func Exclusive(e bool) MetaOpt {
+}
+
+// Unsecure results in unencrypted communication with this plugin.
+// Unsecure overwrites the default (false) for a Meta's Unsecure key.
+func Unsecure(e bool) MetaOpt {
+}
+
+// RoutingStrategy will override the routing strategy this plugin requires.
+// The default routing strategy is Least Recently Used.
+// RoutingStrategy overwrites the default (LRU) for a Meta's RoutingStrategy.
+func RoutingStrategy(r router) MetaOpt {
+}
+
+// CacheTTL will override the default cache TTL for the this plugin. snapd
+// caches metrics on the daemon side for a default of 500ms.
+// CacheTTL overwrites the default (500ms) for a Meta's CacheTTL.
+func CacheTTL(t time.Duration) MetaOpt {
+}
+```
+
+An example of what using all of them would look like:
+
+```go
+	plugin.StartCollector(mypackage.Mytype{},
+				pluginName,
+				pluginVersion,
+				plugin.ConcurrencyCount(a),
+				plugin.Exclusive(b),
+				plugin.Unsecure(c),
+				plugin.RoutingStrategy(d),
+				plugin.CacheTTL(e))
+```
+
+## Testing
+You should specifiy the test size (either small, medium, or large) with the specified build tag `// +build test-size`. The default testing will run all size tests if the build tag is not specified.
+
+
+For example if you want to run only small tests:
+```
+// +build small
+// you must include at least one line between the build tag and the package name.
+package rand
+```
+
+For example if you want to run small and medium tests:
+```
+// +build small medium
+
+package rand
+```

examples/collector/rand/rand.go

@@ -60,7 +60,13 @@ func init() {
 type RandCollector struct {
 }
 
-// CollectMetrics collects metrics for testing
+/*  CollectMetrics collects metrics for testing.
+
+	CollectMetrics() will be called by Snap when a task that collects one of the metrics returned from this plugins
+	GetMetricTypes() is started. The input will include a slice of all the metric types being collected.
+
+	The output is the collected metrics as plugin.Metric and an error.
+*/
 func (RandCollector) CollectMetrics(mts []plugin.Metric) ([]plugin.Metric, error) {
 	metrics := []plugin.Metric{}
 	for idx, mt := range mts {
@@ -96,7 +102,15 @@ func (RandCollector) CollectMetrics(mts []plugin.Metric) ([]plugin.Metric, error
 	return metrics, nil
 }
 
-//GetMetricTypes returns metric types for testing
+/*
+	GetMetricTypes returns metric types for testing.
+	GetMetricTypes() will be called when your plugin is loaded in order to populate the metric catalog(where snaps stores all
+	available metrics).
+
+	Config info is passed in. This config information would come from global config snap settings.
+
+	The metrics returned will be advertised to users who list all the metrics and will become targetable by tasks.
+*/
 func (RandCollector) GetMetricTypes(cfg plugin.Config) ([]plugin.Metric, error) {
 	metrics := []plugin.Metric{}
 
@@ -112,7 +126,13 @@ func (RandCollector) GetMetricTypes(cfg plugin.Config) ([]plugin.Metric, error)
 	return metrics, nil
 }
 
-//GetConfigPolicy returns a ConfigPolicyTree for testing
+/*
+	GetConfigPolicy() returns the configPolicy for your plugin.
+
+	A config policy is how users can provide configuration info to
+	plugin. Here you define what sorts of config info your plugin
+	needs and/or requires.
+*/
 func (RandCollector) GetConfigPolicy() (plugin.ConfigPolicy, error) {
 	policy := plugin.NewConfigPolicy()
 	ir, _ := plugin.NewIntegerRule(