Document recursive (c)transpose

[schmrlng]

Notes:

• ctranspose{T<:AbstractVector}(::Type{T}) is defined indirectly through the methods here: https://github.com/JuliaLang/julia/blob/master/base/operators.jl#L261
• As far as I can tell, transpose{T<:AbstractVector}(::Type{T}) = Matrix{eltype(T)} is the correct definition for all subtypes of AbstractVector.
• According to a brief search, the jury's out on whether the julia community prefers American (behavior) or British (behaviour) spellings, so I went with the good old USofA.

[simonster]

This seems like an improvement, so I support merging, but what if you have a matrix of eltype Union{Vector{T},S}?

[JeffBezanson]

...depends on #4774. I didn't realize transpose is defined on types. That's weird.

[simonster]

@JeffBezanson I don't think it really was, until this PR. It's just that there's a fallback transpose(x) = x

[simonster]

I suppose one issue with defining it on types is that you'd have fill(Vector{Int}, 2, 2)' == fill(Matrix{Int}, 2, 2). Not sure why you'd have a matrix of types, but it could happen...

[schmrlng]

@simonster I suppose in that case a solution would be to extend the definition of transpose on types to operate through unions, but I agree that transpose on types is a bit weird to extend more generally beyond this hack. The behavior in this PR could be achieved by defining a special transposetype function with

transposetype(x) = x
transposetype{T<:AbstractVector}(::Type{T}) = Matrix{eltype(T)}
transposetype(x::Union) = Union{(transposetype(t) for t in x.types)...} 

to be used in the allocations of B in transpose and ctranspose.

As for whether or not we want fill(Vector{Int}, 2, 2)' == fill(Matrix{Int}, 2, 2), to me this feels a lot like the original issue in #15512 of whether transpose means more-or-less permutedims or something mathematical like deeptranspose (or some other option from #4774).

[bjarthur]

documentation is always good for an RC. i'd suggest merging this before 0.5-RC1

[tkelman]

needs a rebase, and some related behavior was changed with the now deprecated fallback

[schmrlng]

I haven't looked at this in ages but I've seen some rumblings recently about a return_type function? Something like that would probably be the right way to implement the element type issue with recursive transpose. This is a bit reminiscent of inference in #16622 although the problem here (#15512) is much more of a special case (i.e., the hacky solution transpose{T<:AbstractVector}(::Type{T}) = Matrix{eltype(T)} seemed sufficient, at least in terms of functionality).

Alternatively, we can let #15512 stand and I can make a PR with only the doc changes.

[bjarthur]

a PR with just the docs would be great. transpose being recursive was a surprise to me, and one shouldn't have to go digging in the issue tracker to learn it's supposed to be that way.

[schmrlng]

Okay, this is just the doc fix portion of the original PR. I guess fixing #15512 can wait until #4774 is figured out.

[Keno]

The rebased version of this (#24891) was declared obsolete, so I assume this is as well.