Documentation unclear about Unions and type parameters

[afniedermayer]

The combination of Unions and type parameters seems to cause confusion repeatedly, see https://groups.google.com/forum/#!topic/julia-users/TNebYrm2A8Q for the most recent discussion. Ideally, #3738 would be resolved, but for the time being it would be helpful if the documentation clarified the current situation with Unions and type parameters.

(The sentence that comes to my mind for the documentation at http://docs.julialang.org/en/release-0.4/manual/types/#type-unions is "The combination of Unions and type parameters is really confusing and should best be avoided." But I'm sure something more meaningful than that could be said.)

[kshyatt]

Since this is apparently pretty confusing to users (it's confusing to me too), have the docs been updated? If not, does someone want to take a crack at it?

[vtjnash]

This should be mostly fixed now, and not just as a doc change.