diff --git a/auth_options.go b/auth_options.go
index f9e6ee5..bc0ef65 100644
--- a/auth_options.go
+++ b/auth_options.go
@@ -1,24 +1,26 @@
 package gophercloud
 
-// AuthOptions lets anyone calling Authenticate() supply the required access credentials.
-// Its fields are the union of those recognized by each identity implementation and provider.
+// 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.
 type AuthOptions struct {
-
-	// IdentityEndpoint specifies the HTTP endpoint offering the Identity API of the appropriate version.
-	// Required by the identity services, but often populated by a provider Client.
+	// 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.
 	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.
+	// 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.
 	Username, UserID string
 
-	// 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.
+	// 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
 
-	// At most one of DomainID and DomainName must be provided if using Username with Identity V3.
-	// Otherwise, either are optional.
+	// At most one of DomainID and DomainName must be provided if using Username
+	// with Identity V3. Otherwise, either are optional.
 	DomainID, DomainName string
 
 	// The TenantID and TenantName fields are optional for the Identity V2 API.
diff --git a/auth_results.go b/auth_results.go
index 07e0fc7..1a1faa5 100644
--- a/auth_results.go
+++ b/auth_results.go
@@ -5,10 +5,9 @@
 // AuthResults encapsulates the raw results from an authentication request. As OpenStack allows
 // extensions to influence the structure returned in ways that Gophercloud cannot predict at
 // compile-time, you should use type-safe accessors to work with the data represented by this type,
-// such as ServiceCatalog() and TokenID().
+// such as ServiceCatalog and TokenID.
 type AuthResults interface {
-
-	// Retrieve the authentication token's value from the authentication response.
+	// TokenID returns the token's ID value from the authentication response.
 	TokenID() (string, error)
 
 	// ExpiresAt retrieves the token's expiration time.
diff --git a/endpoint_search.go b/endpoint_search.go
index 828bcfd..b6f6b48 100644
--- a/endpoint_search.go
+++ b/endpoint_search.go
@@ -10,9 +10,9 @@
 	ErrEndpointNotFound = errors.New("No suitable endpoint could be found in the service catalog.")
 )
 
-// Availability describes the accessibility of a specific service endpoint.
-// Identity v2 lists these as different kinds of URLs ("adminURL", "internalURL", and "publicURL"), while
-// v3 lists them as "Interfaces".
+// Availability indicates whether a specific service endpoint is accessible.
+// Identity v2 lists these as different kinds of URLs ("adminURL",
+// "internalURL", and "publicURL"), while v3 lists them as "Interfaces".
 type Availability string
 
 const (
@@ -28,31 +28,33 @@
 
 // EndpointOpts contains options for finding an endpoint for an Openstack client.
 type EndpointOpts struct {
-
 	// Type is the service type for the client (e.g., "compute", "object-store").
-	// Type is a required field.
+	// Required.
 	Type string
 
-	// Name is the service name for the client (e.g., "nova").
-	// Name is not a required field, but it is used if present.
-	// Services can have the same Type but a different Name, which is one example of when both Type and Name are needed.
+	// Name is the service name for the client (e.g., "nova") as it appears in
+	// the service catalog. Services can have the same Type but a different Name,
+	// which is why both Type and Name are sometimes needed. Optional.
 	Name string
 
-	// Region is the region in which the service resides.
-	// Region must be specified for services that span multiple regions.
+	// Region is the geographic region in which the service resides. Required only
+	// for services that span multiple regions.
 	Region string
 
-	// Availability is the visibility of the endpoint to be returned: AvailabilityPublic, AvailabilityInternal, or AvailabilityAdmin.
+	// Availability is the visibility of the endpoint to be returned. Valid types
+	// are: AvailabilityPublic, AvailabilityInternal, or AvailabilityAdmin.
 	// Availability is not required, and defaults to AvailabilityPublic.
 	// Not all providers or services offer all Availability options.
 	Availability Availability
 }
 
-// EndpointLocator is a function that describes how to locate a single endpoint from a service catalog for a specific ProviderClient.
-// It should be set during ProviderClient authentication and used to discover related ServiceClients.
+// EndpointLocator is a function that describes how to locate a single endpoint
+// from a service catalog for a specific ProviderClient. It should be set
+// during ProviderClient authentication and used to discover related ServiceClients.
 type EndpointLocator func(EndpointOpts) (string, error)
 
-// ApplyDefaults sets EndpointOpts fields if not already set. Currently, EndpointOpts.Availability defaults to the public endpoint.
+// ApplyDefaults sets EndpointOpts fields if not already set. Currently,
+// EndpointOpts.Availability defaults to the public endpoint.
 func (eo *EndpointOpts) ApplyDefaults(t string) {
 	if eo.Type == "" {
 		eo.Type = t
diff --git a/params.go b/params.go
index 26c48c0..5fe3c2c 100644
--- a/params.go
+++ b/params.go
@@ -60,19 +60,21 @@
 	return v.Interface() == z.Interface()
 }
 
-// BuildQueryString accepts a generic structure and parses it URL struct. It
-// converts field names into query names based on tags. So for example, this
-// type:
-//
-// struct {
-//    Bar string `q:"x_bar"`
-//    Baz int    `q:"lorem_ipsum"`
-// }{
-//    Bar: "XXX",
-//    Baz: "YYY",
-// }
-//
-// will be converted into ?x_bar=XXX&lorem_ipsum=YYYY
+/*
+BuildQueryString accepts a generic structure and parses it URL struct. It
+converts field names into query names based on "q" tags. So for example, this
+type:
+
+	struct {
+	   Bar string `q:"x_bar"`
+	   Baz int    `q:"lorem_ipsum"`
+	}{
+	   Bar: "XXX",
+	   Baz: "YYY",
+	}
+
+will be converted into ?x_bar=XXX&lorem_ipsum=YYYY
+*/
 func BuildQueryString(opts interface{}) (*url.URL, error) {
 	optsValue := reflect.ValueOf(opts)
 	if optsValue.Kind() == reflect.Ptr {
@@ -130,7 +132,7 @@
 	return nil, fmt.Errorf("Options type is not a struct.")
 }
 
-// BuildHeaders accepts a generic structure and parses it string map. It
+// BuildHeaders accepts a generic structure and parses it into a string map. It
 // converts field names into header names based on "h" tags, and field values
 // into header values by a simple one-to-one mapping.
 func BuildHeaders(opts interface{}) (map[string]string, error) {
diff --git a/provider_client.go b/provider_client.go
index 2be665e..7754c20 100644
--- a/provider_client.go
+++ b/provider_client.go
@@ -1,29 +1,33 @@
 package gophercloud
 
-// ProviderClient stores details that are required to interact with any services within a specific provider's API.
+// ProviderClient stores details that are required to interact with any
+// services within a specific provider's API.
 //
-// Generally, you acquire a ProviderClient by calling the `NewClient()` method in the appropriate provider's child package,
-// providing whatever authentication credentials are required.
+// Generally, you acquire a ProviderClient by calling the NewClient method in
+// the appropriate provider's child package, providing whatever authentication
+// credentials are required.
 type ProviderClient struct {
-
-	// IdentityBase is the front door to an openstack provider.
-	// Generally this will be populated when you authenticate.
-	// It should be the *root* resource of the identity service, not of a specific identity version.
+	// IdentityBase is the base URL used for a particular provider's identity
+	// service - it will be used when issuing authenticatation requests. It
+	// should point to the root resource of the identity service, not a specific
+	// identity version.
 	IdentityBase string
 
-	// IdentityEndpoint is the originally requested identity endpoint.
-	// This may be a specific version of the identity service, in which case that endpoint is used rather than querying the
-	// version-negotiation endpoint.
+	// IdentityEndpoint is the identity endpoint. This may be a specific version
+	// of the identity service. If this is the case, this endpoint is used rather
+	// than querying versions first.
 	IdentityEndpoint string
 
-	// TokenID is the most recently valid token issued.
+	// TokenID is the ID of the most recently issued valid token.
 	TokenID string
 
-	// EndpointLocator describes how this provider discovers the endpoints for its constituent services.
+	// EndpointLocator describes how this provider discovers the endpoints for
+	// its constituent services.
 	EndpointLocator EndpointLocator
 }
 
-// AuthenticatedHeaders returns a map of HTTP headers that are common for all authenticated service requests.
+// AuthenticatedHeaders returns a map of HTTP headers that are common for all
+// authenticated service requests.
 func (client *ProviderClient) AuthenticatedHeaders() map[string]string {
 	return map[string]string{"X-Auth-Token": client.TokenID}
 }
diff --git a/results.go b/results.go
index 19557fb..a8e3705 100644
--- a/results.go
+++ b/results.go
@@ -39,7 +39,8 @@
 }
 
 // ExtractNextURL attempts to extract the next URL from a JSON structure. It
-// follows the common structure of nesting back and next links.
+// follows the common convention of nesting back and next URLs in a "links"
+// JSON array.
 func ExtractNextURL(links []Link) (string, error) {
 	var url string
 
diff --git a/util.go b/util.go
index 6f62944..7f5ead7 100644
--- a/util.go
+++ b/util.go
@@ -6,8 +6,8 @@
 	"time"
 )
 
-// WaitFor polls a predicate function once per second up to secs times to wait
-// for a certain state to arrive.
+// WaitFor polls a predicate function, once per second, up to a timeout limit.
+// It usually does this to wait for the resource to transition to a certain state.
 func WaitFor(timeout int, predicate func() (bool, error)) error {
 	start := time.Now().Second()
 	for {