some doc fixes

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

@@ -41,26 +41,26 @@ func cmdExamplePluginTx(c *cli.Context) error {
 	//Retrieve any flag results
 	exampleFlag := c.Bool("valid")
 
-	// Create a transaction object with flag results
-	// This object is responsible for passing on custom plugin information
+	// Create a transaction using the flag.
+	// The tx passes on custom information to the plugin
 	exampleTx := ExamplePluginTx{exampleFlag}
 
-	// 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.
+	// The tx is passed to the plugin in the form of
+	// a byte array. This is achieved by serializing the object using go-wire.
 	// Once received in the plugin, these exampleTxBytes are decoded back
-	// into the original object struct ExamplePluginTx
+	// into the original ExamplePluginTx struct
 	exampleTxBytes := wire.BinaryBytes(exampleTx)
 
 	// 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)
+	// Here exampleTxBytes is packaged in the `tx.Data` field of an AppTx,
+	// and passed on to the plugin through the following sequence:
+	//  - passed as `data` to `commands.AppTx` (cmd/commands/tx.go)
+	//  - set as the `tx.Data` field of an AppTx, which is then passed to commands.broadcastTx (cmd/commands/tx.go)
+	//  - the tx is broadcast to Tendermint, which runs it through app.CheckTx (app/app.go)
+	//  - after passing CheckTx, it will eventually be included in a block and run through app.DeliverTx (app/app.go)
+	//  - DeliverTx receives txBytes, which is the serialization of the full AppTx (app/app.go)
+	//  - Once deserialized, the tx is passed to `state.ExecTx` (state/execution.go)
+	//  - If the tx passes various checks, the `tx.Data` is forwarded as `txBytes` to `plugin.RunTx` (docs/guide/src/example-plugin/plugin.go)
+	//  - Finally, it deserialized back to the ExamplePluginTx
 	return commands.AppTx(c, "example-plugin", exampleTxBytes)
 }