Merge #1256

1256: Updated onehot.jl r=CarloLucibello a=Dsantra92

@janEbert @CarloLucibello 
Updated doctstrings and doctests  for onehot.jl and onehot.md

Co-authored-by: Dsantra92 <santradibbo@gmail.com>
Co-authored-by: Deeptendu Santra <santradibbo@gmail.com>

Author: bors[bot]

docs/src/data/onehot.md

@@ -2,7 +2,7 @@
 
 It's common to encode categorical variables (like `true`, `false` or `cat`, `dog`) in "one-of-k" or ["one-hot"](https://en.wikipedia.org/wiki/One-hot) form. Flux provides the `onehot` function to make this easy.
 
-```
+```jldoctest onehot
 julia> using Flux: onehot, onecold
 
 julia> onehot(:b, [:a, :b, :c])
@@ -20,7 +20,7 @@ julia> onehot(:c, [:a, :b, :c])
 
 The inverse is `onecold` (which can take a general probability distribution, as well as just booleans).
 
-```julia
+```jldoctest onehot
 julia> onecold(ans, [:a, :b, :c])
 :c
 
@@ -40,20 +40,20 @@ Flux.onecold
 
 `onehotbatch` creates a batch (matrix) of one-hot vectors, and `onecold` treats matrices as batches.
 
-```julia
+```jldoctest onehot
 julia> using Flux: onehotbatch
 
 julia> onehotbatch([:b, :a, :b], [:a, :b, :c])
-3×3 Flux.OneHotMatrix:
- false   true  false
-  true  false   true
- false  false  false
-
-julia> onecold(ans, [:a, :b, :c])
-3-element Array{Symbol,1}:
-  :b
-  :a
-  :b
+3×3 Flux.OneHotMatrix{Array{Flux.OneHotVector,1}}:
+ 0  1  0
+ 1  0  1
+ 0  0  0
+
+julia> onecold(ans, [:a, :b, :c])	
+3-element Array{Symbol,1}:	
+ :b	
+ :a	
+ :b   
 ```
 
 Note that these operations returned `OneHotVector` and `OneHotMatrix` rather than `Array`s. `OneHotVector`s behave like normal vectors but avoid any unnecessary cost compared to using an integer index directly. For example, multiplying a matrix with a one-hot vector simply slices out the relevant row of the matrix under the hood.

src/onehot.jl

@@ -51,10 +51,11 @@ cudaconvert(x::OneHotMatrix{<:CuArray}) = OneHotMatrix(x.height, cudaconvert(x.d
 """
     onehot(l, labels[, unk])
 
-Create a `OneHotVector` with its `l`-th element `true` based on the
-possible set of `labels`.
-If `unk` is given, return `onehot(unk, labels)` if the input label `l` is not found
-in `labels`; otherwise, it will raise an error.
+Return a `OneHotVector` where only first occourence of `l` in `labels` is `1` and
+all other elements are `0`.
+
+If `l` is not found in labels and  `unk` is present, the function returns
+`onehot(unk, labels)`; otherwise the function raises an error.
 
 # Examples
 ```jldoctest
@@ -86,10 +87,10 @@ end
 """
     onehotbatch(ls, labels[, unk...])
 
-Create a `OneHotMatrix` with a batch of labels based on the
-possible set of `labels`.
-If `unk` is given, return [`onehot(unk, labels)`](@ref) if one of the input
-labels `ls` is not found in `labels`; otherwise it will error.
+Return a `OneHotMatrix` where `k`th column of the matrix is `onehot(ls[k], labels)`.
+
+If one of the input labels `ls` is not found in `labels` and `unk` is given,
+return [`onehot(unk, labels)`](@ref) ; otherwise the function will raise an error.
 
 # Examples
 ```jldoctest