Touch up AuthOptions docs a little.
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
}