From ddaacf0a5731aba02cb7ccda4004d8f8f7802224 Mon Sep 17 00:00:00 2001
From: Brad Fitzpatrick <bradfitz@tailscale.com>
Date: Wed, 31 Mar 2021 08:25:39 -0700
Subject: [PATCH] control/controlclient: document a few things

Signed-off-by: Brad Fitzpatrick <bradfitz@tailscale.com>
---
 control/controlclient/auto.go   | 10 +++++++++-
 control/controlclient/direct.go |  7 +++++--
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/control/controlclient/auto.go b/control/controlclient/auto.go
index c731666e1..9366bb4b0 100644
--- a/control/controlclient/auto.go
+++ b/control/controlclient/auto.go
@@ -404,7 +404,7 @@ func (c *Client) authRoutine() {
 				continue
 			} else if url != "" {
 				if goal.url != "" {
-					err = fmt.Errorf("weird: server required a new url?")
+					err = fmt.Errorf("[unexpected] server required a new URL?")
 					report(err, "WaitLoginURL")
 				}
 
@@ -590,6 +590,7 @@ func (c *Client) AuthCantContinue() bool {
 	return !c.loggedIn && (c.loginGoal == nil || c.loginGoal.url != "")
 }
 
+// SetStatusFunc sets fn as the callback to run on any status change.
 func (c *Client) SetStatusFunc(fn func(Status)) {
 	c.mu.Lock()
 	c.statusFunc = fn
@@ -693,6 +694,13 @@ func (c *Client) Logout() {
 	c.cancelAuth()
 }
 
+// UpdateEndpoints sets the client's discovered endpoints and sends
+// them to the control server if they've changed.
+//
+// It does not retain the provided slice.
+//
+// The localPort field is unused except for integration tests in
+// another repo.
 func (c *Client) UpdateEndpoints(localPort uint16, endpoints []string) {
 	changed := c.direct.SetEndpoints(localPort, endpoints)
 	if changed {
diff --git a/control/controlclient/direct.go b/control/controlclient/direct.go
index 47c53ee47..228345806 100644
--- a/control/controlclient/direct.go
+++ b/control/controlclient/direct.go
@@ -270,12 +270,15 @@ func (c *Direct) TryLogin(ctx context.Context, t *tailcfg.Oauth2Token, flags Log
 	return c.doLoginOrRegen(ctx, t, flags, false, "")
 }
 
-func (c *Direct) WaitLoginURL(ctx context.Context, url string) (newUrl string, err error) {
+// WaitLoginURL sits in a long poll waiting for the user to authenticate at url.
+//
+// On success, newURL and err will both be nil.
+func (c *Direct) WaitLoginURL(ctx context.Context, url string) (newURL string, err error) {
 	c.logf("direct.WaitLoginURL")
 	return c.doLoginOrRegen(ctx, nil, LoginDefault, false, url)
 }
 
-func (c *Direct) doLoginOrRegen(ctx context.Context, t *tailcfg.Oauth2Token, flags LoginFlags, regen bool, url string) (newUrl string, err error) {
+func (c *Direct) doLoginOrRegen(ctx context.Context, t *tailcfg.Oauth2Token, flags LoginFlags, regen bool, url string) (newURL string, err error) {
 	mustregen, url, err := c.doLogin(ctx, t, flags, regen, url)
 	if err != nil {
 		return url, err