Update database page a bit.

3 files changed, 21 insertions, 9 deletions

diff --git a/doc/source/database.rst b/doc/source/database.rst
index 926f9be26..67f940fe1 100644
--- a/doc/source/database.rst
+++ b/doc/source/database.rst
@@ -20,8 +20,7 @@ Database Programming Guide
 
 ::
 
-    TODO(todd): should sqlalchemy.api be here?
-                document register_models (where should it be called from?)
+    TODO(todd): document register_models (where should it be called from?)
                 document any relevant test cases
                 document flags
 
@@ -37,17 +36,26 @@ The :mod:`api` Module
 Drivers
 -------
 
-The :mod:`sqlalchemy` Driver
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Driver: Sqlalchemy
+~~~~~~~~~~~~~~~~~~
+
+The :mod:`sqlalchemy.api` Module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. automodule:: nova.db.sqlalchemy.api
+
+The :mod:`sqlalchemy.models` Module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: nova.db.sqlalchemy.models
     :members:
     :undoc-members:
     :show-inheritance:
 
+The :mod:`sqlalchemy.session` Module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. automodule:: nova.db.sqlalchemy.models
+.. automodule:: nova.db.sqlalchemy.session
     :members:
     :undoc-members:
     :show-inheritance:
-
diff --git a/nova/db/sqlalchemy/api.py b/nova/db/sqlalchemy/api.py
index a3d8dde2f..d9b98655e 100644
--- a/nova/db/sqlalchemy/api.py
+++ b/nova/db/sqlalchemy/api.py
@@ -16,7 +16,7 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 """
-Implementation of SQLAlchemy backend
+Implementation of SQLAlchemy backend.
 """
 
 import random
diff --git a/nova/db/sqlalchemy/models.py b/nova/db/sqlalchemy/models.py
index 894ebcddd..29c3b74da 100644
--- a/nova/db/sqlalchemy/models.py
+++ b/nova/db/sqlalchemy/models.py
@@ -16,7 +16,7 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 """
-SQLAlchemy models for nova data
+SQLAlchemy models for nova data.
 """
 
 import datetime
@@ -488,7 +488,11 @@ class FloatingIp(BASE, NovaBase):
 
 
 def register_models():
-    """Register Models and create metadata."""
+    """Register Models and create metadata.
+
+    Called from nova.db.sqlalchemy.__init__ as part of loading the driver,
+    it will never need to be called explicitly elsewhere.
+    """
     from sqlalchemy import create_engine
     models = (Service, Instance, Volume, ExportDevice, FixedIp,
               FloatingIp, Network, SecurityGroup,