From 5e608a567cb7ab4ac56370c7ad092dbbeb3a3ca9 Mon Sep 17 00:00:00 2001
From: keke-ka <kkektkid@163.com>
Date: Sat, 12 Oct 2024 19:04:25 +0800
Subject: [PATCH] docs(accounts): update docs (backend.go, hub.go)

---
 accounts/external/backend.go | 11 +++++++++++
 accounts/scwallet/hub.go     | 10 ++++++++++
 2 files changed, 21 insertions(+)

diff --git a/accounts/external/backend.go b/accounts/external/backend.go
index 62322753da..8a7bc7efa8 100644
--- a/accounts/external/backend.go
+++ b/accounts/external/backend.go
@@ -37,10 +37,13 @@ type ExternalBackend struct {
 	signers []accounts.Wallet
 }
 
+// Wallets returns a list of wallets associated with the external backend.
 func (eb *ExternalBackend) Wallets() []accounts.Wallet {
 	return eb.signers
 }
 
+// NewExternalBackend creates a new instance of ExternalBackend by initializing
+// an external signer with the provided endpoint. 
 func NewExternalBackend(endpoint string) (*ExternalBackend, error) {
 	signer, err := NewExternalSigner(endpoint)
 	if err != nil {
@@ -51,6 +54,8 @@ func NewExternalBackend(endpoint string) (*ExternalBackend, error) {
 	}, nil
 }
 
+// Subscribe sets up a subscription for wallet events, which is essentially
+// a no-op in this implementation.
 func (eb *ExternalBackend) Subscribe(sink chan<- accounts.WalletEvent) event.Subscription {
 	return event.NewSubscription(func(quit <-chan struct{}) error {
 		<-quit
@@ -69,6 +74,8 @@ type ExternalSigner struct {
 	cache    []accounts.Account
 }
 
+// NewExternalSigner creates a new instance of ExternalSigner by establishing
+// a connection to the specified endpoint.
 func NewExternalSigner(endpoint string) (*ExternalSigner, error) {
 	client, err := rpc.Dial(endpoint)
 	if err != nil {
@@ -87,6 +94,7 @@ func NewExternalSigner(endpoint string) (*ExternalSigner, error) {
 	return extsigner, nil
 }
 
+// URL returns the accounts.URL representation of the ExternalSigner.
 func (api *ExternalSigner) URL() accounts.URL {
 	return accounts.URL{
 		Scheme: "extapi",
@@ -106,6 +114,7 @@ func (api *ExternalSigner) Close() error {
 	return errors.New("operation not supported on external signers")
 }
 
+// Accounts retrieves the list of accounts from the external signer service.
 func (api *ExternalSigner) Accounts() []accounts.Account {
 	var accnts []accounts.Account
 	res, err := api.listAccounts()
@@ -128,6 +137,7 @@ func (api *ExternalSigner) Accounts() []accounts.Account {
 	return accnts
 }
 
+// Contains checks if the specified account exists in the external signer's cached accounts.
 func (api *ExternalSigner) Contains(account accounts.Account) bool {
 	api.cacheMu.RLock()
 	defer api.cacheMu.RUnlock()
@@ -170,6 +180,7 @@ func (api *ExternalSigner) SignData(account accounts.Account, mimeType string, d
 	return res, nil
 }
 
+// SignText signs a plain text message using the specified account.
 func (api *ExternalSigner) SignText(account accounts.Account, text []byte) ([]byte, error) {
 	var signature hexutil.Bytes
 	var signAddress = common.NewMixedcaseAddress(account.Address)
diff --git a/accounts/scwallet/hub.go b/accounts/scwallet/hub.go
index 1b1899dc8e..049c8d5547 100644
--- a/accounts/scwallet/hub.go
+++ b/accounts/scwallet/hub.go
@@ -86,6 +86,9 @@ type Hub struct {
 	stateLock sync.RWMutex // Protects the internals of the hub from racey access
 }
 
+// readPairings reads smartcard pairings from a JSON file and populates the
+// hub's pairing map. The method attempts to open the "smartcards.json" file
+// located in the hub's data directory. 
 func (hub *Hub) readPairings() error {
 	hub.pairings = make(map[string]smartcardPairing)
 	pairingFile, err := os.Open(filepath.Join(hub.datadir, "smartcards.json"))
@@ -112,6 +115,9 @@ func (hub *Hub) readPairings() error {
 	return nil
 }
 
+// writePairings writes the current smartcard pairings to a JSON file.
+// The method opens (or creates) the "smartcards.json" file located in the
+// hub's data directory in read/write mode.
 func (hub *Hub) writePairings() error {
 	pairingFile, err := os.OpenFile(filepath.Join(hub.datadir, "smartcards.json"), os.O_RDWR|os.O_CREATE, 0755)
 	if err != nil {
@@ -136,6 +142,7 @@ func (hub *Hub) writePairings() error {
 	return nil
 }
 
+// pairing retrieves the smartcard pairing associated with the given wallet.
 func (hub *Hub) pairing(wallet *Wallet) *smartcardPairing {
 	if pairing, ok := hub.pairings[string(wallet.PublicKey)]; ok {
 		return &pairing
@@ -143,6 +150,9 @@ func (hub *Hub) pairing(wallet *Wallet) *smartcardPairing {
 	return nil
 }
 
+// setPairing sets or removes the smartcard pairing for the given wallet.
+// If the pairing parameter is nil, it deletes the pairing entry from the
+// hub's pairings map.
 func (hub *Hub) setPairing(wallet *Wallet, pairing *smartcardPairing) error {
 	if pairing == nil {
 		delete(hub.pairings, string(wallet.PublicKey))