modules/coin/rest: incorporated feedback from @ebuchman

modules/roles/rest/handlers.go

@@ -16,17 +16,25 @@ import (
 	"github.com/tendermint/tmlibs/common"
 )
 
+// RoleInput encapsulates the fields needed to create a role
 type RoleInput struct {
+	// Role is a hex encoded string of the role name
+	// for example, instead of "role" as the name, its
+	// hex encoded version "726f6c65".
 	Role string `json:"role" validate:"required,min=2"`
 
 	MinimumSigners uint32 `json:"min_sigs" validate:"required,min=1"`
 
 	Signers []basecoin.Actor `json:"signers" validate:"required,min=1"`
 
+	// Sequence is the user defined field whose purpose is to
+	// prevent replay attacks when creating a role, since it
+	// ensures that for a successful role creation, the previous
+	// sequence number should have been looked up by the caller.
 	Sequence uint32 `json:"seq" validate:"required,min=1"`
 }
 
-func parseRole(roleInHex string) ([]byte, error) {
+func decodeRoleHex(roleInHex string) ([]byte, error) {
 	parsedRole, err := hex.DecodeString(common.StripHex(roleInHex))
 	if err != nil {
 		err = errors.WithMessage("invalid hex", err, abci.CodeType_EncodingError)
@@ -37,8 +45,8 @@ func parseRole(roleInHex string) ([]byte, error) {
 
 // mux.Router registrars
 
-// RegisterQueryAccount is a mux.Router handler that exposes GET
-// method access on route /query/account/{signature} to query accounts
+// RegisterCreateRole is a mux.Router handler that exposes POST
+// method access on route /build/create_role to create a role.
 func RegisterCreateRole(r *mux.Router) error {
 	r.HandleFunc("/build/create_role", doCreateRole).Methods("POST")
 	return nil
@@ -51,7 +59,7 @@ func doCreateRole(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	parsedRole, err := parseRole(ri.Role)
+	parsedRole, err := decodeRoleHex(ri.Role)
 	if err != nil {
 		common.WriteError(w, err)
 		return