From 2f214e9f8811c077eea7d280d5b7654f2140780b Mon Sep 17 00:00:00 2001
From: Christof Stocker <stocker.christof@gmail.com>
Date: Fri, 26 May 2017 00:08:32 +0200
Subject: [PATCH] add docstring to Either

---
 docs/usersguide/operations.rst | 34 ++++++++++-----
 src/operations/either.jl       | 77 ++++++++++++++++++++++++++++++++++
 2 files changed, 101 insertions(+), 10 deletions(-)

diff --git a/docs/usersguide/operations.rst b/docs/usersguide/operations.rst
index 5fb4dc79..a0e21f3f 100644
--- a/docs/usersguide/operations.rst
+++ b/docs/usersguide/operations.rst
@@ -552,27 +552,41 @@ Stochastic Branches
 
 .. class:: Either
 
-   Allows for choosing between different ImageOperations at
-   random. This is particularly useful if one for example wants
-   to first either rotate the image 90 degree clockwise or
+   Allows for choosing between different operations at random
+   when applied. This is particularly useful if one for example
+   wants to first either rotate the image 90 degree clockwise or
    anticlockwise (but never both) and then apply some other
    operation(s) afterwards.
 
+   When compiling a pipeline, :class:`Either` will analyze the
+   provided operations in order to identify the most preferred
+   way to apply the individual operation when sampled, that is
+   supported by all given operations. This way the output of
+   applying :class:`Either` will be inferable and the whole
+   pipeline will remain type-stable, even though randomness is
+   involved.
+
    By default each specified image operation has the same
-   probability of occurance. This default behaviour can be
-   overwritten by specifying the "chance" manually.
+   probability of occurrence. This default behaviour can be
+   overwritten by specifying the chance manually.
 
 .. code-block:: jlcon
 
-   julia> Either(FlipX(), FlipY())
+   julia> FlipX() * FlipY()
    Augmentor.Either (1 out of 2 operation(s)):
      - 50% chance to: Flip the X axis
      - 50% chance to: Flip the Y axis
 
-   julia> Either(0.6=>FlipX(), 0.4=>FlipY())
+   julia> Either(FlipX(), FlipY())
    Augmentor.Either (1 out of 2 operation(s)):
-     - 60% chance to: Flip the X axis
-     - 40% chance to: Flip the Y axis
+     - 50% chance to: Flip the X axis
+     - 50% chance to: Flip the Y axis
+
+   julia> Either((FlipX(), FlipY(), NoOp()), (1,1,2))
+   Augmentor.Either (1 out of 3 operation(s)):
+     - 25% chance to: Flip the X axis
+     - 25% chance to: Flip the Y axis
+     - 50% chance to: No operation
 
    julia> Either(1=>FlipX(), 1=>FlipY(), 2=>NoOp())
    Augmentor.Either (1 out of 3 operation(s)):
@@ -580,7 +594,7 @@ Stochastic Branches
      - 25% chance to: Flip the Y axis
      - 50% chance to: No operation
 
-   julia> Either((FlipX(), FlipY(), NoOp()), (1,1,2))
+   julia> (1=>FlipX()) * (1=>FlipY()) * (2=>NoOp())
    Augmentor.Either (1 out of 3 operation(s)):
      - 25% chance to: Flip the X axis
      - 25% chance to: Flip the Y axis
diff --git a/src/operations/either.jl b/src/operations/either.jl
index fbaba2ae..28514c8f 100644
--- a/src/operations/either.jl
+++ b/src/operations/either.jl
@@ -1,3 +1,80 @@
+"""
+    Either <: Augmentor.Operation
+
+Description
+--------------
+
+Allows for choosing between different `Augmentor.Operations` at
+random when applied. This is particularly useful if one for
+example wants to first either rotate the image 90 degree
+clockwise or anticlockwise (but never both) and then apply some
+other operation(s) afterwards.
+
+When compiling a pipeline, `Either` will analyze the provided
+`operations` in order to identify the most preferred way to apply
+the individual operation when sampled, that is supported by all
+given `operations`. This way the output of applying `Either` will
+be inferable and the whole pipeline will remain type-stable, even
+though randomness is involved.
+
+By default each specified image operation has the same
+probability of occurrence. This default behaviour can be
+overwritten by specifying the `chance` manually.
+
+Usage
+--------------
+
+    Either(operations, [chances])
+
+    Either(operations...; [chances])
+
+    Either(pairs...)
+
+    *(operations...)
+
+    *(pairs...)
+
+Arguments
+--------------
+
+- **`operations`** : `NTuple` or `Vararg` of `Augmentor.Operation`
+    that denote the possible choices to sample from when applied.
+
+- **`chances`** : Optional. Denotes the relative chances for an
+    operation to be sampled. Has to contain the same number of
+    elements as `operations`. Either an `NTuple` of numbers if
+    specified as positional argument, or alternatively a
+    `AbstractVector` of numbers if specified as a keyword
+    argument. If omitted every operation will have equal
+    probability of occurring.
+
+- **`pairs`** : `Vararg` of `Pair{<:Real,<:Augmentor.Operation}`.
+    A compact way to specify an operation and its chance of
+    occurring together.
+
+Examples
+--------------
+
+```julia
+using Augmentor
+img = testpattern()
+
+# all three operations have equal chance of occuring
+augment(img, Either(FlipX(), FlipY(), NoOp()))
+augment(img, FlipX() * FlipY() * NoOp())
+
+# NoOp is twice as likely as either FlipX or FlipY
+augment(img, Either(1=>FlipX(), 1=>FlipY(), 2=>NoOp()))
+augment(img, Either(FlipX(), FlipY(), NoOp(), chances=[1,1,2]))
+augment(img, Either((FlipX(), FlipY(), NoOp()), (1,1,2)))
+augment(img, (1=>FlipX()) * (1=>FlipY()) * (2=>NoOp()))
+```
+
+see also
+--------------
+
+[`augment`](@ref)
+"""
 immutable Either{N,T<:Tuple} <: Operation
     operations::T
     chances::SVector{N,Float64}