Enhance doc for nova services

make some modifications to nova db reference and add some
basic information about some functions such as nova.service.start

Change-Id: I70c1a5eac91ab61ecd4ebc1c8ed95e4e4ba6b9fc

doc/source/reference/services.rst

@@ -50,6 +50,6 @@ Implementation-Specific Drivers
 
 A manager will generally load a driver for some of its tasks. The driver is responsible for specific implementation details.  Anything running shell commands on a host, or dealing with other non-python code should probably be happening in a driver.
 
-Drivers should minimize touching the database, although it is currently acceptable for implementation specific data. This may be reconsidered at some point.
+Drivers should not touch the database as the database management is done inside `nova-conductor`.
 
 It usually makes sense to define an Abstract Base Class for the specific driver (i.e. VolumeDriver), to define the methods that a different driver would need to implement.

nova/service.py

@@ -136,6 +136,11 @@ class Service(service.Service):
                 }
 
     def start(self):
+        """Start the service.
+
+        This includes starting an RPC service, initializing
+        periodic tasks, etc.
+        """
         verstr = version.version_string_with_package()
         LOG.info(_LI('Starting %(topic)s node (version %(version)s)'),
                   {'topic': self.topic, 'version': verstr})
@@ -256,6 +261,7 @@ class Service(service.Service):
             LOG.warning(_LW('Service killed that has no database entry'))
 
     def stop(self):
+        """stop the service and clean up."""
         try:
             self.rpcserver.stop()
             self.rpcserver.wait()
@@ -286,6 +292,7 @@ class Service(service.Service):
             sys.exit(1)
 
     def reset(self):
+        """reset the service."""
         self.manager.reset()