Finish docs review

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:"-"`
 }

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
 }

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()

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 {

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"},

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
 

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

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() {

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)

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 {

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()

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)

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{}{}

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()

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

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
 

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",

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",

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",