chore(manager): improve comments

Author: ndyakov

manager/entraid_manager.go

@@ -223,12 +223,14 @@ func (e *entraidTokenManager) stop() (err error) {
 			err = fmt.Errorf("failed to stop token manager: %s", r)
 		}
 	}()
+	if e.ctxCancel != nil {
+		e.ctxCancel()
+	}
 
 	if e.closedChan == nil || e.listener == nil {
 		return ErrTokenManagerAlreadyStopped
 	}
 
-	e.ctxCancel()
 	e.listener = nil
 	close(e.closedChan)
 

token/token.go

@@ -11,7 +11,10 @@ var _ auth.Credentials = (*Token)(nil)
 
 // New creates a new token with the specified username, password, raw token, expiration time, received at time, and time to live.
 // NOTE: This won't do any validation on the token, expiresOn, receivedAt, or ttl. It will simply create a new token instance.
-// ttl is in milliseconds.
+// The caller is responsible for ensuring the token is valid.
+// Expiration time and TTL are used to determine when the token should be refreshed.
+// TTL is in milliseconds.
+// receivedAt + ttl should be within a millisecond of expiresOn
 func New(username, password, rawToken string, expiresOn, receivedAt time.Time, ttl int64) *Token {
 	return &Token{
 		username:   username,
@@ -32,11 +35,11 @@ type Token struct {
 	password string
 	// expiresOn is the expiration time of the token.
 	expiresOn time.Time
-	// ttl is the time to live of the token.
+	// ttl is the time to live of the token in milliseconds.
 	ttl int64
 	// rawToken is the authentication token.
 	rawToken string
-	// receivedAt is the time when the token was received.
+	// receivedAt is the time when the token was received
 	receivedAt time.Time
 }