docs: update the gem API documentation

- add docs for missing options
- convert docs to YARD and add ability to generate the html
- remove the unmaintained, duplicated docs from README
- fix some unrelated typos in README

Gemfile

@@ -12,3 +12,4 @@ gem 'rspec'
 gem 'rubocop'
 gem 'simplecov'
 gem 'super_diff'
+gem 'yard'

Gemfile.lock

@@ -134,6 +134,7 @@ GEM
       patience_diff
     thor (1.3.2)
     unicode-display_width (2.6.0)
+    yard (0.9.37)
 
 PLATFORMS
   x86_64-linux
@@ -147,6 +148,7 @@ DEPENDENCIES
   rubocop
   simplecov
   super_diff
+  yard
 
 BUNDLED WITH
    2.4.22

Makefile

@@ -20,3 +20,6 @@ stop:
 clean:
 	docker ps -q --filter name=${CONTAINER_NAME} | grep -q . && docker container stop ${CONTAINER_NAME} || true
 	docker image ls -q ${IMAGE_NAME} | grep -q . && docker image rm ${IMAGE_NAME} || true
+
+docs:
+	docker run -it --rm --name ${CONTAINER_NAME} -v ${PWD}:/app ${IMAGE_NAME}:latest yard doc lib/morandi.rb

README.md

@@ -1,11 +1,10 @@
 # Morandi
 
-Library of simple image manipulations - replicating the behaviour of
-morandi-js.
+Library of simple image manipulations - replicating the behaviour of morandi-js.
 
 ## Installation
 
-Install `liblcms2-utils` to provide the `jpgicc` command used by `Morandi::ProfiledPixbuf`. Also ensure that your host system has `imagemagick` installed, which is required bi the `colorscore` gem.
+Install `liblcms2-utils` to provide the `jpgicc` command used by `Morandi::ProfiledPixbuf`. Also ensure that your host system has `imagemagick` installed, which is required by the `colorscore` gem.
 
 Add this line to your application's Gemfile:
 
@@ -22,26 +21,10 @@ Or install it yourself as:
 ## Usage
 
 ````
-   Morandi.process(in_file, settings, out_file)
+   Morandi.process(source, options, target_path)
 ````
-- in_file is a string
-- settings is a hash
-- out_file is a string
-
-Settings Key | Values | Description
--------------|--------|---------------
-brighten     | Integer -20..20 | Change image brightness
-gamma        | Float  | Gamma correct image
-contrast     | Integer -20..20  | Change image contrast
-sharpen      | Integer -5..5  | Sharpen / Blur (negative value)
-redeye       | Array[[Integer,Integer],...]  | Apply redeye correction at point
-angle        | Integer 0,90,180,270  | Rotate image
-straighten   | Float | Rotate by N degrees and zoom
-crop         | Array[Integer,Integer,Integer,Integer] | Crop image
-fx           | String greyscale,sepia,bluetone | Apply colour filters
-border-style  | String square,retro | Set border style
-background-style  | String retro,black,white | Set border colour
-quality       | String '1'..'100' | Set JPG compression value, defaults to 97%
+
+For the detailed documentation of options see `lib/morandi.rb`
 
 ## Contributing
 
@@ -53,4 +36,4 @@ quality       | String '1'..'100' | Set JPG compression value, defaults to 97%
 
 ### Development
 
-Since this gem depends on the `liblcms2-utils` library, which can be awkward to install on some operating systems, we also provide a development docker image. A Makefile is also provided as a simple CLI. To build the image and run the container, type `make` from the project root. The container itself runs `guard` as its main process. Running the container via `make` will drop you into the guard  prompt, which will run the test suite whenever any of the source code or tests are changed. The tests can be kicked-off manually via the `all` command at the guard prompt. Individual test can be run using the `focus: true` annotation on an example or describe block. If you need to access a bash shell in the container (for example, to run rubocop), use the command `make shell`.
+Since this gem depends on the `liblcms2-utils` library, which can be awkward to install on some operating systems, we also provide a development docker image. A Makefile is also provided as a simple CLI. To build the image and run the container, type `make` from the project root. The container itself runs `guard` as its main process. Running the container via `make` will drop you into the guard prompt, which will run the test suite whenever any of the source code or tests are changed. The tests can be kicked-off manually via the `all` command at the guard prompt. Individual test can be run using the `focus: true` annotation on an example or describe block. If you need to access a bash shell in the container (for example, to run rubocop), use the command `make shell`.

lib/morandi.rb

@@ -14,26 +14,34 @@
 module Morandi
   module_function
 
-  # The main entry point for the libray
+  # The main entry point for the library
   #
   # @param source [String|GdkPixbuf::Pixbuf] source image
-  # @param options [Hash]
+  # @param [Hash] options The options describing expected processing to perform
+  # @option options [Integer] 'brighten' Change image brightness (-20..20)
+  # @option options [Float] 'gamma' Gamma correct image
+  # @option options [Integer] 'contrast' Change image contrast (-20..20)
+  # @option options [Integer] 'sharpen' Sharpen (1..5) / Blur (-1..-5)
+  # @option options [Array[[Integer,Integer],...]] 'redeye' Apply redeye correction at point
+  # @option options [Integer] 'angle' Rotate image clockwise by multiple of 90 (0, 90, 180, 270)
+  # @option options [Array[Integer,Integer,Integer,Integer]] 'crop' Crop image (x, y, width, height)
+  # @option options [String] 'fx' Apply colour filters ('greyscale', 'sepia', 'bluetone')
+  # @option options [String] 'border-style' Set border style ('square', 'retro')
+  # @option options [String] 'background-style' Set border colour ('retro', 'black', 'white')
+  # @option options [String] 'quality' ('97') Set JPG compression value ('1' to '100')
+  # @option options [Integer] 'output.max' Downscales the image to fit within the square of given size before
+  #                                        processing to limit the required resources
+  # @option options [Integer] 'output.width' Sets desired width of resulting image
+  # @option options [Integer] 'output.height' Sets desired height of resulting image
+  # @option options [TrueClass|FalseClass] 'image.auto-crop' (true) If the output dimensions are set and this is true,
+  #                                                                image is cropped automatically to the desired
+  #                                                                dimensions.
+  # @option options [TrueClass|FalseClass] 'output.limit' (false) If the output dimensions are defined and this is true,
+  #                                                              the output image is scaled down to fit within square of
+  #                                                              size of the longer edge (ignoring shorter dimension!)
   # @param target_path [String] target location for image
-  # @param local_options [Hash]
-  #
-  # Settings Key | Values | Description
-  # -------------|--------|---------------
-  # brighten     | Integer -20..20 | Change image brightness
-  # gamma        | Float  | Gamma correct image
-  # contrast     | Integer -20..20  | Change image contrast
-  # sharpen      | Integer -5..5  | Sharpen / Blur (negative value)
-  # redeye       | Array[[Integer,Integer],...]  | Apply redeye correction at point
-  # angle        | Integer 0,90,180,270  | Rotate image
-  # crop         | Array[Integer,Integer,Integer,Integer] | Crop image
-  # fx           | String greyscale,sepia,bluetone | Apply colour filters
-  # border-style  | String square,retro | Set border style
-  # background-style  | String retro,black,white | Set border colour
-  # quality       | String '1'..'100' | Set JPG compression value, defaults to 97%
+  # @param local_options [Hash] Hash of options other than desired transformations
+  # @option local_options [String] 'path.icc' A path to store the input after converting to sRGB colour space
   def process(source, options, target_path, local_options = {})
     pro = ImageProcessor.new(source, options, local_options)
     pro.result