docs: document reexported band API

docs/make.jl

@@ -1,5 +1,12 @@
 using Documenter, FastAlmostBandedMatrices
 
+DocMeta.setdocmeta!(
+    FastAlmostBandedMatrices,
+    :DocTestSetup,
+    :(using FastAlmostBandedMatrices),
+    recursive = true,
+)
+
 makedocs(;
     sitename = "FastAlmostBandedMatrices.jl",
     authors = "Avik Pal et al.",

docs/src/api.md

@@ -42,11 +42,8 @@ to be imported separately:
   - Querying them: `bandwidth`, `bandwidths`, `colrange`, `rowrange`
   - Errors: `BandError`
 
-These names are owned and documented by
+These names are defined and documented by
 [BandedMatrices.jl](https://juliaLinearAlgebra.github.io/BandedMatrices.jl/stable/).
-FastAlmostBandedMatrices.jl only re-exports them; it does not document them and does not
-define their behaviour, so BandedMatrices.jl's own documentation is the reference for what
-each one does.
 
 Anything else from BandedMatrices.jl must be imported from BandedMatrices.jl directly.
 In particular, the following are deliberately **not** reexported:
@@ -60,11 +57,17 @@ In particular, the following are deliberately **not** reexported:
     the qualified form.
   - `symrcm`, a sparse-matrix reordering unrelated to this package.
 
-`Band` and `BandError` have no docstring upstream in BandedMatrices.jl, so they are listed
-in the `api_docs_kwargs` ignore list in `test/qa/qa.jl` rather than documented here; that
-docstring is owed by BandedMatrices.jl. Every other reexported name above carries its own
+The `Band` and `BandError` types are defined by
+[BandedMatrices.jl](https://juliaLinearAlgebra.github.io/BandedMatrices.jl/stable/), and
+FastAlmostBandedMatrices.jl documents their public bindings here because they are part of
+its documented construction workflow. Every other reexported name above carries its
 upstream docstring, reachable from the REPL help mode.
 
+```@docs
+Band
+BandError
+```
+
 The list above is kept in sync with the reexport `export` block in
 `src/FastAlmostBandedMatrices.jl` and with `REEXPORTED_API` in `test/qa/qa.jl`, and the
 Core test suite asserts that all three agree.

src/FastAlmostBandedMatrices.jl

@@ -15,10 +15,72 @@ import MatrixFactorizations
 # The BandedMatrices.jl surface that FastAlmostBandedMatrices reexports (see the second
 # `export` below), so that `using FastAlmostBandedMatrices` on its own is enough to build
 # the `bands` argument of an `AlmostBandedMatrix`, populate it, and query its band
-# structure. Everything stays owned and documented upstream in BandedMatrices.jl.
+# structure. The BandedMatrices.jl definitions remain canonical; the two docstrings below
+# document their public bindings in this module.
 using BandedMatrices: Band, BandError, BandRange, BandedMatrix, band, bandrange, bandwidth,
     bandwidths, brand, brandn, colrange, rowrange
 
+"""
+    Band(i)
+
+Index selector for the diagonal at offset `i` of a banded matrix. `Band(0)` selects the
+main diagonal, positive offsets select superdiagonals, and negative offsets select
+subdiagonals.
+
+# Fields
+
+- `i::Int`: Diagonal offset from the main diagonal.
+
+# Arguments
+
+- `i::Int`: Diagonal offset to select.
+
+# Examples
+
+```jldoctest
+julia> A = BandedMatrix(0 => 1:3, 1 => 4:5);
+
+julia> A[Band(0)] == [1, 2, 3]
+true
+
+julia> A[Band(1)] == [4, 5]
+true
+```
+"""
+Band
+
+"""
+    BandError(A, i)
+    BandError(A, (k, j))
+    BandError(A)
+
+Exception thrown when an operation accesses diagonal offset `i` outside the stored lower
+and upper bandwidths of `A`.
+
+# Fields
+
+- `A::AbstractMatrix`: Matrix whose band structure rejects the access.
+- `i::Int`: Requested diagonal offset, with positive offsets above and negative offsets
+  below the main diagonal.
+
+# Arguments
+
+- `A::AbstractMatrix`: Matrix whose band structure is being accessed.
+- `i::Int`: Requested diagonal offset.
+- `(k, j)::Tuple{Int, Int}`: Matrix coordinates from which the diagonal offset `j - k` is
+  computed.
+
+# Examples
+
+```jldoctest
+julia> A = BandedMatrix(0 => 1:3);
+
+julia> BandError(A, 1) isa BandError
+true
+```
+"""
+BandError
+
 import ArrayLayouts: MemoryLayout, sublayout, MatLdivVec, materialize!,
     triangularlayout, triangulardata, colsupport,
     rowsupport, _qr, _qr!, _factorize, muladd!, QRPackedQLayout, AdjQRPackedQLayout

test/qa/qa.jl

@@ -12,9 +12,6 @@ const REEXPORTED_API = (
 run_qa(
     FastAlmostBandedMatrices;
     reexports_allow = REEXPORTED_API,
-    # `Band` and `BandError` are reexported but carry no docstring upstream in
-    # BandedMatrices.jl, so the public-API docstring check has nothing to find for them.
-    api_docs_kwargs = (; ignore = (:Band, :BandError)),
     ei_kwargs = (;
         # Non-public names this package legitimately extends/uses from upstream:
         # ArrayLayouts MatLdivVec/sublayout/triangulardata/triangularlayout/_qr/_qr!/