From ed13749abe0d599dd3900cb7361946e36ba4da73 Mon Sep 17 00:00:00 2001
From: Joel Collins <joel@jtcollins.net>
Date: Tue, 7 Jan 2020 15:04:47 +0000
Subject: [PATCH] Improved documentation

---
 .../api/v2/views/actions/camera.py            | 28 +++++++-----
 .../api/v2/views/actions/stage.py             | 43 +++++++++++--------
 2 files changed, 44 insertions(+), 27 deletions(-)

diff --git a/openflexure_microscope/api/v2/views/actions/camera.py b/openflexure_microscope/api/v2/views/actions/camera.py
index bcb3cd20..70b00380 100644
--- a/openflexure_microscope/api/v2/views/actions/camera.py
+++ b/openflexure_microscope/api/v2/views/actions/camera.py
@@ -25,13 +25,19 @@ class CaptureAPI(Resource):
 
     @use_args(
         {
-            "filename": fields.String(),
-            "temporary": fields.Boolean(missing=False),
+            "filename": fields.String(example="MyFileName"),
+            "temporary": fields.Boolean(
+                missing=False, description="Delete capture on shutdown"
+            ),
             "use_video_port": fields.Boolean(missing=False),
-            "bayer": fields.Boolean(missing=False),
-            "metadata": fields.Dict(missing={}),
-            "tags": fields.List(fields.String, missing=[]),
-            "resize": fields.Dict(missing=None),  # TODO: Validate keys
+            "bayer": fields.Boolean(
+                missing=False, description="Store raw bayer data in file"
+            ),
+            "metadata": fields.Dict(missing={}, example={"Client": "SwaggerUI"}),
+            "tags": fields.List(fields.String, missing=[], example=["docs"]),
+            "resize": fields.Dict(
+                missing=None, example={"width": 640, "height": 480}
+            ),  # TODO: Validate keys
         }
     )
     @marshal_with(capture_schema)
@@ -85,6 +91,9 @@ class GPUPreviewStartAPI(Resource):
     """
 
     def post(self):
+        """
+        Start the onboard GPU preview.
+        """
         microscope = find_device("openflexure_microscope")
         payload = JsonResponse(request)
 
@@ -104,11 +113,10 @@ class GPUPreviewStartAPI(Resource):
 
 
 class GPUPreviewStopAPI(Resource):
-    """
-    Start the onboard GPU preview.
-    """
-
     def post(self):
+        """
+        Stop the onboard GPU preview.
+        """
         microscope = find_device("openflexure_microscope")
         microscope.camera.stop_preview()
         return jsonify(microscope.state)
diff --git a/openflexure_microscope/api/v2/views/actions/stage.py b/openflexure_microscope/api/v2/views/actions/stage.py
index e1df4553..e04f448c 100644
--- a/openflexure_microscope/api/v2/views/actions/stage.py
+++ b/openflexure_microscope/api/v2/views/actions/stage.py
@@ -1,6 +1,13 @@
 from openflexure_microscope.api.utilities import JsonResponse
 from openflexure_microscope.common.flask_labthings.resource import Resource
 from openflexure_microscope.common.flask_labthings.find import find_device
+from openflexure_microscope.common.flask_labthings.decorators import (
+    use_args,
+    marshal_with,
+    doc,
+)
+from openflexure_microscope.common.flask_labthings import fields
+
 from openflexure_microscope.utilities import axes_to_array, filter_dict
 
 from flask import Blueprint, jsonify, request
@@ -9,21 +16,23 @@ import logging
 
 
 class MoveStageAPI(Resource):
-    """
-    Handle stage movements.
-    """
-
-    def post(self):
+    @use_args(
+        {
+            "absolute": fields.Boolean(default=False, example=False),
+            "x": fields.Int(default=0, example=100),
+            "y": fields.Int(default=0, example=100),
+            "z": fields.Int(default=0, example=20),
+        }
+    )
+    def post(self, args):
+        """
+        Move the microscope stage in x, y, z
+        """
         microscope = find_device("openflexure_microscope")
-        # Create response object
-        payload = JsonResponse(request)
-        logging.debug(payload.json)
 
         # Handle absolute positioning (calculate a relative move from current position and target)
-        if (payload.param("absolute") is True) and (
-            microscope.stage
-        ):  # Only if stage exists
-            target_position = axes_to_array(payload.json, ["x", "y", "z"])
+        if (args.get("absolute")) and (microscope.stage):  # Only if stage exists
+            target_position = axes_to_array(args, ["x", "y", "z"])
             logging.debug("TARGET: {}".format(target_position))
             position = [
                 target_position[i] - microscope.stage.position[i] for i in range(3)
@@ -32,7 +41,7 @@ class MoveStageAPI(Resource):
 
         else:
             # Get coordinates from payload
-            position = axes_to_array(payload.json, ["x", "y", "z"], [0, 0, 0])
+            position = axes_to_array(args, ["x", "y", "z"], [0, 0, 0])
 
         logging.debug(position)
 
@@ -48,11 +57,11 @@ class MoveStageAPI(Resource):
 
 
 class ZeroStageAPI(Resource):
-    """
-    Zero stage coordinates 
-    """
-
     def post(self):
+        """
+        Zero the stage coordinates.
+        Does not move the stage, but rather makes the current position read as [0, 0, 0]
+        """
         microscope = find_device("openflexure_microscope")
         microscope.stage.zero_position()