Improve documentation

- Include the doc strings for several functions in the manual
- Remove duplicate content of the documentation
- Some further minor tweaks

Author: fingolfin

docs/src/utilities.md

@@ -32,36 +32,11 @@ julia> MacroTools.shortdef(ex)
 More generally it's also possible to use `splitdef` and `combinedef` to handle
 the full range of function syntax.
 
-`splitdef(def)` matches a function definition of the form
-
-```julia
-function name(args; kwargs)::rtype where {whereparams}
-   body
-end
-```
-
-and returns `Dict(:name=>..., :args=>..., etc.)`. The definition can be rebuilt by
-calling `MacroTools.combinedef(dict)`, or explicitly with
-
-```julia
-rtype = get(dict, :rtype, :Any)
-:(function $(dict[:name])($(dict[:args]...);
-                          $(dict[:kwargs]...))::$rtype where {$(dict[:whereparams]...)}
-  $(dict[:body].args...)
-end)
-```
-
-`splitarg(arg)` matches function arguments (whether from a definition or a function call)
-such as `x::Int=2` and returns `(arg_name, arg_type, slurp, default)`. `default` is
-`nothing` when there is none. For example:
-
-```julia
-julia> map(splitarg, (:(f(y, a=2, x::Int=nothing, args...))).args[2:end])
-4-element Array{Tuple{Symbol,Symbol,Bool,Any},1}:
- (:y, :Any, false, nothing)  
- (:a, :Any, false, 2)        
- (:x, :Int, false, :nothing)
- (:args, :Any, true, nothing)
+```@docs
+MacroTools.splitdef
+MacroTools.combinedef
+MacroTools.splitarg
+MacroTools.combinearg
 ```
 
 ## Other Utilities

src/utils.jl

@@ -289,16 +289,7 @@ end
 ```
 
 and return `Dict(:name=>..., :args=>..., etc.)`. The definition can be rebuilt by
-calling `MacroTools.combinedef(dict)`, or explicitly with
-
-```julia
-rtype = get(dict, :rtype, :Any)
-all_params = [get(dict, :params, [])..., get(dict, :whereparams, [])...]
-:(function \$(dict[:name]){\$(all_params...)}(\$(dict[:args]...);
-                                            \$(dict[:kwargs]...))::\$rtype
-      \$(dict[:body])
-  end)
-```
+calling `MacroTools.combinedef(dict)`.
 
 See also: [`combinedef`](@ref)
 """
@@ -344,6 +335,19 @@ end
 
 `combinedef` is the inverse of [`splitdef`](@ref). It takes a `splitdef`-like Dict
 and returns a function definition.
+
+This function approximately does the following (but more sophisticated to avoid
+emitting parts that did not actually appear in the original function definition.)
+
+```julia
+rtype = get(dict, :rtype, :Any)
+all_params = [get(dict, :params, [])..., get(dict, :whereparams, [])...]
+:(function \$(dict[:name]){\$(all_params...)}(\$(dict[:args]...);
+                                            \$(dict[:kwargs]...))::\$rtype
+      \$(dict[:body])
+  end)
+```
+
 """
 function combinedef(dict::Dict)
   rtype = get(dict, :rtype, nothing)