Update docstring of bkfact and related getindex. (#25185)

* Update docstring of bkfact and related getindex.

To be compatible with 88e7fbc.

Also include the actual decomposition format. Fix missing permutation
matrix in the `getindex` docstring.

* Removed transpose from second permutation matrix.

Also mention properties of permutation matrix in docstring.

Author: tpapp

base/linalg/bunchkaufman.jl

@@ -41,16 +41,15 @@ function bkfact!(A::StridedMatrix{<:BlasFloat}, rook::Bool = false)
 end
 
 """
-    bkfact(A, uplo::Symbol=:U, symmetric::Bool=issymmetric(A), rook::Bool=false) -> BunchKaufman
+    bkfact(A, rook::Bool=false) -> BunchKaufman
 
-Compute the Bunch-Kaufman [^Bunch1977] factorization of a symmetric or Hermitian
-matrix `A` and return a `BunchKaufman` object.
-`uplo` indicates which triangle of matrix `A` to reference.
-If `symmetric` is `true`, `A` is assumed to be symmetric. If `symmetric` is `false`,
-`A` is assumed to be Hermitian. If `rook` is `true`, rook pivoting is used. If
-`rook` is false, rook pivoting is not used.
-The following functions are available for
-`BunchKaufman` objects: [`size`](@ref), `\\`, [`inv`](@ref), [`issymmetric`](@ref), [`ishermitian`](@ref).
+Compute the Bunch-Kaufman [^Bunch1977] factorization of a symmetric or Hermitian matrix `A` as ``PUDU'P`` or ``PLDL'P``, depending on which triangle is stored in `A`, and return a `BunchKaufman` object.
+
+If `rook` is `true`, rook pivoting is used. If `rook` is false, rook pivoting is not used.
+
+The following functions are available for `BunchKaufman` objects: [`size`](@ref), `\\`, [`inv`](@ref), [`issymmetric`](@ref), [`ishermitian`](@ref), [`getindex`](@ref).
+
+Note that  `P` is symmetric, so ``P=P⁻¹=P'``.
 
 [^Bunch1977]: J R Bunch and L Kaufman, Some stable methods for calculating inertia and solving symmetric linear systems, Mathematics of Computation 31:137 (1977), 163-179. [url](http://www.ams.org/journals/mcom/1977-31-137/S0025-5718-1977-0428694-0/).
 
@@ -118,9 +117,11 @@ end
     getproperty(B::BunchKaufman, d::Symbol)
 
 Extract the factors of the Bunch-Kaufman factorization `B`. The factorization can take the
-two forms `L*D*L'` or `U*D*U'` (or `L*D*Transpose(L)` in the complex symmetric case) where `L` is a
-`UnitLowerTriangular` matrix, `U` is a `UnitUpperTriangular`, and `D` is a block diagonal
-symmetric or Hermitian matrix with 1x1 or 2x2 blocks. The argument `d` can be
+two forms `P*L*D*L'*P` or `P*U*D*U'*P` (or `L*D*Transpose(L)` in the complex symmetric case)
+where `P` is a (symmetric) permutation matrix, `L` is a `UnitLowerTriangular` matrix, `U` is a
+`UnitUpperTriangular`, and `D` is a block diagonal symmetric or Hermitian matrix with
+1x1 or 2x2 blocks. The argument `d` can be
+
 - `:D`: the block diagonal matrix
 - `:U`: the upper triangular factor (if factorization is `U*D*U'`)
 - `:L`: the lower triangular factor (if factorization is `L*D*L'`)