Merge pull request #1785 from FluxML/logankilpatrick-patch-6

Update train.jl to add a more detailed `train!` docstring

Author: CarloLucibello

src/optimise/train.jl

@@ -82,16 +82,21 @@ batchmemaybe(x::Tuple) = x
 
 """
     train!(loss, params, data, opt; cb)
-
+        
+`train!` uses a `loss` function and training `data` to improve the 
+[Model parameters](@ref) (`params`) based on a pluggable [Optimisers](@ref) (`opt`).
+        
 For each datapoint `d` in `data`, compute the gradient of  `loss` with
 respect to `params` through backpropagation and call the optimizer `opt`.
-
 If `d` is a tuple of arguments to `loss` call `loss(d...)`, else call `loss(d)`.
-
-A callback is given with the keyword argument `cb`. For example, this will print
-"training" every 10 seconds (using [`Flux.throttle`](@ref)):
-    train!(loss, params, data, opt, cb = throttle(() -> println("training"), 10))
-
+        
+To pass trainable parameters, call [`Flux.params`](@ref) with your model or just the 
+layers you want to train, like `train!(loss, params(model), ...)` or `train!(loss, params(model[1:end-2), ...)` respectively.
+
+[Callbacks](@ref) are given with the keyword argument `cb`. For example, this will print "training" 
+every 10 seconds (using [`Flux.throttle`](@ref)):
+`train!(loss, params, data, opt, cb = throttle(() -> println("training"), 10))`
+        
 The callback can call [`Flux.stop`](@ref) to interrupt the training loop.
 
 Multiple optimisers and callbacks can be passed to `opt` and `cb` as arrays.