Adding documentation

Author: Jamie Hannaford

openstack/db/v1/databases/doc.go

@@ -1 +1,6 @@
+// Package flavors provides information and interaction with the database API
+// resource in the OpenStack Database service.
+//
+// A database, when referred to here, refers to the database engine running on
+// an instance.
 package databases

openstack/db/v1/databases/requests.go

@@ -7,24 +7,36 @@ import (
 	"github.com/rackspace/gophercloud/pagination"
 )
 
+// CreateOptsBuilder builds create options
 type CreateOptsBuilder interface {
 	ToDBCreateMap() (map[string]interface{}, error)
 }
 
 // DatabaseOpts is the struct responsible for configuring a database; often in
 // the context of an instance.
 type CreateOpts struct {
-	// Specifies the name of the database. Optional.
+	// [REQUIRED] Specifies the name of the database. Valid names can be composed
+	// of the following characters: letters (either case); numbers; these
+	// characters '@', '?', '#', ' ' but NEVER beginning a name string; '_' is
+	// permitted anywhere. Prohibited characters that are forbidden include:
+	// single quotes, double quotes, back quotes, semicolons, commas, backslashes,
+	// and forward slashes.
 	Name string
 
-	// Set of symbols and encodings. Optional; the default character set is utf8.
+	// [OPTIONAL] Set of symbols and encodings. The default character set is
+	// "utf8". See http://dev.mysql.com/doc/refman/5.1/en/charset-mysql.html for
+	// supported character sets.
 	CharSet string
 
-	// Set of rules for comparing characters in a character set. Optional; the
-	// default value for collate is utf8_general_ci.
+	// [OPTIONAL] Set of rules for comparing characters in a character set. The
+	// default value for collate is "utf8_general_ci". See
+	// http://dev.mysql.com/doc/refman/5.1/en/charset-mysql.html for supported
+	// collations.
 	Collate string
 }
 
+// ToMap is a helper function to convert individual DB create opt structures
+// into sub-maps.
 func (opts CreateOpts) ToMap() (map[string]string, error) {
 	if opts.Name == "" {
 		return nil, fmt.Errorf("Name is a required field")
@@ -44,8 +56,10 @@ func (opts CreateOpts) ToMap() (map[string]string, error) {
 	return db, nil
 }
 
+// BatchCreateOpts allows for multiple databases to created and modified.
 type BatchCreateOpts []CreateOpts
 
+// ToDBCreateMap renders a JSON map for creating DBs.
 func (opts BatchCreateOpts) ToDBCreateMap() (map[string]interface{}, error) {
 	var dbs []map[string]string
 	for _, db := range opts {
@@ -58,6 +72,8 @@ func (opts BatchCreateOpts) ToDBCreateMap() (map[string]interface{}, error) {
 	return map[string]interface{}{"databases": dbs}, nil
 }
 
+// Create will create a new database within the specified instance. If the
+// specified instance does not exist, a 404 error will be returned.
 func Create(client *gophercloud.ServiceClient, instanceID string, opts CreateOptsBuilder) CreateResult {
 	var res CreateResult
 
@@ -76,6 +92,9 @@ func Create(client *gophercloud.ServiceClient, instanceID string, opts CreateOpt
 	return res
 }
 
+// List will list all of the databases for a specified instance. Note: this
+// operation will only return user-defined databases; it will exclude system
+// databases like "mysql", "information_schema", "lost+found" etc.
 func List(client *gophercloud.ServiceClient, instanceID string) pagination.Pager {
 	createPageFn := func(r pagination.PageResult) pagination.Page {
 		return DBPage{pagination.LinkedPageBase{PageResult: r}}
@@ -84,6 +103,8 @@ func List(client *gophercloud.ServiceClient, instanceID string) pagination.Pager
 	return pagination.NewPager(client, baseURL(client, instanceID), createPageFn)
 }
 
+// Delete will permanently delete the database within a specified instance.
+// All contained data inside the database will also be permanently deleted.
 func Delete(client *gophercloud.ServiceClient, instanceID, dbName string) DeleteResult {
 	var res DeleteResult
 

openstack/db/v1/databases/results.go

@@ -6,8 +6,9 @@ import (
 	"github.com/rackspace/gophercloud/pagination"
 )
 
+// Database represents a Database API resource.
 type Database struct {
-	// Specifies the name of the MySQL DB.
+	// Specifies the name of the MySQL database.
 	Name string
 
 	// Set of symbols and encodings. The default character set is utf8.
@@ -18,10 +19,16 @@ type Database struct {
 	Collate string
 }
 
+// CreateResult represents the result of a Create operation.
 type CreateResult struct {
 	gophercloud.Result
 }
 
+// DeleteResult represents the result of a Delete operation.
+type DeleteResult struct {
+	gophercloud.ErrResult
+}
+
 // DBPage represents a single page of a paginated DB collection.
 type DBPage struct {
 	pagination.LinkedPageBase
@@ -63,7 +70,3 @@ func ExtractDBs(page pagination.Page) ([]Database, error) {
 	err := mapstructure.Decode(casted, &response)
 	return response.Databases, err
 }
-
-type DeleteResult struct {
-	gophercloud.ErrResult
-}

openstack/db/v1/flavors/doc.go

@@ -1,7 +1,7 @@
 // Package flavors provides information and interaction with the flavor API
-// resource in the OpenStack Compute service.
+// resource in the OpenStack Database service.
 //
-// A flavor is an available hardware configuration for a server. Each flavor
-// has a unique combination of disk space, memory capacity and priority for CPU
-// time.
+// A flavor is an available hardware configuration for a database instance.
+// Each flavor has a unique combination of disk space, memory capacity and
+// priority for CPU time.
 package flavors

openstack/db/v1/flavors/fixtures.go

@@ -26,7 +26,7 @@ const flavor = `
 `
 
 var (
-	flavorID = "{flavorID}"
+	flavorID = 1
 	_baseURL = "/flavors"
 	resURL   = "/flavors/" + flavorID
 )

openstack/db/v1/flavors/requests.go

@@ -5,6 +5,9 @@ import (
 	"github.com/rackspace/gophercloud/pagination"
 )
 
+// List will list all available hardware flavors that an instance can use. The
+// operation is identical to the one supported by the Nova API, but without the
+// "disk" property.
 func List(client *gophercloud.ServiceClient) pagination.Pager {
 	createPage := func(r pagination.PageResult) pagination.Page {
 		return FlavorPage{pagination.LinkedPageBase{PageResult: r}}
@@ -13,7 +16,8 @@ func List(client *gophercloud.ServiceClient) pagination.Pager {
 	return pagination.NewPager(client, listURL(client), createPage)
 }
 
-func Get(client *gophercloud.ServiceClient, id string) GetResult {
+// Get will retrieve information for a specified hardware flavor.
+func Get(client *gophercloud.ServiceClient, id int) GetResult {
 	var gr GetResult
 
 	_, gr.Err = client.Request("GET", getURL(client, id), gophercloud.RequestOpts{

openstack/db/v1/flavors/results.go

@@ -1,16 +1,11 @@
 package flavors
 
 import (
-	"errors"
-
 	"github.com/mitchellh/mapstructure"
 	"github.com/rackspace/gophercloud"
 	"github.com/rackspace/gophercloud/pagination"
 )
 
-// ErrCannotInterpret is returned by an Extract call if the response body doesn't have the expected structure.
-var ErrCannotInterpet = errors.New("Unable to interpret a response body.")
-
 // GetResult temporarily holds the response from a Get call.
 type GetResult struct {
 	gophercloud.Result
@@ -32,15 +27,16 @@ func (gr GetResult) Extract() (*Flavor, error) {
 
 // Flavor records represent (virtual) hardware configurations for server resources in a region.
 type Flavor struct {
-	// The Id field contains the flavor's unique identifier.
-	// For example, this identifier will be useful when specifying which hardware configuration to use for a new server instance.
+	// The flavor's unique identifier.
 	ID int `mapstructure:"id"`
 
+	// The RAM capacity for the flavor.
 	RAM int `mapstructure:"ram"`
 
 	// The Name field provides a human-readable moniker for the flavor.
 	Name string `mapstructure:"name"`
 
+	// Links to access the flavor.
 	Links []gophercloud.Link
 }
 

openstack/db/v1/instances/doc.go

@@ -1 +1,7 @@
+// Package instances provides information and interaction with the instance API
+// resource in the OpenStack Database service.
+//
+// A database instance is an isolated database environment with compute and
+// storage resources in a single tenant environment on a shared physical host
+// machine.
 package instances

openstack/db/v1/instances/requests.go

@@ -35,6 +35,7 @@ type CreateOpts struct {
 	Users users.BatchCreateOpts
 }
 
+// ToInstanceCreateMap will render a JSON map.
 func (opts CreateOpts) ToInstanceCreateMap() (map[string]interface{}, error) {
 	if opts.Size > 300 || opts.Size < 1 {
 		return nil, fmt.Errorf("Size (GB) must be between 1-300")

openstack/db/v1/instances/results.go

@@ -3,19 +3,11 @@ package instances
 import (
 	"github.com/mitchellh/mapstructure"
 	"github.com/rackspace/gophercloud"
+	"github.com/rackspace/gophercloud/openstack/db/v1/flavors"
 	"github.com/rackspace/gophercloud/openstack/db/v1/users"
 	"github.com/rackspace/gophercloud/pagination"
 )
 
-// Flavor represents information about a hardware flavor for a database instance.
-type Flavor struct {
-	// The unique identifier for a flavor.
-	ID string
-
-	// Various links which allow a user to reference the flavor.
-	Links []gophercloud.Link
-}
-
 // Volume represents information about an attached volume for a database instance.
 type Volume struct {
 	// The size in GB of the volume
@@ -33,7 +25,7 @@ type Instance struct {
 	Updated string //time.Time
 
 	// Indicates the hardware flavor the instance uses.
-	Flavor Flavor
+	Flavor flavors.Flavor
 
 	// A DNS-resolvable hostname associated with the database instance (rather
 	// than an IPv4 address). Since the hostname always resolves to the correct