From e2b04570c11d585d9401fc19c41dec168f2063d3 Mon Sep 17 00:00:00 2001
From: Richard Ramos <info@richardramos.me>
Date: Mon, 25 Jul 2022 11:28:17 -0400
Subject: [PATCH] chore: improve docs

---
 library/README.md                                | 15 +--------------
 library/api.go                                   |  1 +
 library/api_store.go                             |  4 +---
 mobile/api.go                                    |  2 ++
 tests/init.go                                    |  1 +
 waku/options.go                                  | 15 +++++++++++++++
 waku/persistence/store.go                        | 16 +++++++++++-----
 waku/v2/dnsdisc/enr.go                           |  2 +-
 waku/v2/protocol/lightpush/waku_lightpush.go     |  1 +
 .../protocol/lightpush/waku_lightpush_option.go  | 10 ++++++++++
 waku/v2/protocol/store/waku_store.go             |  2 +-
 waku/v2/utils/crypto.go                          |  2 ++
 waku/v2/utils/enr.go                             |  2 +-
 waku/v2/utils/logger.go                          |  1 +
 14 files changed, 49 insertions(+), 25 deletions(-)

diff --git a/library/README.md b/library/README.md
index 959ec066..91a89d70 100644
--- a/library/README.md
+++ b/library/README.md
@@ -1,14 +1,3 @@
----
-slug: #
-title: #/GOWAKU-BINDINGS
-name: Go-Waku v2 C Bindings
-status: draft
-tags: go-waku
-editor: Richard Ramos <richard@status.im>
-contributors:
-
----
-
 This specification describes the API for consuming go-waku when built as a dynamic or static library
 
 
@@ -441,9 +430,7 @@ Query historic messages using waku store protocol.
   "startTime": 1234, // optional, unix epoch time in nanoseconds
   "endTime": 1234, // optional, unix epoch time in nanoseconds
   "contentFilters": [ // optional
-    {
-      "contentTopic": "..."
-    }, ...
+    "contentTopic1", "contentTopic2" ...
   ],
   "pagingOptions": { // optional pagination information
     "pageSize": 40, // number
diff --git a/library/api.go b/library/api.go
index 8042d739..ded544e6 100644
--- a/library/api.go
+++ b/library/api.go
@@ -1,3 +1,4 @@
+// Set of functions that are exported when go-waku is built as a static/dynamic library
 package main
 
 /*
diff --git a/library/api_store.go b/library/api_store.go
index b79691a1..4880f31a 100644
--- a/library/api_store.go
+++ b/library/api_store.go
@@ -14,9 +14,7 @@ import (
 //  "startTime": 1234, // optional, unix epoch time in nanoseconds
 //  "endTime": 1234, // optional, unix epoch time in nanoseconds
 //  "contentFilters": [ // optional
-// 	    {
-//	       "contentTopic": "..."
-//      }, ...
+// 	    "contentTopic1", "contentTopic2" ...
 //  ],
 //  "pagingOptions": {// optional pagination information
 //      "pageSize": 40, // number
diff --git a/mobile/api.go b/mobile/api.go
index 6608029b..3cc89ba0 100644
--- a/mobile/api.go
+++ b/mobile/api.go
@@ -1,3 +1,5 @@
+// Implements gomobile bindings for go-waku. Contains a set of functions that
+// are exported when go-waku is exported as libraries for mobile devices
 package gowaku
 
 import (
diff --git a/tests/init.go b/tests/init.go
index ca8701d2..cdbbb0ab 100644
--- a/tests/init.go
+++ b/tests/init.go
@@ -1 +1,2 @@
+// Contains resources or utils for test units
 package tests
diff --git a/waku/options.go b/waku/options.go
index 9a3e447f..614e6b0e 100644
--- a/waku/options.go
+++ b/waku/options.go
@@ -6,16 +6,22 @@ import (
 	"github.com/urfave/cli/v2"
 )
 
+// RendezvousOptions are settings for enabling the rendezvous protocol for
+// discovering new nodes
 type RendezvousOptions struct {
 	Enable bool
 	Nodes  cli.StringSlice
 }
 
+// RendezvousServerOptions are settings to enable the waku node to act as a
+// rendezvous server
 type RendezvousServerOptions struct {
 	Enable bool
 	DBPath string
 }
 
+// DiscV5Options are settings to enable a modified version of Ethereum’s Node
+// Discovery Protocol v5 as a means for ambient node discovery.
 type DiscV5Options struct {
 	Enable     bool
 	Nodes      cli.StringSlice
@@ -23,6 +29,9 @@ type DiscV5Options struct {
 	AutoUpdate bool
 }
 
+// RelayOptions are settings to enable the relay protocol which is a pubsub
+// approach to peer-to-peer messaging with a strong focus on privacy,
+// censorship-resistance, security and scalability.
 type RelayOptions struct {
 	Enable                 bool
 	Topics                 cli.StringSlice
@@ -30,6 +39,10 @@ type RelayOptions struct {
 	MinRelayPeersToPublish int
 }
 
+// FilterOptions are settings used to enable filter protocol. This is a protocol
+// that enables subscribing to messages that a peer receives. This is a more
+// lightweight version of WakuRelay specifically designed for bandwidth
+// restricted devices.
 type FilterOptions struct {
 	Enable          bool
 	DisableFullNode bool
@@ -98,6 +111,8 @@ type RPCServerOptions struct {
 	Private bool
 }
 
+// WSOptions are settings used for enabling websockets and secure websockets
+// support
 type WSOptions struct {
 	Enable   bool
 	Port     int
diff --git a/waku/persistence/store.go b/waku/persistence/store.go
index 9502e740..a83faf62 100644
--- a/waku/persistence/store.go
+++ b/waku/persistence/store.go
@@ -71,6 +71,8 @@ func WithDriver(driverName string, datasourceName string) DBOption {
 	}
 }
 
+// WithRetentionPolicy is a DBOption that specifies the max number of messages
+// to be stored and duration before they're removed from the message store
 func WithRetentionPolicy(maxMessages int, maxDuration time.Duration) DBOption {
 	return func(d *DBStore) error {
 		d.maxDuration = maxDuration
@@ -182,14 +184,14 @@ func (d *DBStore) checkForOlderRecords(t time.Duration) {
 	}
 }
 
-// Closes a DB connection
+// Stop closes a DB connection
 func (d *DBStore) Stop() {
 	d.quit <- struct{}{}
 	d.wg.Wait()
 	d.db.Close()
 }
 
-// Inserts a WakuMessage into the DB
+// Put inserts a WakuMessage into the DB
 func (d *DBStore) Put(env *protocol.Envelope) error {
 	stmt, err := d.db.Prepare("INSERT INTO message (id, receiverTimestamp, senderTimestamp, contentTopic, pubsubTopic, payload, version) VALUES (?, ?, ?, ?, ?, ?, ?)")
 	if err != nil {
@@ -211,6 +213,7 @@ func (d *DBStore) Put(env *protocol.Envelope) error {
 	return nil
 }
 
+// Query retrieves messages from the DB
 func (d *DBStore) Query(query *pb.HistoryQuery) ([]StoredMessage, error) {
 	start := time.Now()
 	defer func() {
@@ -319,6 +322,8 @@ func (d *DBStore) Query(query *pb.HistoryQuery) ([]StoredMessage, error) {
 	return result, nil
 }
 
+// MostRecentTimestamp returns an unix timestamp with the most recent senderTimestamp
+// in the message table
 func (d *DBStore) MostRecentTimestamp() (int64, error) {
 	result := sql.NullInt64{}
 
@@ -329,7 +334,7 @@ func (d *DBStore) MostRecentTimestamp() (int64, error) {
 	return result.Int64, nil
 }
 
-// Returns all the stored WakuMessages
+// GetAll returns all the stored WakuMessages
 func (d *DBStore) GetAll() ([]StoredMessage, error) {
 	start := time.Now()
 	defer func() {
@@ -364,7 +369,8 @@ func (d *DBStore) GetAll() ([]StoredMessage, error) {
 	return result, nil
 }
 
-func (d *DBStore) GetStoredMessage(rows *sql.Rows) (StoredMessage, error) {
+// GetStoredMessage is a helper function used to convert a `*sql.Rows` into a `StoredMessage`
+func (d *DBStore) GetStoredMessage(row *sql.Rows) (StoredMessage, error) {
 	var id []byte
 	var receiverTimestamp int64
 	var senderTimestamp int64
@@ -373,7 +379,7 @@ func (d *DBStore) GetStoredMessage(rows *sql.Rows) (StoredMessage, error) {
 	var version uint32
 	var pubsubTopic string
 
-	err := rows.Scan(&id, &receiverTimestamp, &senderTimestamp, &contentTopic, &pubsubTopic, &payload, &version)
+	err := row.Scan(&id, &receiverTimestamp, &senderTimestamp, &contentTopic, &pubsubTopic, &payload, &version)
 	if err != nil {
 		d.log.Error("scanning messages from db", zap.Error(err))
 		return StoredMessage{}, err
diff --git a/waku/v2/dnsdisc/enr.go b/waku/v2/dnsdisc/enr.go
index b52371f1..5d71390c 100644
--- a/waku/v2/dnsdisc/enr.go
+++ b/waku/v2/dnsdisc/enr.go
@@ -17,7 +17,7 @@ type dnsDiscoveryParameters struct {
 
 type DnsDiscoveryOption func(*dnsDiscoveryParameters)
 
-// WithMultiaddress is a WakuNodeOption that configures libp2p to listen on a list of multiaddresses
+// WithNameserver is a DnsDiscoveryOption that configures the nameserver to use
 func WithNameserver(nameserver string) DnsDiscoveryOption {
 	return func(params *dnsDiscoveryParameters) {
 		params.nameserver = nameserver
diff --git a/waku/v2/protocol/lightpush/waku_lightpush.go b/waku/v2/protocol/lightpush/waku_lightpush.go
index dabe428c..5f43578e 100644
--- a/waku/v2/protocol/lightpush/waku_lightpush.go
+++ b/waku/v2/protocol/lightpush/waku_lightpush.go
@@ -18,6 +18,7 @@ import (
 	"go.uber.org/zap"
 )
 
+// LightPushID_v20beta1 is the current Waku Lightpush protocol identifier
 const LightPushID_v20beta1 = libp2pProtocol.ID("/vac/waku/lightpush/2.0.0-beta1")
 
 var (
diff --git a/waku/v2/protocol/lightpush/waku_lightpush_option.go b/waku/v2/protocol/lightpush/waku_lightpush_option.go
index 94a402ed..783d7029 100644
--- a/waku/v2/protocol/lightpush/waku_lightpush_option.go
+++ b/waku/v2/protocol/lightpush/waku_lightpush_option.go
@@ -19,12 +19,15 @@ type LightPushParameters struct {
 
 type LightPushOption func(*LightPushParameters)
 
+// WithPeer is an option used to specify the peerID to push a waku message to
 func WithPeer(p peer.ID) LightPushOption {
 	return func(params *LightPushParameters) {
 		params.selectedPeer = p
 	}
 }
 
+// WithAutomaticPeerSelection is an option used to randomly select a peer from the peer store
+// to push a waku message to
 func WithAutomaticPeerSelection(host host.Host) LightPushOption {
 	return func(params *LightPushParameters) {
 		p, err := utils.SelectPeer(host, string(LightPushID_v20beta1), params.log)
@@ -36,6 +39,8 @@ func WithAutomaticPeerSelection(host host.Host) LightPushOption {
 	}
 }
 
+// WithFastestPeerSelection is an option used to select a peer from the peer store
+// with the lowest ping
 func WithFastestPeerSelection(ctx context.Context) LightPushOption {
 	return func(params *LightPushParameters) {
 		p, err := utils.SelectPeerWithLowestRTT(ctx, params.host, string(LightPushID_v20beta1), params.log)
@@ -47,18 +52,23 @@ func WithFastestPeerSelection(ctx context.Context) LightPushOption {
 	}
 }
 
+// WithRequestId is an option to set a specific request ID to be used when
+// publishing a message
 func WithRequestId(requestId []byte) LightPushOption {
 	return func(params *LightPushParameters) {
 		params.requestId = requestId
 	}
 }
 
+// WithAutomaticRequestId is an option to automatically generate a request ID
+// when publishing a message
 func WithAutomaticRequestId() LightPushOption {
 	return func(params *LightPushParameters) {
 		params.requestId = protocol.GenerateRequestId()
 	}
 }
 
+// DefaultOptions are the default options to be used when using the lightpush protocol
 func DefaultOptions(host host.Host) []LightPushOption {
 	return []LightPushOption{
 		WithAutomaticRequestId(),
diff --git a/waku/v2/protocol/store/waku_store.go b/waku/v2/protocol/store/waku_store.go
index f35227cc..749bd1ea 100644
--- a/waku/v2/protocol/store/waku_store.go
+++ b/waku/v2/protocol/store/waku_store.go
@@ -279,7 +279,7 @@ func WithPeer(p peer.ID) HistoryRequestOption {
 	}
 }
 
-// WithAutomaticPeerSelection is an option used to randomly select a peer from the store
+// WithAutomaticPeerSelection is an option used to randomly select a peer from the peer store
 // to request the message history
 func WithAutomaticPeerSelection() HistoryRequestOption {
 	return func(params *HistoryRequestParameters) {
diff --git a/waku/v2/utils/crypto.go b/waku/v2/utils/crypto.go
index a7967d19..bcf3b603 100644
--- a/waku/v2/utils/crypto.go
+++ b/waku/v2/utils/crypto.go
@@ -7,6 +7,7 @@ import (
 	"github.com/libp2p/go-libp2p-core/crypto"
 )
 
+// EcdsaPubKeyToSecp256k1PublicKey converts an `ecdsa.PublicKey` into a libp2p `crypto.Secp256k1PublicKey``
 func EcdsaPubKeyToSecp256k1PublicKey(pubKey *ecdsa.PublicKey) *crypto.Secp256k1PublicKey {
 	xFieldVal := &btcec.FieldVal{}
 	yFieldVal := &btcec.FieldVal{}
@@ -15,6 +16,7 @@ func EcdsaPubKeyToSecp256k1PublicKey(pubKey *ecdsa.PublicKey) *crypto.Secp256k1P
 	return (*crypto.Secp256k1PublicKey)(btcec.NewPublicKey(xFieldVal, yFieldVal))
 }
 
+// EcdsaPubKeyToSecp256k1PublicKey converts an `ecdsa.PrivateKey` into a libp2p `crypto.Secp256k1PrivateKey``
 func EcdsaPrivKeyToSecp256k1PrivKey(privKey *ecdsa.PrivateKey) *crypto.Secp256k1PrivateKey {
 	privK, _ := btcec.PrivKeyFromBytes(privKey.D.Bytes())
 	return (*crypto.Secp256k1PrivateKey)(privK)
diff --git a/waku/v2/utils/enr.go b/waku/v2/utils/enr.go
index 490a9825..e3047893 100644
--- a/waku/v2/utils/enr.go
+++ b/waku/v2/utils/enr.go
@@ -206,6 +206,7 @@ func Multiaddress(node *enode.Node) ([]ma.Multiaddr, error) {
 	return result, nil
 }
 
+// EnodeToPeerInfo extracts the peer ID and multiaddresses defined in an ENR
 func EnodeToPeerInfo(node *enode.Node) (*peer.AddrInfo, error) {
 	addresses, err := Multiaddress(node)
 	if err != nil {
@@ -218,5 +219,4 @@ func EnodeToPeerInfo(node *enode.Node) (*peer.AddrInfo, error) {
 	}
 
 	return &res[0], nil
-
 }
diff --git a/waku/v2/utils/logger.go b/waku/v2/utils/logger.go
index 99b4afaf..a6472148 100644
--- a/waku/v2/utils/logger.go
+++ b/waku/v2/utils/logger.go
@@ -29,6 +29,7 @@ func Logger() *zap.Logger {
 	return log
 }
 
+// InitLogger initializes a global logger using an specific encoding
 func InitLogger(encoding string) {
 	cfg := zap.Config{
 		Encoding:         encoding,