Some docstring fixes

src/interface/algorithms.jl

@@ -53,6 +53,32 @@ function _show_alg(io::IO, alg::Algorithm)
     return print(io, ")")
 end
 
+@doc """
+    select_algorithm(f, A; kwargs...)
+
+Given some keyword arguments and an input `A`, decide on an algrithm to use for
+implementing the function `f` on inputs of type `A`.
+""" select_algorithm
+
+@doc """
+    copy_input(f, A)
+
+Preprocess the input `A` for a given function, such that it may be handled correctly later.
+This may include a copy whenever the implementation would destroy the original matrix,
+or a change of element type to something that is supported.
+""" copy_input
+
+@doc """
+    initialize_output(f, A, alg)
+
+Whenever possible, allocate the destination for applying a given algorithm in-place.
+If this is not possible, for example when the output size is not known a priori or immutable,
+this function may return `nothing`.
+""" initialize_output
+
+# Utility macros
+# --------------
+
 """
     @algdef AlgorithmName
 

src/interface/eig.jl

@@ -4,9 +4,9 @@
 # TODO: kwargs for sorting eigenvalues?
 
 docs_eig_note = """
-Note that `eig` and its variants do not assume additional structure on the input,
+Note that [`eig_full`](@ref) and its variants do not assume additional structure on the input,
 and therefore will always return complex eigenvalues and eigenvectors. For the real
-eigenvalue decomposition of symmetric or hermitian operators, see [`eigh`](@ref).
+eigenvalue decomposition of symmetric or hermitian operators, see [`eigh_full`](@ref).
 """
 
 # TODO: do we need "full"?
@@ -28,7 +28,7 @@ and the diagonal matrix `D` contains the associated eigenvalues.
 !!! note
     $(docs_eig_note)
 
-See also [`eig_vals(!)`](@ref eig_vals) and [`eig_trunc(!)`](@ref).
+See also [`eig_vals(!)`](@ref eig_vals) and [`eig_trunc(!)`](@ref eig_trunc).
 """
 @functiondef eig_full
 

src/interface/eigh.jl

@@ -4,9 +4,9 @@
 # TODO: kwargs for sorting eigenvalues?
 
 docs_eigh_note = """
-Note that `eigh` and its variants assume additional structure on the input,
+Note that [`eigh_full`](@ref) and its variants assume additional structure on the input,
 and therefore will retain the `eltype` of the input for the eigenvalues and eigenvectors.
-For generic eigenvalue decompositions, see [`eig`](@ref).
+For generic eigenvalue decompositions, see [`eig_full`](@ref).
 """
 
 # TODO: do we need "full"?
@@ -28,7 +28,7 @@ and the real diagonal matrix `D` contains the associated eigenvalues.
 !!! note
     $(docs_eigh_note)
 
-See also [`eigh_vals(!)`](@ref eigh_vals) and [`eigh_trunc(!)`](@ref).
+See also [`eigh_vals(!)`](@ref eigh_vals) and [`eigh_trunc(!)`](@ref eigh_trunc).
 """
 @functiondef eigh_full
 

src/interface/qr.jl

@@ -15,7 +15,7 @@ upper triangular matrix with the same size as `A`.
     possibly destroys the input matrix `A`. Always use the return value of the function
     as it may not always be possible to use the provided `QR` as output.
 
-See also [`qr_compact(!)`](@ref qr_compact) and [`qr_null(!)`](@ref).
+See also [`qr_compact(!)`](@ref qr_compact) and [`qr_null(!)`](@ref qr_null).
 """
 @functiondef qr_full
 
@@ -39,7 +39,7 @@ is upper triangular.
     The compact QR decomposition is equivalent to the full QR decomposition when `m >= n`.
     Some algorithms may require `m >= n`.
 
-See also [`qr_full(!)`](@ref qr_full) and [`qr_null(!)`](@ref).
+See also [`qr_full(!)`](@ref qr_full) and [`qr_null(!)`](@ref qr_null).
 """
 @functiondef qr_compact