docs: update documentation for database-usage (#96)

The PR fixes the following: - links to other documentation - confusing wording - incorrect references to instance instead of database - incorrect grammar

Author: larkee

docs/database-usage.rst

@@ -1,38 +1,39 @@
 Database Admin
 ==============
 
-After creating a :class:`~google.cloud.spanner.instance.Instance`, you can
+After creating an :class:`~google.cloud.spanner_v1.instance.Instance`, you can
 interact with individual databases for that instance.
 
 
 List Databases
 --------------
 
 To iterate over all existing databases for an instance, use its
-:meth:`~google.cloud.spanner.instance.Instance.list_databases` method:
+:meth:`~google.cloud.spanner_v1.instance.Instance.list_databases` method:
 
 .. code:: python
 
  for database in instance.list_databases():
  # `database` is a `Database` object.
 
-This method yields :class:`~.spanner_admin_database_v1.types.Database`
+This method yields :class:`~google.cloud.spanner_v1.database.Database`
 objects.
 
 
 Database Factory
 ----------------
 
-To create a :class:`~google.cloud.spanner.database.Database` object:
+To create a :class:`~google.cloud.spanner_v1.database.Database` object:
 
 .. code:: python
 
  database = instance.database(database_id, ddl_statements)
 
-- ``ddl_statements`` is a list of strings containing DDL for the new database.
+- ``ddl_statements`` is a list of strings containing DDL statements for the new database.
 
-You can also use :meth:`Instance.database` to create a local wrapper for
-a database that has already been created:
+You can also use the :meth:`~google.cloud.spanner_v1.instance.Instance.database` method
+on an :class:`~google.cloud.spanner_v1.instance.Instance` object to create a local wrapper
+for a database that has already been created:
 
 .. code:: python
 
@@ -43,7 +44,7 @@ Create a new Database
 ---------------------
 
 After creating the database object, use its
-:meth:`~google.cloud.spanner.database.Database.create` method to
+:meth:`~google.cloud.spanner_v1.database.Database.create` method to
 trigger its creation on the server:
 
 .. code:: python
@@ -52,8 +53,8 @@ trigger its creation on the server:
 
 .. note::
 
- Creating an instance triggers a "long-running operation" and
- returns an :class:`~concurrent.futures.Future`-like object. Use
+ Creating a database triggers a "long-running operation" and
+ returns a :class:`~concurrent.futures.Future`-like object. Use
  the :meth:`~concurrent.futures.Future.result` method to wait for
  and inspect the result.
 
@@ -62,21 +63,21 @@ Update an existing Database
 ---------------------------
 
 After creating the database object, you can apply additional DDL statements
-via its :meth:`~google.cloud.spanner.database.Database.update_ddl` method:
+via its :meth:`~google.cloud.spanner_v1.database.Database.update_ddl` method:
 
 .. code:: python
 
  operation = database.update_ddl(ddl_statements, operation_id)
 
-- ``ddl_statements`` is a list of strings containing DDL to be applied to
- the database.
+- ``ddl_statements`` is a list of strings containing DDL statements to be
+ applied to the database.
 
 - ``operation_id`` is a string ID for the long-running operation.
 
 .. note::
 
- Update an instance triggers a "long-running operation" and
- returns a :class:`google.cloud.spanner.database.Operation`
+ Updating a database triggers a "long-running operation" and
+ returns an :class:`~google.cloud.spanner_v1.database.Operation`
  object. See :ref:`check-on-current-database-operation` for polling
  to find out if the operation is completed.
 
@@ -85,7 +86,7 @@ Drop a Database
 ---------------
 
 Drop a database using its
-:meth:`~google.cloud.spanner.database.Database.drop` method:
+:meth:`~google.cloud.spanner_v1.database.Database.drop` method:
 
 .. code:: python
 
@@ -97,14 +98,15 @@ Drop a database using its
 Check on Current Database Operation
 -----------------------------------
 
-The :meth:`~google.cloud.spanner.database.Database.create` and
-:meth:`~google.cloud.spanner.database.Database.update` methods of instance
-object trigger long-running operations on the server, and return instances
+The :meth:`~google.cloud.spanner_v1.database.Database.create` and
+:meth:`~google.cloud.spanner_v1.database.Database.update_ddl` methods of the
+:class:`~google.cloud.spanner_v1.database.Database` object trigger
+long-running operations on the server, and return operations
 conforming to the :class:`~.concurrent.futures.Future` class.
 
 .. code:: python
 
- >>> operation = instance.create()
+ >>> operation = database.create()
  >>> operation.result()
 
 
@@ -116,24 +118,25 @@ Use a Snapshot to Read / Query the Database
 
 A snapshot represents a read-only point-in-time view of the database.
 
-Calling :meth:`~google.cloud.spanner.database.Database.snapshot` with
+Calling :meth:`~google.cloud.spanner_v1.database.Database.snapshot` with
 no arguments creates a snapshot with strong concurrency:
 
 .. code:: python
 
  with database.snapshot() as snapshot:
  do_something_with(snapshot)
 
-See :class:`~google.cloud.spanner.snapshot.Snapshot` for the other options
+See :class:`~google.cloud.spanner_v1.snapshot.Snapshot` for the other options
 which can be passed.
 
 .. note::
 
- :meth:`~google.cloud.spanner.database.Database.snapshot` returns an
+ :meth:`~google.cloud.spanner_v1.database.Database.snapshot` returns an
  object intended to be used as a Python context manager (i.e., as the
- target of a ``with`` statement). Use the instance, and any result
- sets returned by its ``read`` or ``execute_sql`` methods, only inside
- the block created by the ``with`` statement.
+ target of a ``with`` statement). Perform all iterations within the
+ context of the ``with database.snapshot()`` block.
+
+
 
 See :doc:`snapshot-usage` for more complete examples of snapshot usage.
 
@@ -151,7 +154,7 @@ on the rows of tables in the database.
 
 .. note::
 
- :meth:`~google.cloud.spanner.database.Database.batch` returns an
+ :meth:`~google.cloud.spanner_v1.database.Database.batch` returns an
  object intended to be used as a Python context manager (i.e., as the
  target of a ``with`` statement). It applies any changes made inside
  the block of its ``with`` statement when exiting the block, unless an
@@ -187,26 +190,26 @@ transaction as a required argument:
 
 .. note::
 
- :meth:`~google.cloud.spanner.database.Database.run_in_transaction`
+ :meth:`~google.cloud.spanner_v1.database.Database.run_in_transaction`
  commits the transaction automatically if the "unit of work" function
  returns without raising an exception.
 
 .. note::
 
- :meth:`~google.cloud.spanner.database.Database.run_in_transaction`
- retries the "unit of work" function if the read / query operatoins
- or the commit are aborted due to concurrent updates
+ :meth:`~google.cloud.spanner_v1.database.Database.run_in_transaction`
+ retries the "unit of work" function if the read / query operations
+ or the commit are aborted due to concurrent updates.
 
 See :doc:`transaction-usage` for more complete examples of transaction usage.
 
 Configuring a session pool for a database
 -----------------------------------------
 
 Under the covers, the ``snapshot``, ``batch``, and ``run_in_transaction``
-methods use a pool of :class:`~google.cloud.spanner.session.Session` objects
+methods use a pool of :class:`~google.cloud.spanner_v1.session.Session` objects
 to manage their communication with the back-end. You can configure
 one of the pools manually to control the number of sessions, timeouts, etc.,
-and then passing it to the :class:`~google.cloud.spanner.database.Database`
+and then pass it to the :class:`~google.cloud.spanner_v1.database.Database`
 constructor:
 
 .. code-block:: python
@@ -221,12 +224,12 @@ constructor:
  pool = spanner.FixedSizePool(size=10, default_timeout=5)
  database = instance.database(DATABASE_NAME, pool=pool)
 
-Note that creating a database with a pool may presume that its database
-already exists, as it may need to pre-create sessions (rather than creating
-them on demand, as the default implementation does).
+Note that creating a database with a pool will require the database to
+already exist if the pool implementation needs to pre-create sessions
+(rather than creating them on demand, as the default implementation does).
 
 You can supply your own pool implementation, which must satisfy the
-contract laid out in :class:`~google.cloud.spanner.pool.AbstractSessionPool`:
+contract laid out in :class:`~google.cloud.spanner_v1.pool.AbstractSessionPool`:
 
 .. code-block:: python