os/user: document the difference between Username and Name

Fixes #18261.

Change-Id: I4bd7363aac4e62461f61fd95b3c7a18063412182
Reviewed-on: https://go-review.googlesource.com/34241
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

1 files changed, 22 insertions, 14 deletions

diff --git a/src/os/user/user.go b/src/os/user/user.go
index 7b44397afb..ad61992ad3 100644
--- a/src/os/user/user.go
+++ b/src/os/user/user.go
@@ -15,31 +15,39 @@ var (
 )
 
 // User represents a user account.
-//
-// On POSIX systems Uid and Gid contain a decimal number
-// representing uid and gid. On windows Uid and Gid
-// contain security identifier (SID) in a string format.
-// On Plan 9, Uid, Gid, Username, and Name will be the
-// contents of /dev/user.
 type User struct {
-	Uid      string // user ID
-	Gid      string // primary group ID
+	// Uid is the user ID.
+	// On POSIX systems, this is a decimal number representing the uid.
+	// On Windows, this is a security identifier (SID) in a string format.
+	// On Plan 9, this is the contents of /dev/user.
+	Uid string
+	// Gid is the primary group ID.
+	// On POSIX systems, this is a decimal number representing the gid.
+	// On Windows, this is a SID in a string format.
+	// On Plan 9, this is the contents of /dev/user.
+	Gid string
+	// Username is the login name.
 	Username string
-	Name     string
-	HomeDir  string
+	// Name is the user's real or display name.
+	// It might be blank.
+	// On POSIX systems, this is the first (or only) entry in the GECOS field
+	// list.
+	// On Windows, this is the user's display name.
+	// On Plan 9, this is the contents of /dev/user.
+	Name string
+	// HomeDir is the path to the user's home directory (if they have one).
+	HomeDir string
 }
 
 // Group represents a grouping of users.
 //
-// On POSIX systems Gid contains a decimal number
-// representing the group ID.
+// On POSIX systems Gid contains a decimal number representing the group ID.
 type Group struct {
 	Gid  string // group ID
 	Name string // group name
 }
 
-// UnknownUserIdError is returned by LookupId when
-// a user cannot be found.
+// UnknownUserIdError is returned by LookupId when a user cannot be found.
 type UnknownUserIdError int
 
 func (e UnknownUserIdError) Error() string {