adds docstrings everywhere

plus improves API index

Author: Stephan Sahm

README.md

@@ -15,8 +15,8 @@ For more details check out the [documentation](https://schlichtanders.github.io/
 The package is soon going to be registered at General, until then you can use it by adding a custom registry.
 ```julia
 using Pkg
-pkg"registry add https://github.com/JuliaRegistries/General"  # central julia repository
-pkg"registry add https://github.com/schlichtanders/SchlichtandersJuliaRegistry.jl"  # custom repository
+pkg"registry add https://github.com/JuliaRegistries/General"  # central julia registry
+pkg"registry add https://github.com/schlichtanders/SchlichtandersJuliaRegistry.jl"  # custom registry
 pkg"add DataTypesBasic"
 ```
 

docs/src/index.md

@@ -7,8 +7,8 @@ This package defines julia implementations for the common types `Option` (aka `M
 
 ```julia
 using Pkg
-pkg"registry add https://github.com/JuliaRegistries/General"  # central julia repository
-pkg"registry add https://github.com/schlichtanders/SchlichtandersJuliaRegistry.jl"  # custom repository
+pkg"registry add https://github.com/JuliaRegistries/General"  # central julia registry
+pkg"registry add https://github.com/schlichtanders/SchlichtandersJuliaRegistry.jl"  # custom registry
 pkg"add DataTypesBasic"
 ```
 

docs/src/library.md

@@ -7,6 +7,62 @@ CurrentModule = DataTypesBasic
 ```@index
 ```
 
-```@autodocs
-Modules = [DataTypesBasic]
+## Identity
+
+```@docs
+Identity
+isidentity
+```
+
+## Const
+
+```@docs
+Const
+Base.isconst(::Const)
+```
+
+## Option
+
+```@docs
+Option
+isoption
+issome
+isnone
+iftrue
+iffalse
+```
+
+## Either
+
+```@docs
+Either
+iseither
+isleft
+isright
+either
+@either
+getleft
+getright
+getleftOption
+getrightOption
+getOption
+```
+
+## Try
+
+```@docs
+Try
+@Try
+@TryCatch
+istry
+issuccess
+isfailure
+getOption
+```
+
+## ContextManager
+```@docs
+ContextManager
+@ContextManager
+Base.run(::ContextManager)
 ```

src/Const.jl

@@ -26,6 +26,8 @@ Base.isconst(other) = false
 
 Base.length(::Const) = 0
 
+# as the length of Const is 0, we intentionally do not support `Base.get`
+
 # const just does nothing, i.e. leaves everything constant
 Base.iterate(c::Const) = nothing
 Base.foreach(f, c::Const) = nothing

src/ContextManager.jl

@@ -1,11 +1,11 @@
-"""
-As ContextManager we denote a computation which has a pre-computation and possibly a cleaning up step
-when run with x->x it is supposed to return x.
-"""
+@doc raw"""
+    ContextManager(func)
 
-"""
-function which expects one argument, which itself is a function. Think of it like the following:
-```
+As ContextManager we denote a computation which has a pre-computation and possibly a cleaning up step.
+
+The single argument is supposed to be a function which expects one argument, the continuation function.
+Think of it like the following:
+```julia
 function contextmanagerready(cont)
   # ... do something before
   value = ... # create some value to work on later
@@ -15,13 +15,57 @@ function contextmanagerready(cont)
 end
 ```
 Now you can wrap it into `ContextManager(contextmanagerready)` and you can use all the context manager
-functionalities right away
+functionalities right away.
+
+There is a simple `@ContextManager` for writing less parentheses
+```julia
+mycontextmanager(value) = @ContextManager function(cont)
+  println("got value = $value")
+  result = cont(value)
+  println("finished value = $value")
+  result
+end
+```
+
+----------------
+
+You can run it in two ways, either by just passing `Base.identity` as the continuation function
+```julia
+julia> mycontextmanager(4)(x -> x)
+got value = 4
+finished value = 4
+```
+or for convenience we also overload `Base.run`
+```julia
+# without any extra arguments runs the contextmanager with Base.identity
+run(mycontextmanager(4))
+# also works with a given continuation, which makes for a nice do-syntax
+run(x -> x, mycontextmanager(4))
+run(mycontextmanager(4)) do x
+  x
+end
+```
 """
 struct ContextManager{F}
   f::F
 end
 
-# one pair of parantheses less
+
+
+"""
+    @ContextManager function(cont); ...; end
+
+There is a simple `@ContextManager` for writing less parentheses
+
+```julia
+mycontextmanager(value) = @ContextManager function(cont)
+  println("got value = $value")
+  result = cont(value)
+  println("finished value = $value")
+  result
+end
+```
+"""
 macro ContextManager(func)
   quote
     ContextManager($(esc(func)))

src/DataTypesBasic.jl

@@ -34,9 +34,9 @@ higher code-reuse and datatype-reuse.
 module DataTypesBasic
 
 export Identity, isidentity, Const,
-  Option, isoption, iftrue, iffalse, getOption, # isnothing, Nothing, Some comes from Base
-  Either, either, @either, iseither, isleft, isright, getleft, getright, getleftOption, getrightOption, flip_left_right,
-  Try, Thrown, @Try, @TryCatch, issuccess, isexception, MultipleExceptions,
+  Option, isoption, issome, isnone, iftrue, iffalse, getOption,
+  Either, either, @either, iseither, isleft, isright, getleft, getright, getOption, getleftOption, getrightOption, flip_left_right,
+  Try, @Try, @TryCatch, istry, issuccess, isexception, Thrown, MultipleExceptions,
   ContextManager, @ContextManager
 
 using Compat

src/Either.jl

@@ -1,3 +1,13 @@
+"""
+    Either{L, R} = Union{Const{L}, Identity{R}}
+    Either{Int, Bool}(true) == Identity(true)
+    Either{Int, Bool}(1) == Const(1)
+    Either{String}("left") == Const("left")
+    Either{String}(:anythingelse) == Identity(:anythingelse)
+
+A very common type to represent Result or Failure.
+We reuse [`Identity`](@ref) as representing "Success" and [`Const`](@ref) for "Failure".
+"""
 const Either{L, R} = Union{Const{L}, Identity{R}}
 Either{L, R}(x::L) where {L, R} = Const(x)
 Either{L, R}(x::R) where {L, R} = Identity(x)
@@ -12,6 +22,18 @@ Base.eltype(::Type{Either}) = Any
 # Helpers for Either
 # ------------------
 
+"""
+    either(:left, bool_condition, "right")
+
+If `bool_condition` is true, it returns the right value, wrapped into [Identity](@ref).
+Else returns left side, wrapped into [Const](@ref).
+
+Example
+-------
+```jldoctest
+either(:left, 1 < 2, "right") == Identity("right")
+```
+"""
 function either(left_false, comparison::Bool, right_true)
   comparison ? Identity(right_true) : Const(left_false)
 end
@@ -36,27 +58,91 @@ macro either(expr::Expr)
   end)
 end
 
+
+"""
+    flip_left_right(Const(1)) == Identity(1)
+    flip_left_right(Identity(:whatever)) == Const(:whatever)
+
+exchanges left and right, i.e. what was Const, becomes an Identity and the other way around.
+"""
 flip_left_right(x::Const) = Identity(x.value)
 flip_left_right(x::Identity) = Const(x.value)
 
+"""
+    iseither(::Const) = true
+    iseither(::Identity) = true
+    iseither(other) = false
+
+check whether something is an [`Either`](@ref)
+"""
 iseither(::Const) = true
 iseither(::Identity) = true
 iseither(other) = false
 
+"""
+    isleft(::Const) = true
+    isleft(::Identity) = false
+
+Identical to [`isconst`](@ref), but might be easier to read when working with `Either`.
+"""
 isleft(::Const) = true
 isleft(::Identity) = false
 
+
+"""
+    isright(::Const) = false
+    isright(::Identity) = true
+
+Identical to [`isidentity`](@ref), but might be easier to read when working with `Either`.
+"""
 isright(::Const) = false
 isright(::Identity) = true
 
+"""
+    getleft(Const(:something)) == :something
+    getleft(Identity(23))  # throws MethodError
+
+Extract a value from a "left" `Const` value. Will result in loud error when used on anything else.
+"""
 getleft(e::Const) = e.value
-# getleft(e::Identity) = nothing  # throw an error if getleft is called on Identity
 
-# getright(e::Const) = nothing  # throw an error if getright is called on Const
+"""
+    getright(Identity(23)) == 23
+    getright(Const(:something))  # throws MethodError
+
+Extract a value from a "right" `Identity` value. Will result in loud error when used on anything else.
+Identical to `Base.get` but explicit about the site (and not defined for other things)
+"""
 getright(e::Identity) = e.value
 
+
+"""
+    getleftOption(Identity(23)) == Option()
+    getleftOption(Const(:something)) == Option(:something)
+
+Convert to option, assuming you want to have the left value be preserved.
+"""
 getleftOption(e::Const) = Option(e.value)
 getleftOption(e::Identity) = Option()
 
+"""
+    getrightOption(Identity(23)) == Option(23)
+    getrightOption(Const(:something)) == Option()
+
+Convert to option, assuming you want to have the right value be preserved.
+Identical to `getOption`, just explicit about the site.
+"""
 getrightOption(e::Const) = Option()
 getrightOption(e::Identity) = e
+
+
+
+"""
+    getOption(Identity(23)) == Option(23)
+    getOption(Const(:something)) == Option()
+
+Convert to option, assuming you want to have the right value be preserved, and the left value represented as
+`Option()`.
+"""
+getOption(e::Const) = Option()
+getOption(e::Identity) = e

src/Identity.jl

@@ -1,3 +1,12 @@
+"""
+    Identity(:anything)
+
+Identity is a simple wrapper, which works as a single-element container.
+
+It can be used as the trivial Monad, and as such can be helpful in monadic
+abstractions. For those who don't know about Monads, just think of it like
+container-abstractions.
+"""
 struct Identity{T}
   value::T
 end
@@ -8,6 +17,12 @@ function Base.show(io::IO, x::Identity)
   print(io, "Identity($(repr(x.value)))")
 end
 
+"""
+    isidentity(Identity(3)) -> true
+    isidentity("anythingelse") -> false
+
+returns true only if given an instance of  [Identity](@ref)
+"""
 isidentity(::Identity) = true
 isidentity(other) = false