From 90135350bed12ac7fa6c733f2af58f35c04769b3 Mon Sep 17 00:00:00 2001
From: Bruno Andreghetti <brunoandreghetti@gmail.com>
Date: Thu, 25 Mar 2021 19:09:41 -0300
Subject: [PATCH] Finish docs review

---
 assets/assetProp.go          |  2 +-
 assets/assetType.go          | 28 +++++++++++++++++-----------
 assets/checkWriters.go       |  4 ++--
 assets/clean.go              |  2 +-
 assets/dataType.go           | 14 ++++++++------
 assets/delete.go             |  3 +--
 assets/existsInLedger.go     |  4 ++--
 assets/get.go                |  4 ++--
 assets/key.go                | 20 +++++++++++++-------
 assets/put.go                | 10 ++++++----
 assets/references.go         | 10 +++++-----
 assets/setProp.go            |  2 +-
 assets/startupCheck.go       |  2 +-
 assets/update.go             |  3 +--
 assets/validateProp.go       |  2 +-
 transactions/getArgs.go      |  2 +-
 transactions/getDataTypes.go |  2 +-
 transactions/getSchema.go    |  2 +-
 transactions/getTx.go        |  2 +-
 transactions/startupCheck.go |  2 +-
 transactions/transaction.go  | 30 ++++++++++++++++++++++--------
 21 files changed, 89 insertions(+), 61 deletions(-)

diff --git a/assets/assetProp.go b/assets/assetProp.go
index 12c3140..c01c64e 100644
--- a/assets/assetProp.go
+++ b/assets/assetProp.go
@@ -40,6 +40,6 @@ type AssetProp struct {
 	// check for a match with regular expression `org\dMSP`
 	Writers []string `json:"writers"`
 
-	// Validate receives a function to be called when validating property format
+	// Validate is a function called when validating property format.
 	Validate func(interface{}) error `json:"-"`
 }
diff --git a/assets/assetType.go b/assets/assetType.go
index 12b47cd..2753557 100644
--- a/assets/assetType.go
+++ b/assets/assetType.go
@@ -4,26 +4,32 @@ import "strings"
 
 // AssetType is a list of all asset properties
 type AssetType struct {
-	// Tag is how the asset will be referenced
+	// Tag is how the asset type will be referenced in the "@assetType" metaproperty.
 	Tag string `json:"tag"`
 
-	// The label is for frontend rendering
+	// Label is the pretty asset type name for front-end rendering
 	Label string `json:"label"`
 
-	// The description is a simple explanation for the specific field
+	// Description is a simple explanation describing the meaning of the asset type.
 	Description string `json:"description"`
 
-	// Props receives an array of assetProps, definig the assets properties
+	// Props receives an array of assetProps, defining the asset's properties.
 	Props []AssetProp `json:"props"`
 
-	// Readers is an array that specifies which organizations can read the asset (used for private data)
+	// Readers is an array that specifies which organizations can read the asset.
+	// Must be coherent with private data collections configuration.
+	// Accepts either basic strings for exact matches
+	// eg. []string{'org1MSP', 'org2MSP'}
+	// or regular expressions
+	// eg. []string{`$org\dMSP`} and cc-tools will
+	// check for a match with regular expression `org\dMSP`
 	Readers []string `json:"readers,omitempty"`
 
-	// Validates is a function that performs the asset input validation
+	// Validate is a function called when validating asset as a whole.
 	Validate func(Asset) error `json:"-"`
 }
 
-// Keys returns a list of asset properties which are defined as primary keys
+// Keys returns a list of asset properties which are defined as primary keys. (IsKey == true)
 func (t AssetType) Keys() (keys []AssetProp) {
 	for _, prop := range t.Props {
 		if prop.IsKey {
@@ -33,7 +39,7 @@ func (t AssetType) Keys() (keys []AssetProp) {
 	return
 }
 
-// SubAssets returns a list of asset properties which are subAssets
+// SubAssets returns a list of asset properties which are subAssets (DataType is `->someAssetType`)
 func (t AssetType) SubAssets() (subAssets []AssetProp) {
 	for _, prop := range t.Props {
 		dataType := prop.DataType
@@ -51,7 +57,7 @@ func (t AssetType) SubAssets() (subAssets []AssetProp) {
 	return
 }
 
-// HasProp returns true if asset type has a property with the given tag
+// HasProp returns true if asset type has a property with the given tag.
 func (t AssetType) HasProp(propTag string) bool {
 	for _, prop := range t.Props {
 		if prop.Tag == propTag {
@@ -61,7 +67,7 @@ func (t AssetType) HasProp(propTag string) bool {
 	return false
 }
 
-// GetPropDef fetches the propDef with tag propTag
+// GetPropDef fetches the propDef with tag propTag.
 func (t AssetType) GetPropDef(propTag string) *AssetProp {
 	for _, prop := range t.Props {
 		if prop.Tag == propTag {
@@ -71,7 +77,7 @@ func (t AssetType) GetPropDef(propTag string) *AssetProp {
 	return nil
 }
 
-// IsPrivate returns true if asset is in a private collection
+// IsPrivate returns true if asset is in a private collection.
 func (t AssetType) IsPrivate() bool {
 	return len(t.Readers) > 0
 }
diff --git a/assets/checkWriters.go b/assets/checkWriters.go
index de41f17..c5b7ef1 100644
--- a/assets/checkWriters.go
+++ b/assets/checkWriters.go
@@ -9,7 +9,7 @@ import (
 	"github.com/hyperledger/fabric/core/chaincode/shim"
 )
 
-// CheckWriters checks if tx creator is allowed to write asset
+// CheckWriters checks if tx creator is allowed to write asset.
 func (a Asset) CheckWriters(stub shim.ChaincodeStubInterface) errors.ICCError {
 	// Get tx creator MSP ID
 	txCreator, err := cid.GetMSPID(stub)
@@ -20,7 +20,7 @@ func (a Asset) CheckWriters(stub shim.ChaincodeStubInterface) errors.ICCError {
 	return a.checkWriters(txCreator)
 }
 
-// checkWriters is an intern function that checks if tx creator is allowed to write asset
+// checkWriters is an internal function that checks if tx creator is allowed to write asset.
 func (a Asset) checkWriters(txCreator string) errors.ICCError {
 	// Fetch asset properties
 	assetTypeDef := a.Type()
diff --git a/assets/clean.go b/assets/clean.go
index edc51ec..f691218 100644
--- a/assets/clean.go
+++ b/assets/clean.go
@@ -1,6 +1,6 @@
 package assets
 
-// clean cleans an asset, erasing the data from the map
+// clean erases nil data from the asset map
 func (a *Asset) clean() {
 	for k, v := range *a {
 		if v == nil {
diff --git a/assets/dataType.go b/assets/dataType.go
index aa6b149..1c630dc 100644
--- a/assets/dataType.go
+++ b/assets/dataType.go
@@ -9,17 +9,19 @@ import (
 	"github.com/goledgerdev/cc-tools/errors"
 )
 
-// DataType is the struct defining a primitive data type
-// The description is a simple explanation for the specific field
-// DropDownValues is a set of pre determined values to be used in a dropdown menu on frontend rendering
-// Parse is a function that parses the interface received, validates the input and stores a string representation of the value
+// DataType is the struct defining a primitive data type.
 type DataType struct {
 	// AcceptedFormats is a list of "core" types that can be accepted (string, number, integer, boolean, datetime)
 	AcceptedFormats []string `json:"acceptedFormats"`
-	Description     string   `json:"description,omitempty"`
 
+	// Description is a simple text describing the data type
+	Description string `json:"description,omitempty"`
+
+	// DropDownValues is a set of predetermined values to be used in a dropdown menu on frontend rendering
 	DropDownValues map[string]interface{}
 
+	// Parse is called to check if the input value is valid, make necessary
+	// conversions and returns a string representation of the value
 	Parse func(interface{}) (string, interface{}, errors.ICCError) `json:"-"`
 
 	legacyMode bool
@@ -57,7 +59,7 @@ func DataTypeMap() map[string]DataType {
 	return ret
 }
 
-// Primitive dataType map, contains all the default data types
+// dataTypeMap contains the "standard" primitive data types
 var dataTypeMap = map[string]DataType{
 	"string": {
 		AcceptedFormats: []string{"string"},
diff --git a/assets/delete.go b/assets/delete.go
index 80c4836..62a2caf 100644
--- a/assets/delete.go
+++ b/assets/delete.go
@@ -8,8 +8,7 @@ import (
 )
 
 // Delete erases asset from world state and checks for all necessary permissions.
-// A asset cannot be deleted if other asset references it
-// The asset is not deleted from the blockchain
+// An asset cannot be deleted if any other asset references it.
 func (a *Asset) Delete(stub shim.ChaincodeStubInterface) ([]byte, error) {
 	var err error
 
diff --git a/assets/existsInLedger.go b/assets/existsInLedger.go
index b0188c1..1a4d133 100644
--- a/assets/existsInLedger.go
+++ b/assets/existsInLedger.go
@@ -5,7 +5,7 @@ import (
 	"github.com/hyperledger/fabric/core/chaincode/shim"
 )
 
-// ExistsInLedger checks if asset already exists
+// ExistsInLedger checks if asset currently has a state on the ledger.
 func (a *Asset) ExistsInLedger(stub shim.ChaincodeStubInterface) (bool, errors.ICCError) {
 	var assetBytes []byte
 	var err error
@@ -24,7 +24,7 @@ func (a *Asset) ExistsInLedger(stub shim.ChaincodeStubInterface) (bool, errors.I
 	return false, nil
 }
 
-// ExistsInLedger checks if asset referenced by a key object already exists
+// ExistsInLedger checks if asset referenced by a key object currently has a state on the ledger.
 func (k *Key) ExistsInLedger(stub shim.ChaincodeStubInterface) (bool, errors.ICCError) {
 	var assetBytes []byte
 	var err error
diff --git a/assets/get.go b/assets/get.go
index 88cbf1d..0740028 100644
--- a/assets/get.go
+++ b/assets/get.go
@@ -34,7 +34,7 @@ func get(stub shim.ChaincodeStubInterface, pvtCollection, key string) (*Asset, e
 	return &response, nil
 }
 
-// Get reads asset from ledger
+// Get fetches asset entry from ledger.
 func (a *Asset) Get(stub shim.ChaincodeStubInterface) (*Asset, errors.ICCError) {
 	var pvtCollection string
 	if a.IsPrivate() {
@@ -44,7 +44,7 @@ func (a *Asset) Get(stub shim.ChaincodeStubInterface) (*Asset, errors.ICCError)
 	return get(stub, pvtCollection, a.Key())
 }
 
-// Get reads asset from ledger
+// Get fetches asset entry from ledger.
 func (k *Key) Get(stub shim.ChaincodeStubInterface) (*Asset, errors.ICCError) {
 	var pvtCollection string
 	if k.IsPrivate() {
diff --git a/assets/key.go b/assets/key.go
index 6b1ee61..bf1003d 100644
--- a/assets/key.go
+++ b/assets/key.go
@@ -7,12 +7,12 @@ import (
 	"github.com/hyperledger/fabric/core/chaincode/shim"
 )
 
-//Key implements the json.Unmarshaler interface
-//It stores the information for retrieving assets from the ledger
-//Instead of having every field, it only has the ones needes for querying
+// Key stores the information for retrieving an Asset from the ledger.
+// Instead of having every asset property mapped such as the Asset type,
+// Key only has the properties needed for fetching the full Asset.
 type Key map[string]interface{}
 
-//UnmarshalJSON parses JSON-encoded data and returns
+// UnmarshalJSON parses JSON-encoded data and returns a Key object pointer
 func (k *Key) UnmarshalJSON(jsonData []byte) error {
 	*k = make(Key)
 	var err error
@@ -33,7 +33,12 @@ func (k *Key) UnmarshalJSON(jsonData []byte) error {
 	return nil
 }
 
-// NewKey constructs Key object from a map
+// NewKey constructs Key object from a map of properties.
+// The map must contain the `@assetType` entry and either
+// all the key properties of the asset (`IsKey == true`) or
+// the `@key` property.
+// Either way, the Key object returned contains only the
+// `@assetType` and `@key` entries.
 func NewKey(m map[string]interface{}) (k Key, err errors.ICCError) {
 	if m == nil {
 		err = errors.NewCCError("cannot create key from nil map", 500)
@@ -84,7 +89,7 @@ func (k *Key) GetBytes(stub shim.ChaincodeStubInterface) ([]byte, errors.ICCErro
 	return assetBytes, nil
 }
 
-// Type return the AssetType object configuration for the asset
+// Type returns the AssetType configuration object for the asset
 func (k Key) Type() *AssetType {
 	// Fetch asset properties
 	assetTypeTag := k.TypeTag()
@@ -108,12 +113,13 @@ func (k Key) TypeTag() string {
 	return assetType
 }
 
-// Key returns the asset's unique key
+// Key returns the asset's unique identifying key in the ledger.
 func (k Key) Key() string {
 	assetKey := k["@key"].(string)
 	return assetKey
 }
 
+// String returns the Key in stringified JSON format.
 func (k Key) String() string {
 	ret, _ := json.Marshal(k)
 	return string(ret)
diff --git a/assets/put.go b/assets/put.go
index 1fb989e..3e2af39 100644
--- a/assets/put.go
+++ b/assets/put.go
@@ -9,8 +9,8 @@ import (
 	"github.com/hyperledger/fabric/core/chaincode/shim"
 )
 
-// put writes the reference index to the ledger, then encodes the asset to JSON format
-// and puts it into the ledger. It checks if the asset belongs in a private collection
+// put writes the reference index to the ledger, then encodes the
+// asset to JSON format and puts it into the ledger.
 func (a *Asset) put(stub shim.ChaincodeStubInterface) (map[string]interface{}, errors.ICCError) {
 	var err error
 
@@ -70,7 +70,7 @@ func (a *Asset) Put(stub shim.ChaincodeStubInterface) (map[string]interface{}, e
 	return a.put(stub)
 }
 
-// PutNew inserts asset in blockchain and returns error if asset exists
+// PutNew inserts asset in blockchain and returns error if asset exists.
 func (a *Asset) PutNew(stub shim.ChaincodeStubInterface) (map[string]interface{}, errors.ICCError) {
 	// Check if asset already exists
 	exists, err := a.ExistsInLedger(stub)
@@ -181,7 +181,9 @@ func PutRecursive(stub shim.ChaincodeStubInterface, object map[string]interface{
 	return putRecursive(stub, object, true)
 }
 
-// PutNewRecursive inserts asset and all it's subassets in blockchain and returns error if asset exists
+// PutNewRecursive inserts asset and all it's subassets in blockchain
+// It returns conflict error only if root asset exists.
+// If one of the subassets already exist in ledger, it is not updated.
 func PutNewRecursive(stub shim.ChaincodeStubInterface, object map[string]interface{}) (map[string]interface{}, errors.ICCError) {
 	objAsAsset, err := NewAsset(object)
 	if err != nil {
diff --git a/assets/references.go b/assets/references.go
index be5411c..2dece06 100644
--- a/assets/references.go
+++ b/assets/references.go
@@ -8,7 +8,7 @@ import (
 	"github.com/hyperledger/fabric/core/chaincode/shim"
 )
 
-// Refs returns an array of keys, containing the subAssets reference keys
+// Refs returns an array of Keys containing the reference keys for all present subAssets.
 func (a Asset) Refs() ([]Key, errors.ICCError) {
 	// Fetch asset properties
 	assetTypeDef := a.Type()
@@ -85,7 +85,7 @@ func (a Asset) Refs() ([]Key, errors.ICCError) {
 	return keys, nil
 }
 
-// ValidateRefs checks if subAsset references exists in blockchain
+// validateRefs checks if subAsset references exist in blockchain.
 func (a Asset) validateRefs(stub shim.ChaincodeStubInterface) errors.ICCError {
 	// Fetch references contained in asset
 	refKeys, err := a.Refs()
@@ -107,7 +107,7 @@ func (a Asset) validateRefs(stub shim.ChaincodeStubInterface) errors.ICCError {
 	return nil
 }
 
-// DelRefs deletes all the reference index for this asset from blockchain
+// delRefs deletes all the reference index for this asset from blockchain.
 func (a Asset) delRefs(stub shim.ChaincodeStubInterface) errors.ICCError {
 	// Fetch references contained in asset
 	refKeys, err := a.Refs()
@@ -131,7 +131,7 @@ func (a Asset) delRefs(stub shim.ChaincodeStubInterface) errors.ICCError {
 	return nil
 }
 
-// PutRefs writes the references to the blockchain
+// putRefs writes the asset's reference index to the blockchain.
 func (a Asset) putRefs(stub shim.ChaincodeStubInterface) errors.ICCError {
 	// Fetch references contained in asset
 	refKeys, err := a.Refs()
@@ -157,7 +157,7 @@ func (a Asset) putRefs(stub shim.ChaincodeStubInterface) errors.ICCError {
 	return nil
 }
 
-// IsReferenced checks if asset is referenced by other asset
+// IsReferenced checks if the asset is referenced by another asset.
 func (a Asset) IsReferenced(stub shim.ChaincodeStubInterface) (bool, errors.ICCError) {
 	// Get asset key
 	assetKey := a.Key()
diff --git a/assets/setProp.go b/assets/setProp.go
index ba0f9a8..5acc769 100644
--- a/assets/setProp.go
+++ b/assets/setProp.go
@@ -6,7 +6,7 @@ import (
 	"github.com/goledgerdev/cc-tools/errors"
 )
 
-// SetProp sets the prop value with proper validation. It does not update the asset in the ledger
+// SetProp sets the prop value with proper validation. It does not update the asset in the ledger.
 func (a *Asset) SetProp(propTag string, value interface{}) errors.ICCError {
 	if len(propTag) == 0 {
 		return errors.NewCCError("propTag cannot be empty", 500)
diff --git a/assets/startupCheck.go b/assets/startupCheck.go
index d611e30..3a16fa1 100644
--- a/assets/startupCheck.go
+++ b/assets/startupCheck.go
@@ -8,7 +8,7 @@ import (
 	"github.com/goledgerdev/cc-tools/errors"
 )
 
-// StartupCheck verifies if asset definitions are properly coded, panicking if they're not
+// StartupCheck verifies if asset definitions are properly coded, returning an error if they're not
 func StartupCheck() errors.ICCError {
 	assetTagSet := map[string]struct{}{}
 	assetLabelSet := map[string]struct{}{}
diff --git a/assets/update.go b/assets/update.go
index 33b4ba3..d886b77 100644
--- a/assets/update.go
+++ b/assets/update.go
@@ -9,8 +9,7 @@ import (
 	"github.com/hyperledger/fabric/core/chaincode/shim"
 )
 
-// Update receives a map[string]interface{} with key/vals to update the asset value in the wolrd state
-// The old asset is still on the blockchain history
+// Update receives a map[string]interface{} with key/vals to update the asset value in the world state.
 func (a *Asset) Update(stub shim.ChaincodeStubInterface, update map[string]interface{}) (map[string]interface{}, error) {
 	// Fetch asset properties
 	assetTypeDef := a.Type()
diff --git a/assets/validateProp.go b/assets/validateProp.go
index 7e2ebd2..338ac1a 100644
--- a/assets/validateProp.go
+++ b/assets/validateProp.go
@@ -7,7 +7,7 @@ import (
 	"github.com/goledgerdev/cc-tools/errors"
 )
 
-// validateProp checks if the given assetProp is valid
+// validateProp checks if a given assetProp is valid according to the given property definition
 func validateProp(prop interface{}, propDef AssetProp) (interface{}, error) {
 	var isArray bool
 	dataTypeName := propDef.DataType
diff --git a/transactions/getArgs.go b/transactions/getArgs.go
index 64cf49e..ec4177f 100644
--- a/transactions/getArgs.go
+++ b/transactions/getArgs.go
@@ -10,7 +10,7 @@ import (
 	"github.com/hyperledger/fabric/core/chaincode/shim"
 )
 
-// GetArgs validates the arguments and assembles a map with the parsed key/values
+// GetArgs validates the received arguments and assembles a map with the parsed key/values.
 func (tx Transaction) GetArgs(stub shim.ChaincodeStubInterface) (map[string]interface{}, errors.ICCError) {
 	var err error
 
diff --git a/transactions/getDataTypes.go b/transactions/getDataTypes.go
index 5f50997..35eabfd 100644
--- a/transactions/getDataTypes.go
+++ b/transactions/getDataTypes.go
@@ -8,7 +8,7 @@ import (
 	"github.com/hyperledger/fabric/core/chaincode/shim"
 )
 
-// GetDataTypes returns the data type map
+// GetDataTypes returns the primitive data type map
 var GetDataTypes = Transaction{
 	Tag:         "getDataTypes",
 	Label:       "Get DataTypes",
diff --git a/transactions/getSchema.go b/transactions/getSchema.go
index f29cac1..c21bd80 100644
--- a/transactions/getSchema.go
+++ b/transactions/getSchema.go
@@ -9,7 +9,7 @@ import (
 	"github.com/hyperledger/fabric/core/chaincode/shim"
 )
 
-// GetSchema returns data in CCHeader
+// GetSchema returns information about a specific AssetType or a list of every configured AssetType
 var GetSchema = Transaction{
 	Tag:         "getSchema",
 	Label:       "Get Schema",
diff --git a/transactions/getTx.go b/transactions/getTx.go
index fee2b5f..9b3e726 100644
--- a/transactions/getTx.go
+++ b/transactions/getTx.go
@@ -8,7 +8,7 @@ import (
 	"github.com/hyperledger/fabric/core/chaincode/shim"
 )
 
-// getTx returns tx definitions
+// getTx returns a specific tx definition or a list of all configured txs
 var getTx = Transaction{
 	Tag:         "getTx",
 	Label:       "Get Tx",
diff --git a/transactions/startupCheck.go b/transactions/startupCheck.go
index cd6a43f..9cc1ad3 100644
--- a/transactions/startupCheck.go
+++ b/transactions/startupCheck.go
@@ -7,7 +7,7 @@ import (
 	"github.com/goledgerdev/cc-tools/errors"
 )
 
-// StartupCheck verifies if asset definitions are properly coded
+// StartupCheck verifies if tx definitions are properly coded, returning an error if they're not.
 func StartupCheck() errors.ICCError {
 	// Checks if there are references to undefined types
 	for _, tx := range txList {
diff --git a/transactions/transaction.go b/transactions/transaction.go
index 5e699f9..afa423b 100644
--- a/transactions/transaction.go
+++ b/transactions/transaction.go
@@ -9,19 +9,33 @@ import (
 type Transaction struct {
 	// List of all MSPs allowed to run this transaction.
 	// Regexp is supported by putting '$' before the MSP regexp e.g. []string{`$org\dMSP`}.
-	// Please note this restriction DOES NOT protect ledger data from being read by unauthorized organizations.
-	// This should be done with Private Data.
+	// Please note this restriction DOES NOT protect ledger data from being
+	// read by unauthorized organizations, this should be done with Private Data.
 	Callers []string `json:"callers,omitempty"`
 
-	Tag         string `json:"tag"`
-	Label       string `json:"label"`
+	// Tag is how the tx will be called.
+	Tag string `json:"tag"`
+
+	// Label is the pretty tx name for front-end rendering.
+	Label string `json:"label"`
+
+	// Description is a simple explanation describing what the tx does.
 	Description string `json:"description"`
 
-	Args     ArgList `json:"args"`
-	Method   string  `json:"method"`
-	ReadOnly bool    `json:"readOnly"`
-	MetaTx   bool    `json:"metaTx"`
+	// Args is a list of argument formats accepted by the tx.
+	Args ArgList `json:"args"`
+
+	// Method indicates the HTTP method which should be used to call the tx when using an HTTP API.
+	Method string `json:"method"`
+
+	// ReadOnly indicates that the tx does not alter the world state.
+	ReadOnly bool `json:"readOnly"`
+
+	// MetaTx indicates that the tx does not encode a business-specific rule,
+	// but an internal process of the chaincode e.g. listing available asset types.
+	MetaTx bool `json:"metaTx"`
 
+	// Routine is the function called when running the tx. It is where the tx logic can be programmed.
 	Routine func(shim.ChaincodeStubInterface, map[string]interface{}) ([]byte, errors.ICCError) `json:"-"`
 }