doc: Make file headings consistent, and update docstrings per the proposed HACKING guide

Change-Id: I593bc9e6cff83307dca3d87f052872a7819d6a0b

bin/marconi-self-host

@@ -1,24 +1,23 @@
 #!/usr/bin/env python
 
-# vim: tabstop=4 shiftwidth=4 softtabstop=4
-
-#    Copyright 2012 Rackspace, Inc.
+# Copyright (c) 2013 Rackspace, Inc.
 #
-#    Licensed under the Apache License, Version 2.0 (the "License"); you may
-#    not use this file except in compliance with the License. You may obtain
-#    a copy of the License at
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
 #
-#         http://www.apache.org/licenses/LICENSE-2.0
+#    http://www.apache.org/licenses/LICENSE-2.0
 #
-#    Unless required by applicable law or agreed to in writing, software
-#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-#    License for the specific language governing permissions and limitations
-#    under the License.
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 
 """Bootstrap for self-hosting a Marconi node
 
-Alternatively, for hosting a WSGI app with an external server, configure
+Alternatively, to host a WSGI app with an external server, configure
 kernel with the WSGI transport and export the WSGI app callable, e.g.:
 
     logging.config.fileConfig(logging_conf_file)

marconi/__init__.py

@@ -1,17 +1,17 @@
-#!/usr/bin/env python
-# Copyright 2012 Rackspace, Inc.
+# Copyright (c) 2013 Rackspace Hosting, Inc.
 #
-# Licensed under the Apache License, Version 2.0 (the "License"); you may
-# not use this file except in compliance with the License. You may obtain
-# a copy of the License at
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
 #
-#      http://www.apache.org/licenses/LICENSE-2.0
+#    http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-# License for the specific language governing permissions and limitations
-# under the License.
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 
 import marconi.version
 

marconi/common/__init__.py

@@ -1,3 +1,3 @@
-""" Code common to Marconi, including main application logic. """
+"""Code common to Marconi, including main application logic."""
 
 from .kernel import Kernel  # NOQA

marconi/common/kernel.py

@@ -1,5 +1,3 @@
-# vim: tabstop=4 shiftwidth=4 softtabstop=4
-
 # Copyright (c) 2013 Rackspace, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,13 +13,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Defines the Marconi Kernel
-
-The Kernel loads up drivers per a given configuration, and manages their
-lifetimes.
-
-"""
-
 from ConfigParser import SafeConfigParser
 
 import marconi.transport.wsgi as wsgi
@@ -29,6 +20,12 @@ import marconi.storage.reference as reference
 
 
 class Kernel(object):
+    """
+    Defines the Marconi Kernel
+
+    The Kernel loads up drivers per a given configuration, and manages their
+    lifetimes.
+    """
 
     def __init__(self, config_file):
         # TODO(kgriffs) Error handling

marconi/storage/__init__.py

@@ -1,3 +1,3 @@
-""" Marconi Storage Drivers """
+"""Marconi Storage Drivers"""
 
 from .driver_base import DriverBase  # NOQA

marconi/storage/driver_base.py

@@ -1,5 +1,3 @@
-# vim: tabstop=4 shiftwidth=4 softtabstop=4
-
 # Copyright (c) 2013 Rackspace, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,8 +13,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Implements the DriverBase abstract class for Marconi storage drivers."""
-
 from abc import ABCMeta, abstractproperty
 
 

marconi/storage/mongodb/__init__.py

@@ -1 +1 @@
-""" MongoDB Storage Driver for Marconi """
+"""MongoDB Storage Driver for Marconi"""

marconi/storage/reference/__init__.py

@@ -1,7 +1,7 @@
-"""In-memory reference Storage Driver for Marconi.
+"""
+In-memory reference Storage Driver for Marconi.
 
 Useful for automated testing and for prototyping storage driver concepts.
-
 """
 
 from .driver import Driver  # NOQA

marconi/storage/reference/driver.py

@@ -1,5 +1,3 @@
-# vim: tabstop=4 shiftwidth=4 softtabstop=4
-
 # Copyright (c) 2013 Rackspace, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");

marconi/tests/__init__.py

@@ -1,14 +1,16 @@
-#!/usr/bin/env python
-# Copyright 2012 Rackspace, Inc.
+# Copyright (c) 2013 Rackspace Hosting, Inc.
 #
-# Licensed under the Apache License, Version 2.0 (the "License"); you may
-# not use this file except in compliance with the License. You may obtain
-# a copy of the License at
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
 #
-#      http://www.apache.org/licenses/LICENSE-2.0
+#    http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-# License for the specific language governing permissions and limitations
-# under the License.
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Marconi Unit-ish Tests"""

marconi/tests/test_simple.py

@@ -1,6 +1,4 @@
-# vim: tabstop=4 shiftwidth=4 softtabstop=4
-
-# Copyright 2012 Rackspace, Inc.
+# Copyright 2013 Rackspace, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License"); you may
 # not use this file except in compliance with the License. You may obtain

marconi/tests/util/__init__.py

@@ -1,4 +1,3 @@
 """Test utilities"""
 
-
 from .test_suite import TestSuite  # NOQA

marconi/tests/util/test_suite.py

@@ -1,40 +1,29 @@
-"""Defines the TestSuite class.
-
-Copyright 2013 by Rackspace Hosting, Inc.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-
-"""
+# Copyright (c) 2013 Rackspace Hosting, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 
 import testtools
 import os.path
 
 
 class TestSuite(testtools.TestCase):
-    """Child class of testtools.TestCase for testing Marconi
+    """
+    Child class of testtools.TestCase for testing Marconi
 
     Inherit from this and write your test methods. If the child class defines
     a prepare(self) method, this method will be called before executing each
     test method.
-
-    Attributes:
-        api: falcon.API instance used in simulating requests.
-        srmock: falcon.testing.StartResponseMock instance used in
-            simulating requests.
-        test_route: Randomly-generated route string (path) that tests can
-            use when wiring up resources.
-
-
     """
 
     def setUp(self):
@@ -47,11 +36,11 @@ class TestSuite(testtools.TestCase):
             prepare()
 
     def conf_path(self, filename):
-        """ Returns the full path to the specified Marconi conf file
-
-        Args:
-            filename: Name of the conf file to find (e.g., "wsgi_memory.conf")
+        """
+        Returns the full path to the specified Marconi conf file
 
+        :param filename: Name of the conf file to find (e.g.,
+                         "wsgi_memory.conf")
         """
 
         parent = os.path.dirname(self._my_dir())

marconi/transport/__init__.py

@@ -1,3 +1,3 @@
-""" Marconi Transport Modules """
+"""Marconi Transport Drivers"""
 
 from .driver_base import DriverBase  # NOQA

marconi/transport/driver_base.py

@@ -1,5 +1,3 @@
-# vim: tabstop=4 shiftwidth=4 softtabstop=4
-
 # Copyright (c) 2013 Rackspace, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,8 +13,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Implements the DriverBase abstract class for Marconi transport drivers."""
-
 from abc import ABCMeta, abstractmethod
 
 
@@ -25,6 +21,5 @@ class DriverBase:
 
     @abstractmethod
     def listen():
-        # TODO(kgriffs): If this is all there is to DriverBase, do we
-        #     even need it?
+        #TODO(kgriffs): If this is all there is to DriverBase, do we need it?
         pass

marconi/transport/wsgi/__init__.py

@@ -1,3 +1,3 @@
-""" WSGI Transport Driver"""
+"""WSGI Transport Driver"""
 
 from .driver import Driver  # NOQA

marconi/transport/wsgi/driver.py

@@ -1,5 +1,3 @@
-# vim: tabstop=4 shiftwidth=4 softtabstop=4
-
 # Copyright (c) 2013 Rackspace, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");

marconi/version.py

@@ -1,19 +1,17 @@
-# vim: tabstop=4 shiftwidth=4 softtabstop=4
-
-#    Copyright 2012 OpenStack LLC
+# Copyright (c) 2013 OpenStack Foundation
 #
-#    Licensed under the Apache License, Version 2.0 (the "License"); you may
-#    not use this file except in compliance with the License. You may obtain
-#    a copy of the License at
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
 #
-#         http://www.apache.org/licenses/LICENSE-2.0
+#    http://www.apache.org/licenses/LICENSE-2.0
 #
-#    Unless required by applicable law or agreed to in writing, software
-#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-#    License for the specific language governing permissions and limitations
-#    under the License.
-
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 
 from marconi.openstack.common import version as common_version