ebuchman comments 2

docs/guide/plugin-design.md

@@ -64,6 +64,14 @@ and also to store arbitrary other information in the state.
 In this way, the functionality and state of a Basecoin-derived cryptocurrency can be greatly extended.
 One could imagine going so far as to implement the Ethereum Virtual Machine as a plugin!
 
+Any required plugin initialization should be constructed within `SetOption`.
+`SetOption` may be called during genesis of basecoin and can be used to set
+initial plugin parameters. Within genesis.json file entries are made in
+the format: "<plugin>/<key>", "<value>" Where <plugin> is the plugin name,
+and <key> and <value> are the strings passed into the plugin SetOption function. 
+This function is intended to be used to set plugin specific information such 
+as the plugin state.
+
 ## Examples
 
 To get started with plugins, see [the example-plugin tutorial](example-plugin.md).

docs/guide/src/example-plugin/cmd.go

@@ -41,12 +41,26 @@ func cmdExamplePluginTx(c *cli.Context) error {
 	//Retrieve any flag results
 	exampleFlag := c.Bool("valid")
 
-	//Create a transaction object with flag results
+	// Create a transaction object with flag results
+	// This object is responsible for passing on custom plugin information
 	exampleTx := ExamplePluginTx{exampleFlag}
 
-	//Encode transaction bytes
+	// The custom plugin object is passed to the plugin in the form of
+	// a byte array. This is achieved serializing the object using go-wire.
+	// Once received in the plugin, these exampleTxBytes are decoded back
+	// into the original object struct ExamplePluginTx
 	exampleTxBytes := wire.BinaryBytes(exampleTx)
 
-	//Send the transaction and return any errors
+	// Send the transaction and return any errors.
+	// Here exampleTxBytes will be passed on to the plugin through the
+	// following series of function calls:
+	//  - commands.AppTx as data (cmd/commands/tx.go)
+	//  - commands.broadcastTx as tx.Data (cmd/commands/tx.go)
+	//    - after being broadcast the Tendermint transaction
+	//      will be run through app.CheckTx, and if successful DeliverTx,
+	//      let's assume app.CheckTx passes
+	//  - app.DeliverTx serialized within txBytes as tx.Data (app/app.go)
+	//  - state.ExecTx as tx.Data (state/execution.go)
+	//  - plugin.RunTx as txBytes (docs/guide/src/example-plugin/plugin.go)
 	return commands.AppTx(c, "example-plugin", exampleTxBytes)
 }

docs/guide/src/example-plugin/plugin.go

@@ -13,10 +13,9 @@ import (
 // Plugin State Struct
 //   * Intended to store the current state of the plugin
 //     * This example contains a field which holds the execution count
-//   * Used by go-wire as the encoding/decoding struct to hold the plugin state
-//   * All fields must be exposed (for go-wire)
-//   * The state is stored within the KVStore using the key retrieved
-//     from the ExamplePlugin.StateKey() function
+//   * Serialized (by go-wire) and stored within the KVStore using the key retrieved
+//     from the ExamplePlugin.StateKey() function/
+//   * All fields must be exposed for serialization by external libs (here go-wire)
 type ExamplePluginState struct {
 	Counter int
 }
@@ -25,9 +24,8 @@ type ExamplePluginState struct {
 //   * Stores transaction-specific plugin-customized information
 //     * This example contains a dummy field 'Valid' intended to specify
 //       if the transaction is a valid and should proceed
-//   * Used by go-wire as the encoding/decoding struct to pass transaction
-//   * All fields must be exposed (for go-wire)
-//   * Passed through txBytes in the RunTx func.
+//   * Deserialized (by go-wire) from txBytes in ExamplePlugin.RunTx
+//   * All fields must be exposed for serialization by external libs (here go-wire)
 type ExamplePluginTx struct {
 	Valid bool
 }
@@ -42,10 +40,7 @@ type ExamplePlugin struct {
 //-----------------------------------------
 // Non-Mandatory Functions
 
-// Return a new example plugin pointer with a hard-coded name. Within other
-// plugin implementations may choose to include other initialization
-// information to populate custom fields of your Plugin struct in this example
-// named ExamplePlugin
+// Return a new ExamplePlugin pointer with a hard-coded name
 func NewExamplePlugin() *ExamplePlugin {
 	return &ExamplePlugin{
 		name: "example-plugin",
@@ -81,13 +76,12 @@ func (ep *ExamplePlugin) SetOption(store types.KVStore, key string, value string
 // Input fields:
 // - store types.KVStore
 //   - This term provides read/write capabilities to the merkelized data store
-//     which is accessible cross-plugin
+//     which holds the basecoin state and is accessible to all plugins
 // - ctx types.CallContext
 //   - The ctx contains the callers address, a pointer to the callers account,
 //     and an amount of coins sent with the transaction
 // - txBytes []byte
-//   - Used to send customized information from the basecoin
-//     application to your plugin
+//   - Used to send customized information to your plugin
 //
 // Other more complex plugins may have a variant on the process order within this
 // example including loading and saving multiple or variable states, or not