From 8ae6e7f45c876ce5a34b603d627c2a84dd2cdc44 Mon Sep 17 00:00:00 2001
From: joshemb <josh@elixxir.io>
Date: Tue, 16 Aug 2022 19:36:27 -0700
Subject: [PATCH] Update UD documentation
---
bindings/ud.go | 59 ++++++++++++++++++++++++++++++++++----------------
1 file changed, 40 insertions(+), 19 deletions(-)
diff --git a/bindings/ud.go b/bindings/ud.go
index 7504992f4..89ae1d9db 100644
--- a/bindings/ud.go
+++ b/bindings/ud.go
@@ -105,28 +105,49 @@ type UdNetworkStatus interface {
// Manager functions //
////////////////////////////////////////////////////////////////////////////////
-// NewOrLoadUd loads an existing Manager from storage or creates a
-// new one if there is no extant storage information. Parameters need be provided
-// to specify how to connect to the User Discovery service. These parameters may be used
-// to contact either the UD server hosted by the xx network team or a custom
-// third-party operated server. For the former, all the information may be pulled from the
-// NDF using the bindings.
+// NewOrLoadUd loads an existing UserDiscovery from storage or creates a new
+// UserDiscovery if there is no storage data. Regardless of storage state,
+// the UserDiscovery object returned will be registered with the
+// User Discovery service. If the user is not already registered, a call
+// to register will occur internally. If the user is already registered,
+// this call will simply load state and return to you a UserDiscovery object.
+// Some parameters are required for registering with the service, but are not required
+// if the user is already registered. These will be noted in the parameters section as
+// "SEMI-REQUIRED".
+//
+// Certain parameters are required every call to this function. These parameters are listed below
+// as "REQUIRED". For example, parameters need be provided to specify how to connect to the
+// User Discovery service. These parameters may be used to contact either the UD server hosted
+// by the xx network team or a custom third-party operated server. For the former,
+// all the information may be fetched from the NDF using the bindings. These fetch
+// methods are detailed in the parameters section.
//
// Params
-// - e2eID - e2e object ID in the tracker
-// - follower - network follower func wrapped in UdNetworkStatus
-// - username - the username the user wants to register with UD.
-// If the user is already registered, this field may be blank
-// - networkValidationSig is a signature provided by the network (i.e. the client registrar).
-// This may be nil, however UD may return an error in some cases (e.g. in a production level
-// environment).
-// - cert is the TLS certificate for the UD server this call will connect with.
-// You may use the UD server run by the xx network team by using E2e.GetUdCertFromNdf.
-// - contactFile is the data within a marshalled contact.Contact. This represents the
+// - e2eID - REQUIRED. The tracked e2e object ID. This is returned by [E2e.GetID].
+// - follower - REQUIRED. Network follower function. This will check if the network
+// follower is running.
+// - username - SEMI-REQUIRED. The username the user wants to register with UD.
+// If the user is already registered, this field may be blank. If the user is not
+// already registered, these field must be populated with a username that meets the
+// requirements of the UD service. For example, in the xx network's UD service,
+// the username must not be registered by another user.
+// - networkValidationSig - SEMI-REQUIRED. A signature provided by the xx network
+// (i.e. the client registrar). If the user is not already registered, this field is required
+// in order to register with the xx network. This may be nil if the user is already registered
+// or connecting to a third-party UD service unassociated with the xx network.
+// - cert - REQUIRED. The TLS certificate for the UD server this call will connect with.
+// If this is nil, you may not contact the UD server hosted by the xx network.
+// Third-party services may vary.
+// You may use the UD server run by the xx network team by using [E2e.GetUdCertFromNdf].
+// - contactFile - REQUIRED. The data within a marshalled [contact.Contact]. This represents the
// contact file of the server this call will connect with.
-// You may use the UD server run by the xx network team by using E2e.GetUdContactFromNdf.
-// - address is the IP address of the UD server this call will connect with.
-// You may use the UD server run by the xx network team by using E2e.GetUdAddressFromNdf.
+// If this is nil, you may not contact the UD server hosted by the xx network.
+// Third-party services may vary.
+// You may use the UD server run by the xx network team by using [E2e.GetUdContactFromNdf].
+// - address - REQUIRED. The IP address of the UD server this call will connect with.
+// You may use the UD server run by the xx network team by using [E2e.GetUdAddressFromNdf].
+// If this is nil, you may not contact the UD server hosted by the xx network.
+// Third-party services may vary.
//
// Returns
// - A Manager object which is registered to the specified UD service.
--
GitLab