Finish DB docs for Rackspace

Author: Jamie Hannaford

rackspace/db/v1/backups/doc.go

@@ -1 +1,6 @@
+// Package backups provides information and interaction with the backup API
+// resource in the Rackspace Database service.
+//
+// A backup is a copy of a database instance that can be used to restore it to
+// some defined point in history.
 package backups

rackspace/db/v1/backups/requests.go

@@ -7,18 +7,25 @@ import (
 	"github.com/rackspace/gophercloud/pagination"
 )
 
+// CreateOptsBuilder is the top-level interface for creating JSON maps.
 type CreateOptsBuilder interface {
 	ToBackupCreateMap() (map[string]interface{}, error)
 }
 
+// CreateOpts is responsible for configuring newly provisioned backups.
 type CreateOpts struct {
+	// [REQUIRED] The name of the backup. The only restriction is the name must
+	// be less than 64 characters long.
 	Name string
 
+	// [REQUIRED] The ID of the instance being backed up.
 	InstanceID string
 
+	// [OPTIONAL] A human-readable explanation of the backup.
 	Description string
 }
 
+// ToBackupCreateMap will create a JSON map for the Create operation.
 func (opts CreateOpts) ToBackupCreateMap() (map[string]interface{}, error) {
 	if opts.Name == "" {
 		return nil, errors.New("Name is a required field")
@@ -39,6 +46,17 @@ func (opts CreateOpts) ToBackupCreateMap() (map[string]interface{}, error) {
 	return map[string]interface{}{"backup": backup}, nil
 }
 
+// Create asynchronously creates a new backup for a specified database instance.
+// During the backup process, write access on MyISAM databases will be
+// temporarily disabled; innoDB databases will be unaffected. During this time,
+// you will not be able to add or delete databases or users; nor delete, stop
+// or reboot the instance itself. Only one backup is permitted at once.
+//
+// Backups are not deleted when database instances are deleted; you must
+// manually delete any backups created using Delete(). Backups are saved to your
+// Cloud Files account in a new container called z_CLOUDDB_BACKUPS. It is
+// strongly recommended you do not alter this container or its contents; usual
+// storage costs apply.
 func Create(client *gophercloud.ServiceClient, opts CreateOptsBuilder) CreateResult {
 	var res CreateResult
 
@@ -57,14 +75,18 @@ func Create(client *gophercloud.ServiceClient, opts CreateOptsBuilder) CreateRes
 	return res
 }
 
+// ListOptsBuilder is the top-level interface for creating query strings.
 type ListOptsBuilder interface {
 	ToBackupListQuery() (string, error)
 }
 
+// ListOpts allows you to refine a list search by certain parameters.
 type ListOpts struct {
+	// The type of datastore by which to filter.
 	Datastore string `q:"datastore"`
 }
 
+// ToBackupListQuery converts a ListOpts struct into a query string.
 func (opts ListOpts) ToBackupListQuery() (string, error) {
 	q, err := gophercloud.BuildQueryString(opts)
 	if err != nil {
@@ -73,6 +95,7 @@ func (opts ListOpts) ToBackupListQuery() (string, error) {
 	return q.String(), nil
 }
 
+// List will list all the saved backups for all database instances.
 func List(client *gophercloud.ServiceClient, opts ListOptsBuilder) pagination.Pager {
 	url := baseURL(client)
 
@@ -91,6 +114,7 @@ func List(client *gophercloud.ServiceClient, opts ListOptsBuilder) pagination.Pa
 	return pagination.NewPager(client, url, pageFn)
 }
 
+// Get will retrieve details for a particular backup based on its unique ID.
 func Get(client *gophercloud.ServiceClient, id string) GetResult {
 	var res GetResult
 
@@ -102,6 +126,7 @@ func Get(client *gophercloud.ServiceClient, id string) GetResult {
 	return res
 }
 
+// Delete will permanently delete a backup.
 func Delete(client *gophercloud.ServiceClient, id string) DeleteResult {
 	var res DeleteResult
 

rackspace/db/v1/backups/results.go

@@ -7,6 +7,19 @@ import (
 	"github.com/rackspace/gophercloud/rackspace/db/v1/datastores"
 )
 
+// Status represents the various states a Backup can be in.
+type Status string
+
+// Enum types for the status.
+const (
+	StatusNew          Status = "NEW"
+	StatusBuilding     Status = "BUILDING"
+	StatusCompleted    Status = "COMPLETED"
+	StatusFailed       Status = "FAILED"
+	StatusDeleteFailed Status = "DELETE_FAILED"
+)
+
+// Backup represents a Backup API resource.
 type Backup struct {
 	Description string
 	ID          string
@@ -15,24 +28,32 @@ type Backup struct {
 	Name        string
 	ParentID    string `json:"parent_id" mapstructure:"parent_id"`
 	Size        float64
-	Status      string
+	Status      Status
 	Created     string
 	Updated     string
 	Datastore   datastores.DatastorePartial
 }
 
+// CreateResult represents the result of a create operation.
 type CreateResult struct {
 	commonResult
 }
 
+// GetResult represents the result of a get operation.
 type GetResult struct {
 	commonResult
 }
 
+// DeleteResult represents the result of a delete operation.
+type DeleteResult struct {
+	gophercloud.ErrResult
+}
+
 type commonResult struct {
 	gophercloud.Result
 }
 
+// Extract will retrieve a Backup struct from an operation's result.
 func (r commonResult) Extract() (*Backup, error) {
 	if r.Err != nil {
 		return nil, r.Err
@@ -46,10 +67,7 @@ func (r commonResult) Extract() (*Backup, error) {
 	return &response.Backup, err
 }
 
-type DeleteResult struct {
-	gophercloud.ErrResult
-}
-
+// BackupPage represents a page of backups.
 type BackupPage struct {
 	pagination.SinglePageBase
 }
@@ -63,6 +81,7 @@ func (r BackupPage) IsEmpty() (bool, error) {
 	return len(is) == 0, nil
 }
 
+// ExtractBackups will retrieve a slice of Backup structs from a paginated collection.
 func ExtractBackups(page pagination.Page) ([]Backup, error) {
 	casted := page.(BackupPage).Body
 

rackspace/db/v1/configurations/doc.go

@@ -1 +1,11 @@
+// Package configurations provides information and interaction with the
+// configuration API resource in the Rackspace Database service.
+//
+// A configuration group is a collection of key/value pairs which define how a
+// particular database operates. These key/value pairs are specific to each
+// datastore type and serve like settings. Some directives are capable of being
+// applied dynamically, while other directives require a server restart to take
+// effect. The configuration group can be applied to an instance at creation or
+// applied to an existing instance to modify the behavior of the running
+// datastore on the instance.
 package configurations

rackspace/db/v1/configurations/requests.go

@@ -8,6 +8,7 @@ import (
 	"github.com/rackspace/gophercloud/pagination"
 )
 
+// List will list all of the available configurations.
 func List(client *gophercloud.ServiceClient) pagination.Pager {
 	pageFn := func(r pagination.PageResult) pagination.Page {
 		return ConfigPage{pagination.SinglePageBase(r)}
@@ -16,15 +17,22 @@ func List(client *gophercloud.ServiceClient) pagination.Pager {
 	return pagination.NewPager(client, baseURL(client), pageFn)
 }
 
+// CreateOptsBuilder is a top-level interface which renders a JSON map.
 type CreateOptsBuilder interface {
 	ToConfigCreateMap() (map[string]interface{}, error)
 }
 
+// DatastoreOpts is the primary options struct for creating and modifying
+// how configuration resources are associated with datastores.
 type DatastoreOpts struct {
-	Type    string
+	// [OPTIONAL] The type of datastore. Defaults to "MySQL".
+	Type string
+
+	// [OPTIONAL] The specific version of a datastore. Defaults to "5.6".
 	Version string
 }
 
+// ToMap renders a JSON map for a datastore setting.
 func (opts DatastoreOpts) ToMap() (map[string]string, error) {
 	datastore := map[string]string{}
 
@@ -39,13 +47,24 @@ func (opts DatastoreOpts) ToMap() (map[string]string, error) {
 	return datastore, nil
 }
 
+// CreateOpts is the struct responsible for configuring new configurations.
 type CreateOpts struct {
-	Datastore   *DatastoreOpts
+	// [REQUIRED] The configuration group name
+	Name string
+
+	// [REQUIRED] A map of user-defined configuration settings that will define
+	// how each associated datastore works. Each key/value pair is specific to a
+	// datastore type.
+	Values map[string]interface{}
+
+	// [OPTIONAL] Associates the configuration group with a particular datastore.
+	Datastore *DatastoreOpts
+
+	// [OPTIONAL] A human-readable explanation for the group.
 	Description string
-	Name        string
-	Values      map[string]interface{}
 }
 
+// ToConfigCreateMap casts a CreateOpts struct into a JSON map.
 func (opts CreateOpts) ToConfigCreateMap() (map[string]interface{}, error) {
 	if opts.Name == "" {
 		return nil, errors.New("Name is a required field")
@@ -74,6 +93,7 @@ func (opts CreateOpts) ToConfigCreateMap() (map[string]interface{}, error) {
 	return map[string]interface{}{"configuration": config}, nil
 }
 
+// Create will create a new configuration group.
 func Create(client *gophercloud.ServiceClient, opts CreateOptsBuilder) CreateResult {
 	var res CreateResult
 
@@ -92,6 +112,7 @@ func Create(client *gophercloud.ServiceClient, opts CreateOptsBuilder) CreateRes
 	return res
 }
 
+// Get will retrieve the details for a specified configuration group.
 func Get(client *gophercloud.ServiceClient, configID string) GetResult {
 	var res GetResult
 
@@ -103,17 +124,30 @@ func Get(client *gophercloud.ServiceClient, configID string) GetResult {
 	return res
 }
 
+// UpdateOptsBuilder is the top-level interface for casting update options into
+// JSON maps.
 type UpdateOptsBuilder interface {
 	ToConfigUpdateMap() (map[string]interface{}, error)
 }
 
+// UpdateOpts is the struct responsible for modifying existing configurations.
 type UpdateOpts struct {
-	Datastore   *DatastoreOpts
+	// [OPTIONAL] The configuration group name
+	Name string
+
+	// [OPTIONAL] A map of user-defined configuration settings that will define
+	// how each associated datastore works. Each key/value pair is specific to a
+	// datastore type.
+	Values map[string]interface{}
+
+	// [OPTIONAL] Associates the configuration group with a particular datastore.
+	Datastore *DatastoreOpts
+
+	// [OPTIONAL] A human-readable explanation for the group.
 	Description string
-	Name        string
-	Values      map[string]interface{}
 }
 
+// ToConfigUpdateMap will cast an UpdateOpts struct into a JSON map.
 func (opts UpdateOpts) ToConfigUpdateMap() (map[string]interface{}, error) {
 	config := map[string]interface{}{}
 
@@ -140,6 +174,9 @@ func (opts UpdateOpts) ToConfigUpdateMap() (map[string]interface{}, error) {
 	return map[string]interface{}{"configuration": config}, nil
 }
 
+// Update will modify an existing configuration group by performing a merge
+// between new and existing values. If the key already exists, the new value
+// will overwrite. All other keys will remain unaffected.
 func Update(client *gophercloud.ServiceClient, configID string, opts UpdateOptsBuilder) UpdateResult {
 	var res UpdateResult
 
@@ -158,6 +195,9 @@ func Update(client *gophercloud.ServiceClient, configID string, opts UpdateOptsB
 	return res
 }
 
+// Replace will modify an existing configuration group by overwriting the
+// entire parameter group with the new values provided. Any existing keys not
+// included in UpdateOptsBuilder will be deleted.
 func Replace(client *gophercloud.ServiceClient, configID string, opts UpdateOptsBuilder) ReplaceResult {
 	var res ReplaceResult
 
@@ -176,6 +216,7 @@ func Replace(client *gophercloud.ServiceClient, configID string, opts UpdateOpts
 	return res
 }
 
+// Delete will permanently delete a configuration group.
 func Delete(client *gophercloud.ServiceClient, configID string) DeleteResult {
 	var res DeleteResult
 
@@ -186,20 +227,32 @@ func Delete(client *gophercloud.ServiceClient, configID string) DeleteResult {
 	return res
 }
 
+// ListInstances will list all the instances associated with a particular
+// configuration group.
 func ListInstances(client *gophercloud.ServiceClient, configID string) pagination.Pager {
 	pageFn := func(r pagination.PageResult) pagination.Page {
 		return instances.InstancePage{pagination.LinkedPageBase{PageResult: r}}
 	}
 	return pagination.NewPager(client, instancesURL(client, configID), pageFn)
 }
 
+// ListDatastoreParams will list all the available and supported parameters
+// that can be used for a particular datastore ID and a particular version.
+// For example, if you are wondering how you can configure a MySQL 5.6 instance,
+// you can use this operation (you will need to retrieve the MySQL datastore ID
+// by using the datastores API).
 func ListDatastoreParams(client *gophercloud.ServiceClient, datastoreID, versionID string) pagination.Pager {
 	pageFn := func(r pagination.PageResult) pagination.Page {
 		return ParamPage{pagination.SinglePageBase(r)}
 	}
 	return pagination.NewPager(client, listDSParamsURL(client, datastoreID, versionID), pageFn)
 }
 
+// GetDatastoreParam will retrieve information about a specific configuration
+// parameter. For example, you can use this operation to understand more about
+// "innodb_file_per_table" configuration param for MySQL datastores. You will
+// need the param's ID first, which can be attained by using the ListDatastoreParams
+// operation.
 func GetDatastoreParam(client *gophercloud.ServiceClient, datastoreID, versionID, paramID string) ParamResult {
 	var res ParamResult
 
@@ -211,13 +264,17 @@ func GetDatastoreParam(client *gophercloud.ServiceClient, datastoreID, versionID
 	return res
 }
 
+// ListGlobalParams is similar to ListDatastoreParams but does not require a
+// DatastoreID.
 func ListGlobalParams(client *gophercloud.ServiceClient, versionID string) pagination.Pager {
 	pageFn := func(r pagination.PageResult) pagination.Page {
 		return ParamPage{pagination.SinglePageBase(r)}
 	}
 	return pagination.NewPager(client, listGlobalParamsURL(client, versionID), pageFn)
 }
 
+// GetGlobalParam is similar to GetDatastoreParam but does not require a
+// DatastoreID.
 func GetGlobalParam(client *gophercloud.ServiceClient, versionID, paramID string) ParamResult {
 	var res ParamResult