Write docstrings

docs/conf.py

@@ -177,3 +177,6 @@ epub_exclude_files = ['search.html']
 
 
 # -- Extension configuration -------------------------------------------------
+
+# Concatenate the class' and __init__'s docstrings when documenting a class
+autoclass_content = 'both'

urbantz/delivery.py

@@ -10,19 +10,58 @@ class Delivery(object):
     """
 
     def __init__(self, id):
+        """
+        :param str id: A delivery ID.
+        """
         self.id = id
+        """
+        The delivery ID.
+
+        :type: str
+        """
+
         self.last_updated = None
+        """
+        Last API update date/time. Is None if data has never been fetched
+        from the API.
+
+        :type: datetime or None
+        """
+
         self.position = None
+        """
+        Coordinates of the delivery truck's position.
+
+        :type: urbantz.utils.Coordinates
+        """
+
         self.destination = None
+        """
+        Coordinates of the delivery destination.
+
+        :type: urbantz.utils.Coordinates
+        """
 
     def __repr__(self):
         return '{}({})'.format(self.__class__.__name__, self.id)
 
     @property
     def api_url(self):
+        """
+        URL pointing to the API endpoint to use for the specific delivery.
+
+        :type: str
+        """
         return 'https://backend.urbantz.com/public/task/tracking/' + self.id
 
     def update(self):
+        """
+        Fetch the latest delivery information from the API.
+
+        :raises requests.exceptions.HTTPError: If the response has an
+           HTTP 4xx or 5xx code.
+        :raises urbantz.exceptions.APIError: If the API returned an error.
+        """
         resp = requests.get(self.api_url)
         resp.raise_for_status()
         data = resp.json()

urbantz/exceptions.py

@@ -1,6 +1,14 @@
 class APIError(Exception):
+    """
+    An error returned by the UrbanTZ API.
+    This does not include HTTP errors.
+    """
 
     def __init__(self, error):
+        """
+        :param error: Parsed JSON error from the API.
+        :type error: dict
+        """
         self.message = error.get('message')
         self.code = error.get('code')
 

urbantz/utils.py

@@ -10,7 +10,10 @@ class Coordinates(object):
 
     def __init__(self, lat=0, lng=0):
         """
-        Coordinates from decimal degrees
+        Get coordinates from decimal degrees.
+
+        :param float lat: Latitude in decimal degrees.
+        :param float lng: Longitude in decimal degrees.
         """
         self.lat = lat
         self.lng = lng
@@ -82,11 +85,22 @@ class Coordinates(object):
         return self.__class__(lat=ceil(self.lat), lng=ceil(self.lng))
 
     def to_radians(self):
+        """
+        Convert to a ``(lat, lng)`` tuple in radians.
+
+        :returns: Coordinates in radians.
+        :rtype: tuple(float, float)
+        """
         return tuple(map(radians, self))
 
     def distance(self, other):
         """
-        Compute Haversine distance between two coordinates.
+        Compute Haversine distance between two coordinates in meters.
+
+        :param other: Another pair of coordinates to compute distance against.
+        :type other: Coordinates
+        :returns: Distance between the two coordinates, in meters.
+        :rtype: float
         """
         if not hasattr(other, 'to_radians'):
             raise NotImplementedError(
@@ -100,9 +114,19 @@ class Coordinates(object):
     def toJSON(self):
         """
         Convert to UrbanTZ JSON geometry
+
+        :returns: UrbanTZ-compatible JSON geometry data
+        :rtype: list(float)
         """
         return [self.lng, self.lat]
 
     @staticmethod
     def fromJSON(geometry):
+        """
+        Get a Coordinates instance from parsed UrbanTZ JSON geometry data.
+
+        :param geometry: Parsed UrbanTZ geometry data: a list holding
+           ``[lng, lat]`` in decimal degrees.
+        :type geometry: list(float)
+        """
         return Coordinates(lng=geometry[0], lat=geometry[1])