some doc fixes

docs/guide/basecoin-design.md

@@ -55,7 +55,7 @@ type TxInput struct {
   Coins     Coins            `json:"coins"`     //
   Sequence  int              `json:"sequence"`  // Must be 1 greater than the last committed TxInput
   Signature crypto.Signature `json:"signature"` // Depends on the PubKey type and the whole Tx
-  PubKey    crypto.PubKey    `json:"pub_key"`   // Is present if Sequence == 0
+  PubKey    crypto.PubKey    `json:"pub_key"`   // Is present iff Sequence == 0
 }
 
 type TxOutput struct {

docs/guide/plugin-design.md

@@ -67,8 +67,8 @@ One could imagine going so far as to implement the Ethereum Virtual Machine as a
 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,
+the format: `"<plugin>/<key>", "<value>"`, where `<plugin>` is the plugin name,
-and <key> and <value> are the strings passed into the plugin SetOption function. 
+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.
 

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
+	// Create a transaction using the flag.
-	// This object is responsible for passing on custom plugin information
+	// 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
+	// The tx is passed to the plugin in the form of
-	// a byte array. This is achieved serializing the object using go-wire.
+	// 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
+	// Here exampleTxBytes is packaged in the `tx.Data` field of an AppTx,
-	// following series of function calls:
+	// and passed on to the plugin through the following sequence:
-	//  - commands.AppTx as data (cmd/commands/tx.go)
+	//  - passed as `data` to `commands.AppTx` (cmd/commands/tx.go)
-	//  - commands.broadcastTx as tx.Data (cmd/commands/tx.go)
+	//  - set as the `tx.Data` field of an AppTx, which is then passed to commands.broadcastTx (cmd/commands/tx.go)
-	//    - after being broadcast the Tendermint transaction
+	//  - the tx is broadcast to Tendermint, which runs it through app.CheckTx (app/app.go)
-	//      will be run through app.CheckTx, and if successful DeliverTx,
+	//  - after passing CheckTx, it will eventually be included in a block and run through app.DeliverTx (app/app.go)
-	//      let's assume app.CheckTx passes
+	//  - DeliverTx receives txBytes, which is the serialization of the full AppTx (app/app.go)
-	//  - app.DeliverTx serialized within txBytes as tx.Data (app/app.go)
+	//  - Once deserialized, the tx is passed to `state.ExecTx` (state/execution.go)
-	//  - state.ExecTx as tx.Data (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)
-	//  - plugin.RunTx as txBytes (docs/guide/src/example-plugin/plugin.go)
+	//  - Finally, it deserialized back to the ExamplePluginTx
 	return commands.AppTx(c, "example-plugin", exampleTxBytes)
 }