Merge branch 'XX-4125/TrackServicesCallbackImproveDocs' into 'release'

XX-4125 / Fix Ambiguous documentation for TrackServicesCallback

See merge request !362

bindings/follow.go

@@ -27,29 +27,28 @@ import (
 // they are stopped if there is no internet access.
 //
 // Threads Started:
-//   - Network Follower (/network/follow.go)
-//     tracks the network events and hands them off to workers for handling.
-//   - Historical Round Retrieval (/network/rounds/historical.go)
-//     retrieves data about rounds that are too old to be stored by the client.
-//	 - Message Retrieval Worker Group (/network/rounds/retrieve.go)
-//	   requests all messages in a given round from the gateway of the last
-//	   nodes.
-//	 - Message Handling Worker Group (/network/message/handle.go)
-//	   decrypts and partitions messages when signals via the Switchboard.
-//	 - Health Tracker (/network/health),
-//	   via the network instance, tracks the state of the network.
-//	 - Garbled Messages (/network/message/garbled.go)
-//	   can be signaled to check all recent messages that could be decoded. It
-//	   uses a message store on disk for persistence.
-//	 - Critical Messages (/network/message/critical.go)
-//	   ensures all protocol layer mandatory messages are sent. It uses a message
-//	   store on disk for persistence.
-//	 - KeyExchange Trigger (/keyExchange/trigger.go)
-//	   responds to sent rekeys and executes them.
-//   - KeyExchange Confirm (/keyExchange/confirm.go)
-//	   responds to confirmations of successful rekey operations.
-//   - Auth Callback (/auth/callback.go)
-//     handles both auth confirm and requests.
+//  - Network Follower (/network/follow.go)
+//    tracks the network events and hands them off to workers for handling.
+//  - Historical Round Retrieval (/network/rounds/historical.go)
+//    retrieves data about rounds that are too old to be stored by the client.
+//  - Message Retrieval Worker Group (/network/rounds/retrieve.go)
+//	  requests all messages in a given round from the gateway of the last nodes.
+//  - Message Handling Worker Group (/network/message/handle.go)
+//	  decrypts and partitions messages when signals via the Switchboard.
+//	- Health Tracker (/network/health),
+//	  via the network instance, tracks the state of the network.
+//  - Garbled Messages (/network/message/garbled.go)
+//	  can be signaled to check all recent messages that could be decoded. It
+//	  uses a message store on disk for persistence.
+//	- Critical Messages (/network/message/critical.go)
+//	  ensures all protocol layer mandatory messages are sent. It uses a message
+//	  store on disk for persistence.
+//	- KeyExchange Trigger (/keyExchange/trigger.go)
+//	  responds to sent rekeys and executes them.
+//  - KeyExchange Confirm (/keyExchange/confirm.go)
+//	  responds to confirmations of successful rekey operations.
+//  - Auth Callback (/auth/callback.go)
+//    handles both auth confirm and requests.
 func (c *Cmix) StartNetworkFollower(timeoutMS int) error {
 	timeout := time.Duration(timeoutMS) * time.Millisecond
 	return c.api.StartNetworkFollower(timeout)
@@ -170,35 +169,39 @@ func (c *Cmix) RegisterClientErrorCallback(clientError ClientError) {
 	}()
 }
 
-// TrackServicesCallback is the callback for Cmix.TrackServices.
+// TrackServicesCallback is the callback for [Cmix.TrackServices].
 // This will pass to the user a JSON-marshalled list of backend services.
 // If there was an error retrieving or marshalling the service list,
 // there is an error for the second parameter which will be non-null.
 //
-// Example JSON:
+// Parameters:
+//  - marshalData - JSON marshalled bytes of [message.ServiceList], which is an
+//    array of [id.ID] and [message.Service].
+//  - err - JSON unmarshalling error
 //
-// [
-//  {
-//    "Id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD",
-//    "Services": [
-//      {
-//        "Identifier": null,
-//        "Tag": "test",
-//        "Metadata": null
-//      }
-//    ]
-//  },
-//  {
-//    "Id": "AAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD",
-//    "Services": [
-//      {
-//        "Identifier": null,
-//        "Tag": "test",
-//        "Metadata": null
-//      }
-//    ]
-//  },
-//]
+// Example JSON:
+//  [
+//    {
+//      "Id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD", // bytes of id.ID encoded as base64 string
+//      "Services": [
+//        {
+//          "Identifier": "AQID",                             // bytes encoded as base64 string
+//          "Tag": "TestTag 1",                               // string
+//          "Metadata": "BAUG"                                // bytes encoded as base64 string
+//        }
+//      ]
+//    },
+//    {
+//      "Id": "AAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD",
+//      "Services": [
+//        {
+//          "Identifier": "AQID",
+//          "Tag": "TestTag 2",
+//          "Metadata": "BAUG"
+//        }
+//      ]
+//    },
+//  ]
 type TrackServicesCallback interface {
 	Callback(marshalData []byte, err error)
 }
@@ -209,8 +212,8 @@ type TrackServicesCallback interface {
 // may need context on the available services for this client.
 //
 // Parameters:
-//   - cb - A TrackServicesCallback, which will be passed the marshalled
-//     message.ServiceList.
+//  - cb - A TrackServicesCallback, which will be passed the marshalled
+//    message.ServiceList.
 func (c *Cmix) TrackServices(cb TrackServicesCallback) {
 	c.api.GetCmix().TrackServices(func(list message.ServiceList) {
 		cb.Callback(json.Marshal(list))

bindings/notifications.go

@@ -13,58 +13,58 @@ import (
 	"gitlab.com/elixxir/primitives/notifications"
 )
 
-// NotificationReports is a list of NotificationReport's. This will be returned
+// NotificationReports is a list of [NotificationReport]s. This will be returned
 // via GetNotificationsReport as a JSON marshalled byte data.
 //
 // Example JSON:
-//
-// [
-//  {
-//    "ForMe": true,
-//    "Type": "e2e",
-//    "Source": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD"
-//  },
-//  {
-//    "ForMe": true,
-//    "Type": "e2e",
-//    "Source": "AAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD"
-//  },
-//  {
-//    "ForMe": true,
-//    "Type": "e2e",
-//    "Source": "AAAAAAAAAAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD"
-//  }
-//]
+//  [
+//    {
+//      "ForMe": true,                                           // boolean
+//      "Type": "e2e",                                           // string
+//      "Source": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD" // bytes of id.ID encoded as base64 string
+//    },
+//    {
+//      "ForMe": true,
+//      "Type": "e2e",
+//      "Source": "AAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD"
+//    },
+//    {
+//      "ForMe": true,
+//      "Type": "e2e",
+//      "Source": "AAAAAAAAAAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD"
+//    }
+//  ]
 type NotificationReports []NotificationReport
 
+//  TODO: The table in the docstring below needs to be checked for completeness
+//   and/or accuracy to ensure descriptions/sources are still accurate (they are
+//   from the old implementation).
+
 // NotificationReport is the bindings' representation for notifications for
 // this user.
 //
 // Example NotificationReport JSON:
-//
-// {
-//  "ForMe": true,
-//  "Type": "e2e",
-//  "Source": "dGVzdGVyMTIzAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
-//}
+//  {
+//    "ForMe": true,
+//    "Type": "e2e",
+//    "Source": "dGVzdGVyMTIzAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
+//  }
 //
 // Given the Type, the Source value will have specific contextual meanings.
 // Below is a table that will define the contextual meaning of the Source field
 // given all possible Type fields.
 //
-//      TYPE     |     SOURCE         |    DESCRIPTION
-//     ________________________________________________________________________________________
-//     "default" |  recipient user ID |  A message with no association.
-//	   "request" |  sender user ID    |  A channel request has been received, from Source.
-//     "reset"   |  sender user ID    |  A channel reset has been received.
-//     "confirm" |  sender user ID    |  A channel request has been accepted.
-//     "silent"  |  sender user ID    |  A message where the user should not be notified.
-//     "e2e"     |  sender user ID    |  A reception of an E2E message.
-//     "group"   |  group ID          |  A reception of a group chat message.
-//     "endFT"   |  sender user ID    |  The last message sent confirming end of file transfer.
-//     "groupRQ" |  sender user ID    |  A request from Source to join a group chat.
-//  todo iterate over this docstring, ensure descriptions/sources are
-//    still accurate (they are from the old implementation
+//   TYPE     |     SOURCE         |    DESCRIPTION
+//  ----------+--------------------+--------------------------------------------------------
+//  "default" |  recipient user ID |  A message with no association.
+//  "request" |  sender user ID    |  A channel request has been received, from Source.
+//  "reset"   |  sender user ID    |  A channel reset has been received.
+//  "confirm" |  sender user ID    |  A channel request has been accepted.
+//  "silent"  |  sender user ID    |  A message where the user should not be notified.
+//  "e2e"     |  sender user ID    |  A reception of an E2E message.
+//  "group"   |  group ID          |  A reception of a group chat message.
+//  "endFT"   |  sender user ID    |  The last message sent confirming end of file transfer.
+//  "groupRQ" |  sender user ID    |  A request from Source to join a group chat.
 type NotificationReport struct {
 	// ForMe determines whether this value is for the user. If it is
 	// false, this report may be ignored.

xxdk/cmix.go

@@ -340,29 +340,28 @@ func (c *Cmix) GetErrorsChannel() <-chan interfaces.ClientError {
 // they are stopped if there is no internet access.
 //
 // Threads Started:
-//   - Network Follower (/network/follow.go)
-//     tracks the network events and hands them off to workers for handling.
-//   - Historical Round Retrieval (/network/rounds/historical.go)
-// 	   retrieves data about rounds that are too old to be stored by the client.
-//	 - Message Retrieval Worker Group (/network/rounds/retrieve.go)
-//	   requests all messages in a given round from the gateway of the last
-//	   nodes.
-//	 - Message Handling Worker Group (/network/message/handle.go)
-//	   decrypts and partitions messages when signals via the Switchboard.
-//	 - Health Tracker (/network/health),
-//	   via the network instance, tracks the state of the network.
-//	 - Garbled Messages (/network/message/garbled.go)
-//	   can be signaled to check all recent messages that could be decoded. It
-//	   uses a message store on disk for persistence.
-//	 - Critical Messages (/network/message/critical.go)
-//	   ensures all protocol layer mandatory messages are sent. It uses a
-//	   message store on disk for persistence.
-//	 - KeyExchange Trigger (/keyExchange/trigger.go)
-//	   responds to sent rekeys and executes them.
-//   - KeyExchange Confirm (/keyExchange/confirm.go)
-//	   responds to confirmations of successful rekey operations.
-//   - Auth Callback (/auth/callback.go)
-//     handles both auth confirm and requests.
+//  - Network Follower (/network/follow.go)
+//    tracks the network events and hands them off to workers for handling.
+//  - Historical Round Retrieval (/network/rounds/historical.go)
+//    retrieves data about rounds that are too old to be stored by the client.
+//  - Message Retrieval Worker Group (/network/rounds/retrieve.go)
+//	  requests all messages in a given round from the gateway of the last nodes.
+//  - Message Handling Worker Group (/network/message/handle.go)
+//	  decrypts and partitions messages when signals via the Switchboard.
+//	- Health Tracker (/network/health),
+//	  via the network instance, tracks the state of the network.
+//  - Garbled Messages (/network/message/garbled.go)
+//	  can be signaled to check all recent messages that could be decoded. It
+//	  uses a message store on disk for persistence.
+//	- Critical Messages (/network/message/critical.go)
+//	  ensures all protocol layer mandatory messages are sent. It uses a message
+//	  store on disk for persistence.
+//	- KeyExchange Trigger (/keyExchange/trigger.go)
+//	  responds to sent rekeys and executes them.
+//  - KeyExchange Confirm (/keyExchange/confirm.go)
+//	  responds to confirmations of successful rekey operations.
+//  - Auth Callback (/auth/callback.go)
+//    handles both auth confirm and requests.
 func (c *Cmix) StartNetworkFollower(timeout time.Duration) error {
 	jww.INFO.Printf(
 		"StartNetworkFollower() \n\tTransmissionID: %s \n\tReceptionID: %s",