client/tailscale/apitype,tailcfg: document WhoIsResponse fields

Updates #cleanup

Signed-off-by: Maisem Ali <maisem@tailscale.com>

client/tailscale/apitype/apitype.go

@@ -10,9 +10,16 @@ import "tailscale.com/tailcfg"
 const LocalAPIHost = "local-tailscaled.sock"
 
 // WhoIsResponse is the JSON type returned by tailscaled debug server's /whois?ip=$IP handler.
-// In successful whois responses, Node and UserProfile are never nil.
 type WhoIsResponse struct {
-	Node        *tailcfg.Node
+	// Node is the node that the IP address belongs to.
+	//
+	// It is always non-nil in successful responses.
+	Node *tailcfg.Node
+
+	// UserProfile is the profile of the Node.User if the node is not tagged.
+	// For tagged nodes, the profile should be ignored.
+	//
+	// It is always non-nil in successful responses.
 	UserProfile *tailcfg.UserProfile
 
 	// CapMap is a map of capabilities to their values.

tailcfg/tailcfg.go

@@ -221,9 +221,12 @@ type Node struct {
 	// e.g. "host.tail-scale.ts.net."
 	Name string
 
-	// User is the user who created the node. If ACL tags are in
-	// use for the node then it doesn't reflect the ACL identity
-	// that the node is running as.
+	// User represents the owner of an untagged node. This field should be
+	// ignored for tagged nodes, as the value is undefined and may change in the
+	// future.
+	//
+	// To support old clients, the value is used to group all tagged nodes
+	// together for UI purposes and to circumvent isSelf checks for the PeerAPI.
 	User UserID
 
 	// Sharer, if non-zero, is the user who shared this node, if different than User.