docstring fixes

Author: lkdvos

src/implementations/truncation.jl

@@ -119,14 +119,6 @@ _ind_intersect(A, B) = intersect(A, B)
 
 # Truncation error
 # ----------------
-@doc """
-    truncation_error(values, ind)
-    truncation_error!(values, ind)
-
-Determine the truncation error of selecting `ind` out of the `values`.
-This is defined as the 2-norm of the discarded values.
-""" truncation_error, truncation_error!
-
 truncation_error(values::AbstractVector, ind) = truncation_error!(copy(values), ind)
 # destroys input in order to maximize accuracy:
 # sqrt(norm(values)^2 - norm(values[ind])^2) might suffer from floating point error

src/interface/eig.jl

@@ -45,6 +45,26 @@ selected according to a truncation strategy.
 The function also returns `ϵ`, the truncation error defined as the 2-norm of the 
 discarded eigenvalues.
 
+## Keyword arguments
+The behavior of this function is controlled by the following keyword arguments:
+
+- `trunc`: Specifies the truncation strategy. This can be:
+  - A `NamedTuple` with fields `atol`, `rtol`, and/or `maxrank`, which will be converted to
+    a [`TruncationStrategy`](@ref). For details on available truncation strategies, see
+    [Truncations](@ref).
+  - A `TruncationStrategy` object directly (e.g., `truncrank(10)`, `trunctol(atol=1e-6)`, or
+    combinations using `&`).
+  - `nothing` (default), which keeps all eigenvalues.
+
+- Other keyword arguments are passed to the algorithm selection procedure. If no explicit
+  `alg` is provided, these keywords are used to select and configure the algorithm through
+  [`MatrixAlgebraKit.select_algorithm`](@ref). The remaining keywords after algorithm
+  selection are passed to the algorithm constructor. See [`MatrixAlgebraKit.default_algorithm`](@ref)
+  for the default algorithm selection behavior.
+
+When `alg` is a [`TruncatedAlgorithm`](@ref), the `trunc` keyword cannot be specified as the
+truncation strategy is already embedded in the algorithm.
+
 !!! note
     The bang method `eig_trunc!` optionally accepts the output structure and
     possibly destroys the input matrix `A`. Always use the return value of the function

src/interface/eigh.jl

@@ -37,16 +37,19 @@ See also [`eigh_vals(!)`](@ref eigh_vals) and [`eigh_trunc(!)`](@ref eigh_trunc)
 @functiondef eigh_full
 
 """
-    eigh_trunc(A; [trunc], kwargs...) -> D, V
-    eigh_trunc(A, alg::AbstractAlgorithm) -> D, V
-    eigh_trunc!(A, [DV]; [trunc], kwargs...) -> D, V
-    eigh_trunc!(A, [DV], alg::AbstractAlgorithm) -> D, V
+    eigh_trunc(A; [trunc], kwargs...) -> D, V, ϵ
+    eigh_trunc(A, alg::AbstractAlgorithm) -> D, V, ϵ
+    eigh_trunc!(A, [DV]; [trunc], kwargs...) -> D, V, ϵ
+    eigh_trunc!(A, [DV], alg::AbstractAlgorithm) -> D, V, ϵ
 
 Compute a partial or truncated eigenvalue decomposition of the symmetric or hermitian matrix
 `A`, such that `A * V ≈ V * D`, where the isometric matrix `V` contains a subset of the
 orthogonal eigenvectors and the real diagonal matrix `D` contains the associated eigenvalues,
 selected according to a truncation strategy.
 
+The function also returns `ϵ`, the truncation error defined as the 2-norm of the discarded
+eigenvalues.
+
 ## Keyword arguments
 The behavior of this function is controlled by the following keyword arguments:
 

src/interface/svd.jl

@@ -54,7 +54,27 @@ square diagonal matrix of size `(k, k)`, with `k` is set by the truncation strat
 
 The function also returns `ϵ`, the truncation error defined as the 2-norm of the 
 discarded singular values.
-        
+
+## Keyword arguments
+The behavior of this function is controlled by the following keyword arguments:
+
+- `trunc`: Specifies the truncation strategy. This can be:
+  - A `NamedTuple` with fields `atol`, `rtol`, and/or `maxrank`, which will be converted to
+    a [`TruncationStrategy`](@ref). For details on available truncation strategies, see
+    [Truncations](@ref).
+  - A `TruncationStrategy` object directly (e.g., `truncrank(10)`, `trunctol(atol=1e-6)`, or
+    combinations using `&`).
+  - `nothing` (default), which keeps all singular values.
+
+- Other keyword arguments are passed to the algorithm selection procedure. If no explicit
+  `alg` is provided, these keywords are used to select and configure the algorithm through
+  [`MatrixAlgebraKit.select_algorithm`](@ref). The remaining keywords after algorithm
+  selection are passed to the algorithm constructor. See [`MatrixAlgebraKit.default_algorithm`](@ref)
+  for the default algorithm selection behavior.
+
+When `alg` is a [`TruncatedAlgorithm`](@ref), the `trunc` keyword cannot be specified as the
+truncation strategy is already embedded in the algorithm.
+
 !!! note
     The bang method `svd_trunc!` optionally accepts the output structure and
     possibly destroys the input matrix `A`. Always use the return value of the function

src/interface/truncation.jl

@@ -181,3 +181,8 @@ Base.:&(::NoTruncation, ::NoTruncation) = notrunc()
 # disambiguate
 Base.:&(::NoTruncation, trunc::TruncationIntersection) = trunc
 Base.:&(trunc::TruncationIntersection, ::NoTruncation) = trunc
+
+@doc """
+    truncation_error(values, ind)
+Compute the truncation error as the 2-norm of the values that are not kept by `ind`.
+""" truncation_error, truncation_error!