improve docstrings

Author: dkarrasch

src/kronecker.jl

@@ -79,22 +79,22 @@ for k in 3:8 # is 8 sufficient?
         kron($(mapargs...), $(Symbol(:A, k)), convert_to_lmaps(As...)...)
 end
 
-"""
+@doc raw"""
     squarekron(A₁::MapOrMatrix, A₂::MapOrMatrix, A₃::MapOrMatrix, Aᵢ::MapOrMatrix...)::CompositeMap
 
 Construct a (lazy) representation of the Kronecker product `⨂ᵢ₌₁ⁿ Aᵢ` of at least 3 _square_
 Kronecker factors. In contrast to [`kron`](@ref), this function assumes that all Kronecker
 factors are square, and makes use of the following identity[^1]:
 
-```
-\\bigotimes_{i=1}^n A_i = \\prod_{i=1}^n I_1 \\otimes \\ldots \\otimes I_{i-1} \\otimes A_i \\otimes I_{i+1} \\otimes \\ldots \\otimes I_n
+```math
+\bigotimes_{i=1}^n A_i = \prod_{i=1}^n I_1 \otimes \ldots \otimes I_{i-1} \otimes A_i \otimes I_{i+1} \otimes \ldots \otimes I_n
 ```
 
-where ```I_k``` is an identity matrix of the size of ```A_k```. By associativity, the
+where ``I_k`` is an identity matrix of the size of ``A_k``. By associativity, the
 Kronecker product of the identity operators may be combined to larger identity operators
-```I_{1:i-1}``` and ```I_{i+1:n}```, which yields
+``I_{1:i-1}`` and ``I_{i+1:n}``, which yields
 
-```
+```math
 \\bigotimes_{i=1}^n A_i = \\prod_{i=1}^n I_{1:i-1} \\otimes A_i \\otimes I_{i+1:n}
 ```
 
@@ -103,9 +103,7 @@ outer `UniformScalingMap`s and the respective Kronecker factor. This representat
 expected to yield significantly faster multiplication (and reduce memory allocation)
 compared to [`kron`](@ref), but benchmarking intended use cases is highly recommended.
 
-[^1]: Fernandes, P. and Plateau, B. and Stewart, W. J. ["Efficient Descriptor-Vector
-Multiplications in Stochastic Automata Networks"](https://doi.org/10.1145/278298.278303),
-_Journal of the ACM_, 45(3), 381–414, 1998.
+[^1]: Fernandes, P. and Plateau, B. and Stewart, W. J. ["Efficient Descriptor-Vector Multiplications in Stochastic Automata Networks"](https://doi.org/10.1145/278298.278303), _Journal of the ACM_, 45(3), 381–414, 1998.
 """
 function squarekron(A::MapOrMatrix, B::MapOrMatrix, C::MapOrMatrix, Ds::MapOrMatrix...)
     maps = (A, B, C, Ds...)
@@ -326,24 +324,24 @@ kronsum(A::MapOrMatrix, B::MapOrMatrix) =
 kronsum(A::MapOrMatrix, B::MapOrMatrix, C::MapOrMatrix, Ds::MapOrMatrix...) =
     kronsum(A, kronsum(B, C, Ds...))
 
-"""
+@doc raw"""
     sumkronsum(A, B)::LinearCombination
     sumkronsum(A, B, Cs...)::LinearCombination
 
 Construct a (lazy) representation of the Kronecker sum `A⊕B` of two or more square
 objects of type `LinearMap` or `AbstractMatrix`. This function makes use of the following
 representation of Kronecker sums[^1]:
 
-```
-\\bigoplus_{i=1}^n A_i = \\sum_{i=1}^n I_1 \\otimes \\ldots \\otimes I_{i-1} \\otimes A_i \\otimes I_{i+1} \\otimes \\ldots \\otimes I_n
+```math
+\bigoplus_{i=1}^n A_i = \sum_{i=1}^n I_1 \otimes \ldots \otimes I_{i-1} \otimes A_i \otimes I_{i+1} \otimes \ldots \otimes I_n
 ```
 
-where ```I_k``` is the identity operator of the size of ```A_k```. By associativity, the
+where ``I_k`` is the identity operator of the size of ``A_k``. By associativity, the
 Kronecker product of the identity operators may be combined to larger identity operators
-```I_{1:i-1}``` and ```I_{i+1:n}```, which yields
+``I_{1:i-1}`` and ``I_{i+1:n}``, which yields
 
-```
-\\bigoplus_{i=1}^n A_i = \\sum_{i=1}^n I_{1:i-1} \\otimes A_i \\otimes I_{i+1:n}
+```math
+\bigoplus_{i=1}^n A_i = \sum_{i=1}^n I_{1:i-1} \otimes A_i \otimes I_{i+1:n},
 ```
 
 i.e., a `LinearCombination` where each summand is a Kronecker product consisting of three
@@ -369,9 +367,7 @@ julia> Matrix(Δ₁) == Matrix(Δ₂) == Matrix(Δ₃)
 true
 ```
 
-[^1]: Fernandes, P. and Plateau, B. and Stewart, W. J. ["Efficient Descriptor-Vector
-Multiplications in Stochastic Automata Networks"](https://doi.org/10.1145/278298.278303),
-_Journal of the ACM_, 45(3), 381–414, 1998.
+[^1]: Fernandes, P. and Plateau, B. and Stewart, W. J. ["Efficient Descriptor-Vector Multiplications in Stochastic Automata Networks"](https://doi.org/10.1145/278298.278303), _Journal of the ACM_, 45(3), 381–414, 1998.
 """
 function sumkronsum(A::MapOrMatrix, B::MapOrMatrix)
     LinearAlgebra.checksquare(A, B)