diff --git a/auth_options.go b/auth_options.go
index bc0ef65..19ce5d4 100644
--- a/auth_options.go
+++ b/auth_options.go
@@ -1,20 +1,28 @@
 package gophercloud
 
-// AuthOptions allows anyone calling Authenticate to supply the required access
-// credentials. Its fields are the union of those recognized by each identity
-// implementation and provider.
+/*
+AuthOptions stores information needed to authenticate to an OpenStack cluster.
+You can populate one manually, or use a provider's AuthOptionsFromEnv() function
+to read relevant information from the standard environment variables. Pass one
+to a provider's AuthenticatedClient function to authenticate and obtain a
+ProviderClient representing an active session on that provider.
+
+Its fields are the union of those recognized by each identity implementation and
+provider.
+*/
 type AuthOptions struct {
 	// IdentityEndpoint specifies the HTTP endpoint that is required to work with
-	// the Identity API of the appropriate version. Required by the identity
-	// services, but often populated by a provider Client.
+	// the Identity API of the appropriate version. While it's ultimately needed by
+	// all of the identity services, it will often be populated by a provider-level
+	// function.
 	IdentityEndpoint string
 
 	// Username is required if using Identity V2 API. Consult with your provider's
 	// control panel to discover your account's username. In Identity V3, either
-	// UserID or a combination of Username and DomainID or DomainName.
+	// UserID or a combination of Username and DomainID or DomainName are needed.
 	Username, UserID string
 
-	// Exactly one of Password or ApiKey is required for the Identity V2 and V3
+	// Exactly one of Password or APIKey is required for the Identity V2 and V3
 	// APIs. Consult with your provider's control panel to discover your account's
 	// preferred method of authentication.
 	Password, APIKey string
@@ -25,7 +33,7 @@
 
 	// The TenantID and TenantName fields are optional for the Identity V2 API.
 	// Some providers allow you to specify a TenantName instead of the TenantId.
-	// Some require both.  Your provider's authentication policies will determine
+	// Some require both. Your provider's authentication policies will determine
 	// how these fields influence authentication.
 	TenantID, TenantName string
 
@@ -34,5 +42,7 @@
 	// re-authenticate automatically if/when your token expires.  If you set it to
 	// false, it will not cache these settings, but re-authentication will not be
 	// possible.  This setting defaults to false.
+	//
+	// This setting is speculative and is currently not respected!
 	AllowReauth bool
 }