Docstring updates

trovebox/api/api_action.py

@@ -9,9 +9,12 @@ class ApiAction(ApiBase):
     """ Definitions of /action/ API endpoints """
     def create(self, target, target_type=None, **kwds):
         """
-        Create a new action and return it.
-        If the target_type parameter isn't specified, it is automatically
-        generated.
+        Endpoint: /action/<target_id>/<target_type>/create.json
+
+        Creates a new action and returns it.
+        The target parameter can either be an id or a Trovebox object.
+        If a Trovebox object is used, the target type is inferred
+        automatically.
         """
         if target_type is None:
             # Determine the target type
@@ -33,7 +36,9 @@ class ApiAction(ApiBase):
 
     def delete(self, action, **kwds):
         """
-        Delete an action.
+        Endpoint: /action/<id>/delete.json
+
+        Deletes an action.
         Returns True if successful.
         Raises a TroveboxError if not.
         """
@@ -43,7 +48,9 @@ class ApiAction(ApiBase):
 
     def view(self, action, **kwds):
         """
-        View an action's contents.
+        Endpoint: /action/<id>/view.json
+
+        Requests all properties of an action.
         Returns the requested action object.
         """
         if not isinstance(action, Action):

trovebox/api/api_activity.py

@@ -9,7 +9,13 @@ from .api_base import ApiBase
 class ApiActivities(ApiBase):
     """ Definitions of /activities/ API endpoints """
     def list(self, filters={}, **kwds):
-        """ Returns a list of Activity objects """
+        """
+        Endpoint: /activities/[<filters>]/list.json
+
+        Returns a list of Activity objects.
+        The filters parameter can be used to narrow down the returned activities.
+        Eg: filters={"type": "photo-upload"}
+        """
         filter_string = self._build_filter_string(filters)
         activities = self._client.get("/activities/%slist.json" % filter_string,
                                       **kwds)["result"]
@@ -17,7 +23,12 @@ class ApiActivities(ApiBase):
         return [Activity(self._client, activity) for activity in activities]
 
     def purge(self, **kwds):
-        """ Purge all activities """
+        """
+        Endpoint: /activities/purge.json
+
+        Purges all activities.
+        Currently not working due to frontend issue #1368
+        """
         if not self._client.post("/activities/purge.json", **kwds)["result"]:
             raise TroveboxError("Purge response returned False")
         return True
@@ -26,7 +37,9 @@ class ApiActivity(ApiBase):
     """ Definitions of /activity/ API endpoints """
     def view(self, activity, **kwds):
         """
-        View an activity's contents.
+        Endpoint: /activity/<id>/view.json
+
+        Requests all properties of an activity.
         Returns the requested activity object.
         """
         if not isinstance(activity, Activity):

trovebox/api/api_album.py

@@ -16,14 +16,20 @@ class ApiAlbums(ApiBase):
 class ApiAlbum(ApiBase):
     """ Definitions of /album/ API endpoints """
     def create(self, name, **kwds):
-        """ Create a new album and return it"""
+        """
+        Endpoint: /album/create.json
+
+        Creates a new album and returns it.
+        """
         result = self._client.post("/album/create.json",
                                    name=name, **kwds)["result"]
         return Album(self._client, result)
 
     def delete(self, album, **kwds):
         """
-        Delete an album.
+        Endpoint: /album/<id>/delete.json
+
+        Deletes an album.
         Returns True if successful.
         Raises a TroveboxError if not.
         """
@@ -44,7 +50,11 @@ class ApiAlbum(ApiBase):
         raise NotImplementedError()
 
     def update(self, album, **kwds):
-        """ Update an album """
+        """
+        Endpoint: /album/<id>/update.json
+
+        Updates an album with the specified parameters.
+        """
         if not isinstance(album, Album):
             album = Album(self._client, {"id": album})
         album.update(**kwds)
@@ -52,7 +62,9 @@ class ApiAlbum(ApiBase):
 
     def view(self, album, **kwds):
         """
-        View an album's contents.
+        Endpoint: /album/<id>/view.json
+
+        Requests all properties of an album.
         Returns the requested album object.
         """
         if not isinstance(album, Album):

trovebox/objects/action.py

@@ -25,7 +25,9 @@ class Action(TroveboxObject):
 
     def delete(self, **kwds):
         """
-        Delete this action.
+        Endpoint: /action/<id>/delete.json
+
+        Deletes this action.
         Returns True if successful.
         Raises a TroveboxError if not.
         """
@@ -38,6 +40,8 @@ class Action(TroveboxObject):
 
     def view(self, **kwds):
         """
+        Endpoint: /action/<id>/view.json
+
         Requests the full contents of the action.
         Updates the action's fields with the response.
         """

trovebox/objects/activity.py

@@ -26,6 +26,8 @@ class Activity(TroveboxObject):
 
     def view(self, **kwds):
         """
+        Endpoint: /activity/<id>/view.json
+
         Requests the full contents of the activity.
         Updates the activity's fields with the response.
         """

trovebox/objects/album.py

@@ -20,7 +20,9 @@ class Album(TroveboxObject):
 
     def delete(self, **kwds):
         """
-        Delete this album.
+        Endpoint: /album/<id>/delete.json
+
+        Deletes this album.
         Returns True if successful.
         Raises a TroveboxError if not.
         """
@@ -44,7 +46,11 @@ class Album(TroveboxObject):
         raise NotImplementedError()
 
     def update(self, **kwds):
-        """ Update this album with the specified parameters """
+        """
+        Endpoint: /album/<id>/update.json
+
+        Updates this album with the specified parameters.
+        """
         result = self._trovebox.post("/album/%s/update.json" %
                                      self.id, **kwds)["result"]
 
@@ -58,7 +64,9 @@ class Album(TroveboxObject):
 
     def view(self, **kwds):
         """
-        Requests the full contents of the album.
+        Endpoint: /album/<id>/view.json
+
+        Requests all properties of an album.
         Updates the album's fields with the response.
         """
         result = self._trovebox.get("/album/%s/view.json" %