merge in trunk

4 files changed, 49 insertions, 2 deletions

diff --git a/nova/api/__init__.py b/nova/api/__init__.py
index f693225d9..1dabd3d21 100644
--- a/nova/api/__init__.py
+++ b/nova/api/__init__.py
@@ -30,6 +30,7 @@ import routes
 import webob.dec
 
 from nova import flags
+from nova import utils
 from nova import wsgi
 from nova.api import cloudpipe
 from nova.api import ec2
@@ -83,6 +84,7 @@ class API(wsgi.Router):
         mapper.connect("/cloudpipe/{path_info:.*}", controller=cloudpipe.API())
         super(API, self).__init__(mapper)
 
+    @utils.fix_wsgify_docstr
     @webob.dec.wsgify
     def osapi_versions(self, req):
         """Respond to a request for all OpenStack API versions."""
@@ -94,6 +96,7 @@ class API(wsgi.Router):
                 "attributes": dict(version=["status", "id"])}}
         return wsgi.Serializer(req.environ, metadata).to_content_type(response)
 
+    @utils.fix_wsgify_docstr
     @webob.dec.wsgify
     def ec2api_versions(self, req):
         """Respond to a request for all EC2 versions."""
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
diff --git a/nova/utils.py b/nova/utils.py
index e7892a212..d7ebe5b4c 100644
--- a/nova/utils.py
+++ b/nova/utils.py
@@ -21,6 +21,7 @@ System-level utilities and helper functions.
 """
 
 import datetime
+import functools
 import inspect
 import logging
 import os
@@ -232,3 +233,10 @@ def utf8(value):
         return value.encode("utf-8")
     assert isinstance(value, str)
     return value
+
+def fix_wsgify_docstr(wsgified_func):
+    """A decorator to re-assign docstrings that webob.dec.wsgify clobbers."""
+    @functools.wraps(wsgified_func.func)
+    def _f(*args, **kwargs):
+        wsgified_func(*args, **kwargs)
+    return _f