add functions documentation

Author: Eslam-Nawara

node-registrar/client/README.md

@@ -28,12 +28,12 @@ The Node Registrar Client enables communication with the ThreeFold Grid's node r
 ### Farms
 
 * **Create Farm**: Create new farm on the registrar with uniqe name.
-* **update Farm**: update farm configuration (farm\_id, dedicated).
-* **Get Farm**: Get a farm using either its farm\_id.
+* **update Farm**: Update farm configuration (farm\_id, dedicated).
+* **Get Farm**: Get a farm using its farm\_id.
 
 ### Node
 
-* **Register Node**: Register physical/virtual nodes with the TFGrid.
+* **Register Node**: Register physical/virtual nodes with on TFGrid.
 * **Update Node**: Update node configuration (farm\_id, interfaces, resources, location, secure\_boot, virtualized).
 * **Get Node**: Fetch registered node details using (node\_id, twin\_id, farm\_id).
 * **Update Node Uptime**: Update node Uptime.

node-registrar/client/account.go

@@ -15,18 +15,22 @@ import (
 
 var ErrorAccountNotFound = fmt.Errorf("failed to get requested account from node registrar")
 
+// CreateAccount create new account on the registrar with uniqe mnemonic.
 func (c *RegistrarClient) CreateAccount(relays []string, rmbEncKey string) (account Account, mnemonic string, err error) {
 	return c.createAccount(relays, rmbEncKey)
 }
 
-func (c *RegistrarClient) GetAccount(id uint64) (account Account, err error) {
-	return c.getAccount(id)
+// GetAccount get an account using either its twinID
+func (c *RegistrarClient) GetAccount(twinID uint64) (account Account, err error) {
+	return c.getAccount(twinID)
 }
 
-func (c *RegistrarClient) GetAccountByPK(pk []byte) (account Account, err error) {
-	return c.getAccountByPK(pk)
+// GetAccountByPK get an account using either its its publicKey.
+func (c *RegistrarClient) GetAccountByPK(publicKey []byte) (account Account, err error) {
+	return c.getAccountByPK(publicKey)
 }
 
+// UpdateAccount update the account configuration (relays or rmbEncKey).
 func (c *RegistrarClient) UpdateAccount(opts ...UpdateAccountOpts) (err error) {
 	return c.updateAccount(opts)
 }
@@ -40,18 +44,21 @@ type (
 	UpdateAccountOpts func(*accountCfg)
 )
 
+// UpdateAccountWithRelays update the account relays
 func UpdateAccountWithRelays(relays []string) UpdateAccountOpts {
 	return func(n *accountCfg) {
 		n.relays = relays
 	}
 }
 
+// UpdateAccountWithRMBEncKey update the account rmb encryption key
 func UpdateAccountWithRMBEncKey(rmbEncKey string) UpdateAccountOpts {
 	return func(n *accountCfg) {
 		n.rmbEncKey = rmbEncKey
 	}
 }
 
+// EnsureAccount ensures that an account is created with specific seed/mnemonic.
 func (c *RegistrarClient) EnsureAccount(relays []string, rmbEncKey string) (account Account, err error) {
 	return c.ensureAccount(relays, rmbEncKey)
 }
@@ -250,6 +257,7 @@ func (c *RegistrarClient) ensureAccount(relays []string, rmbEncKey string) (acco
 	return account, err
 }
 
+// ensureTwinID ensures that the RegistrarClient is set up properly with a valid public key representing an account on the registrar
 func (c *RegistrarClient) ensureTwinID() error {
 	if c.twinID != 0 {
 		return nil

node-registrar/client/client.go

@@ -16,6 +16,7 @@ type RegistrarClient struct {
 	twinID     uint64
 }
 
+// NewRegistrarClient creates a new client with optional seed or mnemonic
 func NewRegistrarClient(baseURL string, mnemonicOrSeed ...string) (cli RegistrarClient, err error) {
 	client := http.DefaultClient
 

node-registrar/client/farm.go

@@ -15,18 +15,22 @@ import (
 
 var ErrorFarmNotFound = fmt.Errorf("failed to get requested farm from node registrar")
 
+// CreateFarm create new farm on the registrar with uniqe name.
 func (c *RegistrarClient) CreateFarm(farmName, stellarAddr string, dedicated bool) (farmID uint64, err error) {
 	return c.createFarm(farmName, stellarAddr, dedicated)
 }
 
+// UpdateFarm update farm configuration (farmName, stellarAddress, dedicated).
 func (c *RegistrarClient) UpdateFarm(farmID uint64, opts ...UpdateFarmOpts) (err error) {
 	return c.updateFarm(farmID, opts)
 }
 
-func (c *RegistrarClient) GetFarm(id uint64) (farm Farm, err error) {
-	return c.getFarm(id)
+// GetFarm get a farm using its farmID
+func (c *RegistrarClient) GetFarm(farmID uint64) (farm Farm, err error) {
+	return c.getFarm(farmID)
 }
 
+// ListFarms get a list of farm using ListFarmOpts
 func (c *RegistrarClient) ListFarms(opts ...ListFarmOpts) (farms []Farm, err error) {
 	return c.listFarms(opts...)
 }
@@ -46,48 +50,56 @@ type (
 	UpdateFarmOpts func(*farmCfg)
 )
 
+// ListFarmWithName lists farms with farm name
 func ListFarmWithName(name string) ListFarmOpts {
 	return func(n *farmCfg) {
 		n.farmName = name
 	}
 }
 
+// ListFarmWithFarmID lists farms with farmID
 func ListFarmWithFarmID(id uint64) ListFarmOpts {
 	return func(n *farmCfg) {
 		n.farmID = id
 	}
 }
 
+// ListFarmWithTwinID lists farms with twinID
 func ListFarmWithTwinID(id uint64) ListFarmOpts {
 	return func(n *farmCfg) {
 		n.twinID = id
 	}
 }
 
+// ListFarmWithDedicated lists dedicated farms
 func ListFarmWithDedicated() ListFarmOpts {
 	return func(n *farmCfg) {
 		n.dedicated = true
 	}
 }
 
+// ListFarmWithPage lists farms in a certain page
 func ListFarmWithPage(page uint32) ListFarmOpts {
 	return func(n *farmCfg) {
 		n.page = page
 	}
 }
 
+// ListFarmWithPage lists size number of farms
 func ListFarmWithSize(size uint32) ListFarmOpts {
 	return func(n *farmCfg) {
 		n.size = size
 	}
 }
 
+// UpdateFarmWithName update farm name
 func UpdateFarmWithName(name string) UpdateFarmOpts {
 	return func(n *farmCfg) {
 		n.farmName = name
 	}
 }
 
+// UpdateFarmWithName set farm status to dedicated
 func UpdateFarmWithDedicated() UpdateFarmOpts {
 	return func(n *farmCfg) {
 		n.dedicated = true
@@ -331,6 +343,7 @@ func parseUpdateFarmOpts(opts []UpdateFarmOpts) map[string]any {
 	return data
 }
 
+// validateStellarAddress ensures that the address is valid stellar address
 func validateStellarAddress(stellarAddr string) error {
 	stellarAddr = strings.TrimSpace(stellarAddr)
 	if len(stellarAddr) != 56 {

node-registrar/client/mnemonic.go

@@ -12,16 +12,18 @@ func (c *RegistrarClient) Mnemonic() string {
 	return c.mnemonic
 }
 
+// parseKeysFromMnemonicOrSeed drives keypair from mnemonic or seed
 func parseKeysFromMnemonicOrSeed(mnemonicOrSeed string) (keypair subkey.KeyPair, err error) {
 	// otherwise drive key pair from seed
 	keypair, err = subkey.DeriveKeyPair(subkeyEd25519.Scheme{}, mnemonicOrSeed)
 	if err != nil {
-		return keypair, errors.Wrapf(err, "failed  to derive key pair from seed %s", mnemonicOrSeed)
+		return keypair, errors.Wrapf(err, "failed  to drive key pair from seed %s", mnemonicOrSeed)
 	}
 
 	return keypair, nil
 }
 
+// generateNewMnemonic generates new mnemonic and keypair
 func generateNewMnemonic() (mnemonic string, keypair subkey.KeyPair, err error) {
 	// Generate 128-bit entropy (12-word mnemonic)
 	entropy, err := bip39.NewEntropy(128)

node-registrar/client/node.go

@@ -14,6 +14,7 @@ import (
 
 var ErrorNodeNotFound = fmt.Errorf("failed to get requested node from node registrar")
 
+// RegisterNode register physical/virtual nodes with on TFGrid.
 func (c *RegistrarClient) RegisterNode(
 	farmID uint64,
 	twinID uint64,
@@ -27,22 +28,27 @@ func (c *RegistrarClient) RegisterNode(
 	return c.registerNode(farmID, twinID, interfaces, location, resources, serialNumber, secureBoot, virtualized)
 }
 
+// UpdateNode update node configuration (farmID, interfaces, resources, location, secureBoot, virtualized).
 func (c *RegistrarClient) UpdateNode(opts ...UpdateNodeOpts) (err error) {
 	return c.updateNode(opts)
 }
 
+// ReportUptime update node Uptime.
 func (c *RegistrarClient) ReportUptime(report UptimeReport) (err error) {
 	return c.reportUptime(report)
 }
 
+// GetNode gets registered node details using nodeID
 func (c *RegistrarClient) GetNode(id uint64) (node Node, err error) {
 	return c.getNode(id)
 }
 
+// GetNodeByTwinID gets registered node details using twinID
 func (c *RegistrarClient) GetNodeByTwinID(id uint64) (node Node, err error) {
 	return c.getNodeByTwinID(id)
 }
 
+// ListNodes lists registered nodes details using (nodeID, twinID, farmID).
 func (c *RegistrarClient) ListNodes(opts ...ListNodeOpts) (nodes []Node, err error) {
 	return c.listNodes(opts)
 }

node-registrar/client/utils.go

@@ -9,6 +9,7 @@ import (
 	"github.com/pkg/errors"
 )
 
+// signRequest signs request with challenge with format timestamp:twinID
 func (c *RegistrarClient) signRequest(timestamp int64) (authHeader string, err error) {
 	challenge := []byte(fmt.Sprintf("%d:%v", timestamp, c.twinID))
 	signature, err := c.keyPair.Sign(challenge)
@@ -24,6 +25,7 @@ func (c *RegistrarClient) signRequest(timestamp int64) (authHeader string, err e
 	return
 }
 
+// parseResponseError parse json response error
 func parseResponseError(body io.Reader) (err error) {
 	errResp := struct {
 		Error string `json:"error"`

node-registrar/client/zos_version.go

@@ -12,10 +12,12 @@ import (
 	"github.com/pkg/errors"
 )
 
+// GetZosVersion gets zos version for specific network
 func (c *RegistrarClient) GetZosVersion() (version ZosVersion, err error) {
 	return c.getZosVersion()
 }
 
+// SetZosVersion sets zos version for specific network only valid for network admin
 func (c *RegistrarClient) SetZosVersion(v string, safeToUpgrade bool) (err error) {
 	return c.setZosVersion(v, safeToUpgrade)
 }