From 6f8d1b5f1a7df608192bcc66a9a5f6b4340fc49d Mon Sep 17 00:00:00 2001
From: Chouffe <chouffe.caillau@gmail.com>
Date: Sun, 3 Mar 2019 18:19:50 +0100
Subject: [PATCH] [clojure-package] improve docstrings in `image.clj`

---
 .../src/org/apache/clojure_mxnet/image.clj    | 76 +++++++++++++++++--
 1 file changed, 69 insertions(+), 7 deletions(-)

diff --git a/contrib/clojure-package/src/org/apache/clojure_mxnet/image.clj b/contrib/clojure-package/src/org/apache/clojure_mxnet/image.clj
index e2e87ed47e2f..7fb603e500b9 100644
--- a/contrib/clojure-package/src/org/apache/clojure_mxnet/image.clj
+++ b/contrib/clojure-package/src/org/apache/clojure_mxnet/image.clj
@@ -16,6 +16,7 @@
 ;;
 
 (ns org.apache.clojure-mxnet.image
+  "Image API of Clojure package."
   (:require [t6.from-scala.core :refer [$ $$] :as $]
             [org.apache.clojure-mxnet.dtype :as dtype]
             [org.apache.clojure-mxnet.ndarray :as ndarray]
@@ -37,7 +38,18 @@
   (s/keys :opt-un [::color-flag ::to-rgb ::output]))
 
 (defn decode-image
-  "Decodes an image from an input stream"
+  "Decodes an image from an input stream with OpenCV
+    `input-stream`: `InputStream` - Contains the binary encoded image
+    `color-flag`: 0 or 1 - Convert decoded image to grayscale (0) or color (1)
+    `to-rgb`: boolean - Whether to convert decoded image to mxnet's default RGB
+            format (instead of opencv's default BGR)
+    `output`: nil or `NDArray`
+    returns: `NDArray` with dtype uint8
+
+  Ex:
+    (decode-image input-stream)
+    (decode-image input-stream {:color-flag 1})
+    (decode-image input-stream {:color-flag 0 :output nd})"
   ([input-stream {:keys [color-flag to-rgb output]
                   :or {color-flag COLOR to-rgb true output nil}
                   :as opts}]
@@ -54,7 +66,19 @@
   (s/or :none nil? :some ::to-rgb))
 
 (defn read-image
-  "Reads an image file and returns an ndarray"
+  "Reads an image file and returns an ndarray with OpenCV. It returns image in
+   RGB by default instead of OpenCV's default BGR.
+    `filename`: string - Name of the image file to be loaded
+    `color-flag`: 0 or 1 - Convert decoded image to grayscale (0) or color (1)
+    `to-rgb`: boolean - Whether to convert decoded image to mxnet's default RGB
+            format (instead of opencv's default BGR)
+    `output`: nil or `NDArray`
+    returns: `NDArray` with dtype uint8
+
+   Ex:
+     (read-image \"cat.jpg\")
+     (read-image \"cat.jpg\" {:color-flag 0})
+     (read-image \"cat.jpg\" {:color-flag 1 :output nd})"
   ([filename {:keys [color-flag to-rgb output]
               :or {color-flag nil to-rgb nil output nil}
               :as opts}]
@@ -74,7 +98,17 @@
 (s/def ::optional-int (s/or :none nil? :some int?))
 
 (defn resize-image
-  "Resizes the image array to (width, height)"
+  "Resizes the image array to (width, height)
+   `input`: `NDArray` - source image in NDArray
+   `w`: int - Width of resized image
+   `h`: int - Height of resized image
+   `interpolation`: Interpolation method. Default is INTER_LINEAR
+   `ouput`: nil or `NDArray`
+   returns: `NDArray`
+
+   Ex:
+     (resize-image nd-img 300 300)
+     (resize-image nd-img 28 28 {:output nd})"
   ([input w h {:keys [interpolation output]
                :or {interpolation nil output nil}
                :as opts}]
@@ -88,7 +122,21 @@
    (resize-image input w h {})))
 
 (defn apply-border
-  "Pad image border"
+  "Pad image border with OpenCV.
+   `input`: `NDArray` - source image in NDArray
+   `top`: int - Top margin
+   `bottom`: int - Bottom margin
+   `left`: int - Left margin
+   `right`: int - Right margin
+   `fill-type`: nil or Filling type - Default BORDER_CONSTANT
+   `value`: nil or double - Deprecated, use `values` instead
+   `values`: Fill with value(RGB or gray), up to 4 channels
+   `output`: nil or `NDArray`
+   returns: `NDArray`
+
+   Ex:
+     (apply-border img-nd 1 1 1 1)
+     (apply-border img-nd 3 3 0 0)"
   ([input top bottom left right
     {:keys [fill-type value values output]
      :or {fill-type nil value nil values nil output nil}
@@ -109,7 +157,17 @@
    (apply-border input top bottom left right {})))
 
 (defn fixed-crop
-  "Return a fixed crop of the image"
+  "Return a fixed crop of the image.
+   `input`: `NDArray` - Source image in NDArray
+   `x0`: int - Starting x point
+   `y0`: int - Starting y point
+   `w`: int - Width of the image
+   `h`: int - Height of the image
+   returns: cropped `NDArray`
+
+   Ex:
+     (fixed-crop nd-img 0 0 28 28)
+     (fixed-crop nd-img 10 0 100 300)"
   [input x0 y0 w h]
   (util/validate! ::ndarray input "Invalid input array")
   (util/validate! ::int x0 "Invalid starting x coordinate")
@@ -119,7 +177,9 @@
   (Image/fixedCrop input x0 y0 w h))
 
 (defn rgb-array?
-  "Returns whether the ndarray is in the RGB format"
+  "Returns whether the ndarray is in the RGB format
+   `input`: `NDArray` - Source image in NDArray
+   returns: boolean"
   [input]
   (util/validate! ::ndarray input "Invalid input array")
   (let [shape (ndarray/shape-vec input)]
@@ -133,7 +193,9 @@
   (s/and ::ndarray ::all-bytes ::rgb-array))
 
 (defn to-image
-  "Convert a NDArray image in RGB format to a real image"
+  "Convert a NDArray image in RGB format to a real image.
+   `input`: `NDArray` - Source image in NDArray
+   returns: `BufferedImage`"
   [input]
   (util/validate! ::to-image-ndarray input "Invalid input array")
   (Image/toImage input))