ENH: Typos + completed documentation for thing.py

ml/thing.py

@@ -96,10 +96,10 @@ def model(self):
 
     @property
     def features(self):
-        """Returns
+        """Returns this object's features.
 
-        :returns:
-        :rtype:
+        :returns: Features
+        :rtype: dict
 
         """
 
@@ -107,7 +107,7 @@ def features(self):
 
     @features.setter
     def features(self, value):
-        """Replaces __features with vale.
+        """Replaces __features with value.
 
         :param value: New collection of features
 
@@ -117,21 +117,20 @@ def features(self, value):
 
     @property
     def roles(self):
-        """Returns the things roles.
+        """Returns the thing's roles.
 
         :returns: ml40 roles
-
         :rtype: dict
+
         """
 
         return self.__roles
 
     @roles.setter
     def roles(self, value):
-        """Adds a new role.
+        """Replaces __roles with value
 
-        :param value: The new role
-        :type value: ml.role
+        :param value: New collection of roles
         """
 
         self.__roles = value
@@ -141,8 +140,8 @@ def client_secret(self):
         """Returns the client secret.
 
         :returns: Client secret
-
         :rtype: str
+
         """
 
         return self.__client_secret
@@ -153,8 +152,8 @@ def grant_type(self):
         identity provider.
 
         :returns: authentication method
-
         :rtype: str
+
         """
 
         return self.__grant_type
@@ -165,6 +164,7 @@ def access_token(self):
 
         :returns: java web token
         :rtype: str
+
         """
         return self.__access_token
 
@@ -174,6 +174,7 @@ def name(self):
 
         :returns: name
         :rtype: str
+
         """
 
         return self.__name
@@ -184,6 +185,7 @@ def thing_id(self):
 
         :returns: identifier
         :rtype: str
+
         """
 
         return self.__thing_id
@@ -866,10 +868,12 @@ def to_json(self):
         return self.dt_json
 
     def to_subthing_json(self):
-        """
+        """Returns a dictionary representing this thing in it's current state
+        as a subordinate thing. This representation should be used for
+        subordinate things in s3i repository entries.
 
-        :returns:
-        :rtype:
+        :returns: Representation of this object as a subordinate thing
+        :rtype: dict
 
         """
 
@@ -887,6 +891,15 @@ def to_subthing_json(self):
         return json_out
 
     def to_subthing_dir_json(self):
+        """Returns a dictionary representing this thing in it's current state
+        as a subordinate thing. This representation should be used for
+        subordinate things in s3i directory entries.
+
+        :returns: Representation of this object as a subordinate thing.
+        :rtype: dict
+
+        """
+
         json_out = {"class": "ml40::Thing", "identifier": self.thing_id, "links": []}
         for key in self.roles.keys():
             role_entry = {"association": "roles", "target": self.roles[key].to_json()}