Normalization of Dev reference docs.

2 files changed, 38 insertions, 2 deletions

diff --git a/nova/manager.py b/nova/manager.py
index 4244b2db4..a6efb8732 100644
--- a/nova/manager.py
+++ b/nova/manager.py
@@ -15,8 +15,40 @@
 #    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 #    License for the specific language governing permissions and limitations
 #    under the License.
+
 """
-Base class for managers of different parts of the system
+Managers are responsible for a certain aspect of the sytem.  It is a logical
+grouping of code relating to a portion of the system.  In general other
+components should be using the manager to make changes to the components that
+it is responsible for.
+
+For example, other components that need to deal with volumes in some way,
+should do so by calling methods on the VolumeManager instead of directly
+changing fields in the database.  This allows us to keep all of the code
+relating to volumes in the same place.
+
+We have adopted a basic strategy of Smart managers and dumb data, which means
+rather than attaching methods to data objects, components should call manager
+methods that act on the data.
+
+Methods on managers that can be executed locally should be called directly. If
+a particular method must execute on a remote host, this should be done via rpc
+to the service that wraps the manager
+
+Managers should be responsible for most of the db access, and
+non-implementation specific data.  Anything implementation specific that can't
+be generalized should be done by the Driver.
+
+In general, we prefer to have one manager with multiple drivers for different
+implementations, but sometimes it makes sense to have multiple managers.  You
+can think of it this way: Abstract different overall strategies at the manager
+level(FlatNetwork vs VlanNetwork), and different implementations at the driver
+level(LinuxNetDriver vs CiscoNetDriver).
+
+Managers will often provide methods for initial setup of a host or periodic
+tasksto a wrapping service.
+
+This module provides Manager, a base class for managers.
 """
 
 from nova import utils
diff --git a/nova/service.py b/nova/service.py
index d53d92b65..0eb3a2762 100644
--- a/nova/service.py
+++ b/nova/service.py
@@ -17,7 +17,11 @@
 #    under the License.
 
 """
-Generic Node baseclass for all workers that run on hosts
+A service is a very thin wrapper around a Manager object.  It exposes the
+manager's public methods to other components of the system via rpc.  It will
+report state periodically to the database and is responsible for initiating any periodic tasts that need to be executed on a given host.
+
+This module contains Service, a generic baseclass for all workers.
 """
 
 import inspect