Merge "Update api-ref documentation"

4 files changed, 33 insertions, 31 deletions

diff --git a/api-ref/source/database-instance-actions.inc b/api-ref/source/database-instance-actions.inc
index f1c842a8..35426339 100644
--- a/api-ref/source/database-instance-actions.inc
+++ b/api-ref/source/database-instance-actions.inc
@@ -14,11 +14,11 @@ Restart instance
 
 Restarts the database service for an instance.
 
-The restart operation restarts only the MySQL instance. Restarting
-MySQL erases any dynamic configuration settings that you make in
-MySQL.
+The restart operation restarts only the database instance. Restarting
+the database erases any dynamic configuration settings that you make
+in the database instance.
 
-The MySQL service is unavailable until the instance restarts.
+The database instance is unavailable until the instance restarts.
 
 If the operation succeeds, it returns the ``Accepted (202)``
 response code.
@@ -65,7 +65,7 @@ Resize instance
 Resizes the memory for an instance.
 
 If you provide a valid ``flavorRef``, this operation changes the
-memory size of the instance, and restarts MySQL.
+memory size of the instance, and restarts the database.
 
 Error response codes:202,413,415,405,404,403,401,400,422,503,500,501,
 
diff --git a/api-ref/source/database-instances.inc b/api-ref/source/database-instances.inc
index 7dd9f8f0..46364830 100644
--- a/api-ref/source/database-instances.inc
+++ b/api-ref/source/database-instances.inc
@@ -7,7 +7,7 @@ Database instances (instances)
 Creates, lists, shows details for, attaches a configuration group
 to, detaches a configuration group from, deletes, lists
 configuration defaults, creates root, and determines whether root
-is enables for instances.
+is enabled for instances.
 
 
 Delete database instance
@@ -60,11 +60,11 @@ Lists the status and details of the database instance.
 Lists the volume size in gigabytes (GB) and the approximate GB
 used.
 
-After instance creation, the ``used`` value is greater than 0,
-which is expected and due to the automatic creation of non-empty
-transaction logs for MySQL optimization. The response does not
-include the ``used`` attribute when the instance status is
-``BUILD``, ``REBOOT``, ``RESIZE``, or ``ERROR``.
+After instance creation, the ``used`` value is greater than 0, which
+is expected as databases may create some basic (non empty) files to
+represent an empty schema. The response does not include the ``used``
+attribute when the instance status is ``BUILD``, ``REBOOT``,
+``RESIZE``, or ``ERROR``.
 
 The list operations return a DNS-resolvable host name for the
 database instance rather than an IP address. Because the host name
@@ -266,7 +266,8 @@ database instance.
 - You can create a database instance with one or more databases. You
   associate users with each database.
 
-- The default binding for the MySQL instance is port 3306.
+- The port on which the database instance is listening is database
+  specific.
 
 
 Normal response codes: 200
diff --git a/api-ref/source/databases.inc b/api-ref/source/databases.inc
index 658b5b7b..465a755d 100644
--- a/api-ref/source/databases.inc
+++ b/api-ref/source/databases.inc
@@ -51,8 +51,6 @@ Create database
 
 Creates a database within an instance.
 
-The ``name`` of the database is a required attribute.
-
 Error response codes:202,413,405,404,403,401,400,422,503,500,501,
 
 
diff --git a/api-ref/source/user-management.inc b/api-ref/source/user-management.inc
index 28970bf6..7dd77d95 100644
--- a/api-ref/source/user-management.inc
+++ b/api-ref/source/user-management.inc
@@ -17,13 +17,13 @@ Enables the root user for a database instance and returns the root password.
 This operation generates a root password for the root user and
 enables the root user to log in from any host.
 
-Changes that you make as a root user can impact the database
-instance and API operations in unpredictable and detrimental ways.
-When you enable the root user, you accept the possibility that we
-cannot support your database instance. We might not be able to
-assist you if you change core MySQL settings. These changes can be,
-but are not limited to, turning off bin logs, removing users that
-we use to access your instance, and so on.
+Changes that you make as a root user can impact the database instance
+and API operations in unpredictable and detrimental ways.  When you
+enable the root user, you accept the possibility that we cannot
+support your database instance. We might not be able to assist you if
+you change core database settings. These changes can be, but are not
+limited to, turning off bin logs, removing users that we use to access
+your instance, and so on.
 
 
 Normal response codes: 200
@@ -202,16 +202,19 @@ This table lists the required attributes for creating users:
 
 **Required attributes for user**
 
-+-----------------+---------------------------------------------------------------------+------------------------------------+----------+
-|    Applies to   |                                 Name                                |            Description             | Required |
-+-----------------+---------------------------------------------------------------------+------------------------------------+----------+
-|       User      |                                 name                                | Name of the user for the database. |   Yes    |
-+-----------------+---------------------------------------------------------------------+------------------------------------+----------+
-|     password    |                  User password for database access.                 |                Yes                 |          |
-+-----------------+---------------------------------------------------------------------+------------------------------------+----------+
-| (database) name | Name of the database that the user can access. You must specify one |                 No                 |          |
-|                 |                       or more database names.                       |                                    |          |
-+-----------------+---------------------------------------------------------------------+------------------------------------+----------+
++-----------------+------+------------------------------------+----------+
+|    Applies to   | Name |            Description             | Required |
++-----------------+------+------------------------------------+----------+
+|       User      | name | Name of the user for the database. |   Yes    |
++-----------------+------+------------------------------------+----------+
+|     password    |      | User password for database access. |   Yes    |
++-----------------+------+-------------------------+----------+----------+
+| (database) name |      | Name of the database(s) that the   |          |
+|                 |      | user can access. You can specify   |   No     |
+|                 |      | one or more database names.        |          |
++-----------------+------+------------------------------------+----------+
+
+Name of the database that the user can access. You can specify one or more database names.
 
  **Notes**