Improve return and raises values for documentation

Change-Id: Ice8ba6cf38f1d0a38de9bc6ef73a6252c4c3fbf4

cerberus/api/v1/controllers/plugins.py

@@ -91,8 +91,7 @@ class PluginsController(base.BaseController):
     def get_all(self):
         """ Get a list of plugins loaded by Cerberus manager
 
-        :return: PluginResourceCollection : a list of plugins loaded by
-        Cerberus manager
+        :return: a list of plugins loaded by Cerberus manager
         :raises:
             HTTPServiceUnavailable: an error occurred in Cerberus Manager or
             the service is unavailable

cerberus/api/v1/controllers/security_alarms.py

@@ -49,8 +49,10 @@ class SecurityAlarmsController(base.BaseController):
     @wsme_pecan.wsexpose(alarm_models.SecurityAlarmResourceCollection)
     def get_all(self):
         """ Get stored security alarms.
-        :return: list of security alarms for one or all projects depending on
-        context of the token.
+
+        :return: list of security alarms
+        :raises:
+            HTTPNotFound: Any database error
         """
         try:
             security_alarms = self.list_security_alarms()
@@ -93,7 +95,12 @@ class SecurityAlarmController(base.BaseController):
     @wsme_pecan.wsexpose(alarm_models.SecurityAlarmResource,
                          wtypes.text)
     def get(self):
-        """Get security alarm in db"""
+        """Get security alarm in db
+
+        :return: a security alarm
+        :raises:
+            HTTPNotFound: Alarm not found or any database error
+        """
         try:
             security_alarm = self.get_security_alarm(self._uuid)
         except errors.DbError:
@@ -108,7 +115,8 @@ class SecurityAlarmController(base.BaseController):
         """Modify the ticket id associated to a security alarm in db.
 
         :param ticket_id: the ticket_id to store in db.
-
+        :raises:
+            HTTPNotFound: Alarm not found or any database error
         """
         try:
             db.security_alarm_update_ticket_id(self._uuid, ticket_id)

cerberus/api/v1/controllers/security_reports.py

@@ -50,8 +50,10 @@ class SecurityReportsController(base.BaseController):
     @wsme_pecan.wsexpose(report_models.SecurityReportResourceCollection)
     def get_all(self):
         """ Get stored security reports.
-        :return: list of security reports for one or all projects depending on
-        context of the token.
+
+        :return: list of security reports
+        :raises:
+            HTTPNotFound: Any database error
         """
         ctx = pecan.request.context
         try:
@@ -102,7 +104,12 @@ class SecurityReportController(base.BaseController):
     @wsme_pecan.wsexpose(report_models.SecurityReportResource,
                          wtypes.text)
     def get(self):
-        """Get security report in db. """
+        """Get security report in db.
+
+        :return: a security report
+        :raises:
+            HTTPNotFound: Report not found or any database error
+        """
         try:
             security_report = self.get_security_report(self._id)
         except errors.DbError:
@@ -117,7 +124,8 @@ class SecurityReportController(base.BaseController):
         """Modify the ticket id associated to a security report in db.
 
         :param ticket_id: the ticket_id to store in db.
-
+        :raises:
+            HTTPNotFound: Report not found or any database error
         """
         try:
             db.security_report_update_ticket_id(self._id, ticket_id)

cerberus/api/v1/controllers/tasks.py

@@ -44,7 +44,11 @@ class ActionController(base.BaseController):
 
     @wsme_pecan.wsexpose(None, wtypes.text)
     def stop(self, task_id):
-        """Stop task"""
+        """Stop task
+
+        :raises:
+            HTTPBadRequest: task not found or impossible to stop it
+        """
         try:
             self.stop_task(task_id)
         except rpc.RemoteError:
@@ -53,15 +57,23 @@ class ActionController(base.BaseController):
 
     @wsme_pecan.wsexpose(None, wtypes.text)
     def force_delete(self, task_id):
-        """Force delete task"""
+        """Force delete task
+
+        :raises:
+            HTTPNotFound: task is not found
+        """
         try:
             self.force_delete_task(task_id)
         except rpc.RemoteError as e:
-            raise exc.HTTPBadRequest(explanation=e.value)
+            raise exc.HTTPNotFound(explanation=e.value)
 
     @wsme_pecan.wsexpose(None, wtypes.text)
     def restart(self, task_id):
-        """Restart delete task"""
+        """Restart delete task
+
+        :raises:
+            HTTPBadRequest: task not found or impossible to restart it
+        """
         try:
             self.restart_task(task_id)
         except rpc.RemoteError as e:
@@ -119,10 +131,12 @@ class TasksController(base.BaseController):
 
     @wsme_pecan.wsexpose(task_models.TaskResourceCollection)
     def get_all(self):
-        """ List tasks
+        """ List tasks handled by Cerberus Manager.
+
         :return: list of tasks
         :raises:
-            HTTPBadRequest
+            HTTPServiceUnavailable: an error occurred in Cerberus Manager or
+            the service is unavailable
         """
         try:
             tasks = self.list_tasks()
@@ -142,14 +156,19 @@ class TasksController(base.BaseController):
     @wsme_pecan.wsexpose(task_models.TaskResource,
                          wtypes.text)
     def get(self, task_id):
-        """ Get details of a task"""
+        """ Get details of a task
+
+        :return: task details
+        :raises:
+            HTTPNotFound: task is not found
+        """
         try:
             task = self.get_task(task_id)
         except rpc.RemoteError:
             raise exc.HTTPNotFound()
         except Exception as e:
             LOG.exception(e)
-            raise
+            raise exc.HTTPNotFound()
         return task_models.TaskResource(initial_data=task)
 
     def create_task(self, task):
@@ -176,7 +195,12 @@ class TasksController(base.BaseController):
     @wsme_pecan.wsexpose(task_models.TaskResource,
                          body=task_models.TaskResource)
     def post(self, task):
-        """Create a task"""
+        """Create a task
+
+        :return: task details
+        :raises:
+            HTTPBadRequest
+        """
 
         try:
             task = self.create_task(task)
@@ -190,11 +214,15 @@ class TasksController(base.BaseController):
 
     @wsme_pecan.wsexpose(None, wtypes.text)
     def delete(self, task_id):
-        """Delete a task"""
+        """Delete a task
+
+        :raises:
+            HTTPNotFound: task does not exist
+        """
         try:
             self.delete_task(task_id)
         except rpc.RemoteError as e:
-            raise exc.HTTPBadRequest(explanation=e.value)
+            raise exc.HTTPNotFound(explanation=e.value)
         except Exception as e:
             LOG.exception(e)
             raise