Comments and Documentation

This change adds a ton of comments and documentation across all the code.

Change-Id: Ifee0a2f534e8584f14b0f13af4dda8dc70eb7553
Signed-off-by: Parker Berberian <pberberian@iol.unh.edu>

5 files changed, 38 insertions, 62 deletions

diff --git a/src/resource_inventory/idf_templater.py b/src/resource_inventory/idf_templater.py
index bf6eda0..8f0f924 100644
--- a/src/resource_inventory/idf_templater.py
+++ b/src/resource_inventory/idf_templater.py
@@ -16,9 +16,8 @@ from resource_inventory.models import Vlan
 
 
 class IDFTemplater:
-    """
-    Utility class to create a full IDF yaml file
-    """
+    """Utility class to create a full Installer Descriptor File (IDF) yaml file."""
+
     net_names = ["admin", "mgmt", "private", "public"]
     bridge_names = {
         "admin": "br-admin",
@@ -39,9 +38,7 @@ class IDFTemplater:
             }
 
     def makeIDF(self, booking):
-        """
-        fills the installer descriptor file template with info about the resource
-        """
+        """Fill the IDF template with info about the resource."""
         template = "dashboard/idf.yaml"
         info = {}
         info['version'] = "0.1"
diff --git a/src/resource_inventory/models.py b/src/resource_inventory/models.py
index d152698..4bc9bf3 100644
--- a/src/resource_inventory/models.py
+++ b/src/resource_inventory/models.py
@@ -111,24 +111,20 @@ class Resource(models.Model):
 
     def get_configuration(self, state):
         """
+        Get configuration of Resource.
+
         Returns the desired configuration for this host as a
         JSON object as defined in the rest api spec.
         state is a ConfigState
-        TODO: single method, or different methods for hw, network, snapshot, etc?
         """
         raise NotImplementedError("Must implement in concrete Resource classes")
 
     def reserve(self):
-        """
-        Reserves this resource for its currently
-        assigned booking.
-        """
+        """Reserve this resource for its currently assigned booking."""
         raise NotImplementedError("Must implement in concrete Resource classes")
 
     def release(self):
-        """
-        Makes this resource available again for new boookings
-        """
+        """Make this resource available again for new boookings."""
         raise NotImplementedError("Must implement in concrete Resource classes")
 
 
@@ -170,15 +166,14 @@ class PhysicalNetwork(Resource):
 
     def get_configuration(self, state):
         """
-        Returns the network configuration
+        Get the network configuration.
+
         Collects info about each attached network interface and vlan, etc
         """
         return {}
 
     def reserve(self):
-        """
-        Reserves vlan(s) associated with this network
-        """
+        """Reserve vlan(s) associated with this network."""
         # vlan_manager = self.bundle.lab.vlan_manager
         return False
 
@@ -329,9 +324,8 @@ class OPNFVRole(models.Model):
 
 
 class Image(models.Model):
-    """
-    model for representing OS images / snapshots of hosts
-    """
+    """Model for representing OS images / snapshots of hosts."""
+
     id = models.AutoField(primary_key=True)
     lab_id = models.IntegerField()  # ID the lab who holds this image knows
     from_lab = models.ForeignKey(Lab, on_delete=models.CASCADE)
@@ -354,10 +348,8 @@ def get_sentinal_opnfv_role():
 
 
 class HostConfiguration(models.Model):
-    """
-    model to represent a complete configuration for a single
-    physical host
-    """
+    """Model to represent a complete configuration for a single physical host."""
+
     id = models.AutoField(primary_key=True)
     host = models.ForeignKey(GenericHost, related_name="configuration", on_delete=models.CASCADE)
     image = models.ForeignKey(Image, on_delete=models.PROTECT)
@@ -438,8 +430,7 @@ class Interface(models.Model):
 
 
 class OPNFV_SETTINGS():
-    """
-    This is a static configuration class
-    """
+    """This is a static configuration class."""
+
     # all the required network types in PDF/IDF spec
     NETWORK_ROLES = ["public", "private", "admin", "mgmt"]
diff --git a/src/resource_inventory/pdf_templater.py b/src/resource_inventory/pdf_templater.py
index 7e91b87..51e3746 100644
--- a/src/resource_inventory/pdf_templater.py
+++ b/src/resource_inventory/pdf_templater.py
@@ -14,15 +14,11 @@ from resource_inventory.models import Host, InterfaceProfile
 
 
 class PDFTemplater:
-    """
-    Utility class to create a full PDF yaml file
-    """
+    """Utility class to create a full PDF yaml file."""
 
     @classmethod
     def makePDF(cls, booking):
-        """
-        fills the pod descriptor file template with info about the resource
-        """
+        """Fill the pod descriptor file template with info about the resource."""
         template = "dashboard/pdf.yaml"
         info = {}
         info['details'] = cls.get_pdf_details(booking.resource)
@@ -33,9 +29,7 @@ class PDFTemplater:
 
     @classmethod
     def get_pdf_details(cls, resource):
-        """
-        Info for the "details" section
-        """
+        """Info for the "details" section."""
         details = {}
         owner = "Anon"
         email = "email@mail.com"
@@ -64,6 +58,7 @@ class PDFTemplater:
 
     @classmethod
     def get_jumphost(cls, booking):
+        """Return the host designated as the Jumphost for the booking."""
         jumphost = None
         if booking.opnfv_config:
             jumphost_opnfv_config = booking.opnfv_config.host_opnfv_config.get(
@@ -80,9 +75,7 @@ class PDFTemplater:
 
     @classmethod
     def get_pdf_jumphost(cls, booking):
-        """
-        returns a dict of all the info for the "jumphost" section
-        """
+        """Return a dict of all the info for the "jumphost" section."""
         jumphost = cls.get_jumphost(booking)
         jumphost_info = cls.get_pdf_host(jumphost)
         jumphost_info['os'] = jumphost.config.image.os.name
@@ -90,9 +83,7 @@ class PDFTemplater:
 
     @classmethod
     def get_pdf_nodes(cls, booking):
-        """
-        returns a list of all the "nodes" (every host except jumphost)
-        """
+        """Return a list of all the "nodes" (every host except jumphost)."""
         pdf_nodes = []
         nodes = set(Host.objects.filter(bundle=booking.resource))
         nodes.discard(cls.get_jumphost(booking))
@@ -105,8 +96,9 @@ class PDFTemplater:
     @classmethod
     def get_pdf_host(cls, host):
         """
-        method to gather all needed info about a host
-        returns a dict
+        Gather all needed info about a host.
+
+        returns a dictionary
         """
         host_info = {}
         host_info['name'] = host.template.resource.name
@@ -125,9 +117,7 @@ class PDFTemplater:
 
     @classmethod
     def get_pdf_host_node(cls, host):
-        """
-        returns "node" info for a given host
-        """
+        """Return "node" info for a given host."""
         d = {}
         d['type'] = "baremetal"
         d['vendor'] = host.vendor
@@ -148,9 +138,7 @@ class PDFTemplater:
 
     @classmethod
     def get_pdf_host_disk(cls, disk):
-        """
-        returns a dict describing the given disk
-        """
+        """Return a dict describing the given disk."""
         disk_info = {}
         disk_info['name'] = disk.name
         disk_info['capacity'] = str(disk.size) + "G"
@@ -161,9 +149,7 @@ class PDFTemplater:
 
     @classmethod
     def get_pdf_host_iface(cls, interface):
-        """
-        returns a dict describing given interface
-        """
+        """Return a dict describing given interface."""
         iface_info = {}
         iface_info['features'] = "none"
         iface_info['mac_address'] = interface.mac_address
@@ -179,9 +165,7 @@ class PDFTemplater:
 
     @classmethod
     def get_pdf_host_remote_management(cls, host):
-        """
-        gives the remote params of the host
-        """
+        """Get the remote params of the host."""
         man = host.remote_management
         mgmt = {}
         mgmt['address'] = man.address
diff --git a/src/resource_inventory/resource_manager.py b/src/resource_inventory/resource_manager.py
index 7df4263..34c7be3 100644
--- a/src/resource_inventory/resource_manager.py
+++ b/src/resource_inventory/resource_manager.py
@@ -44,10 +44,10 @@ class ResourceManager:
 
     def hostsAvailable(self, grb):
         """
-        This method will check if the given GenericResourceBundle
-        is available. No changes to the database
-        """
+        Check if the given GenericResourceBundle is available.
 
+        No changes to the database
+        """
         # count up hosts
         profile_count = {}
         for host in grb.getResources():
@@ -90,7 +90,10 @@ class ResourceManager:
 
     def convertResourceBundle(self, genericResourceBundle, config=None):
         """
-        Takes in a GenericResourceBundle and 'converts' it into a ResourceBundle
+        Convert a GenericResourceBundle into a ResourceBundle.
+
+        Takes in a genericResourceBundle and reserves all the
+        Resources needed and returns a completed ResourceBundle.
         """
         resource_bundle = ResourceBundle.objects.create(template=genericResourceBundle)
         generic_hosts = genericResourceBundle.getResources()
diff --git a/src/resource_inventory/urls.py b/src/resource_inventory/urls.py
index a1eace7..a008176 100644
--- a/src/resource_inventory/urls.py
+++ b/src/resource_inventory/urls.py
@@ -9,7 +9,8 @@
 ##############################################################################
 
 
-"""laas_dashboard URL Configuration
+"""
+laas_dashboard URL Configuration.
 
 The `urlpatterns` list routes URLs to views. For more information please see:
     https://docs.djangoproject.com/en/1.10/topics/http/urls/