Merge pull request #39 from ChrisRackauckas-Claude/docs-improvements-20251229-195327

Documentation improvements: Expand examples and enhance docstrings

Author: ChrisRackauckas

.github/dependabot.yml

@@ -5,3 +5,6 @@ updates:
     directory: "/" # Location of package manifests
     schedule:
       interval: "weekly"
+    ignore:
+      - dependency-name: "crate-ci/typos"
+        update-types: ["version-update:semver-patch", "version-update:semver-minor"]

README.md

@@ -20,13 +20,33 @@ repository.
 
 ## High Level Examples
 
+### Basic Construction and Usage
+
 ```julia
-using FastAlmostBandedMatrices
+using FastAlmostBandedMatrices, LinearAlgebra
 
-m = 2
-n = 10
+m = 2  # Fill rank
+n = 10 # Matrix dimension
 
-A1 = AlmostBandedMatrix(brand(Float64, n, n, m + 1, m), rand(Float64, m, n))
+# Create an almost banded matrix
+# brand(T, m, n, lower_bandwidth, upper_bandwidth) creates a random banded matrix
+A = AlmostBandedMatrix(brand(Float64, n, n, m + 1, m), rand(Float64, m, n))
+
+# Query matrix properties
+almostbandwidths(A)  # Returns (3, 2) - the bandwidths of the banded part
+almostbandedrank(A)  # Returns 2 - the rank of the fill part
+
+# Access the parts
+B = bandpart(A)       # Get the banded part
+F = fillpart(A)       # Get the fill part (low-rank correction)
+
+# Solve linear systems efficiently
+b = rand(n)
+x = A \ b  # Uses specialized QR factorization
+
+# QR factorization
+fact = qr(A)
+Q, R = fact.Q, fact.R
 ```
 
 ## Benchmarks

src/FastAlmostBandedMatrices.jl

@@ -81,6 +81,17 @@ end
 
 MemoryLayout(::Type{<:AlmostBandedMatrix}) = AlmostBandedLayout()
 
+"""
+    finish_part_setindex!(A::AlmostBandedMatrix)
+    finish_part_setindex!(bands, fill)
+
+Synchronize the overlapping region between the banded part and the fill part of an
+`AlmostBandedMatrix`. This function copies values from the `fill` part into the
+corresponding positions in the `bands` part where they overlap.
+
+This is automatically called during construction but may need to be called manually if
+the fill part is modified directly after construction.
+"""
 @inline function finish_part_setindex!(A)
     return finish_part_setindex!(bandpart(A), fillpart(A))
 end
@@ -97,21 +108,44 @@ end
 """
     bandpart(A::AlmostBandedMatrix)
 
-Banded Part of the AlmostBandedMatrix.
+Return the banded part of the `AlmostBandedMatrix`. This is a `BandedMatrix` that stores
+the banded structure including the overlapping region with the fill part.
+
+# Example
+```julia
+A = AlmostBandedMatrix(brand(Float64, 10, 10, 3, 2), rand(Float64, 2, 10))
+B = bandpart(A)  # Returns the BandedMatrix component
+```
 """
 @inline bandpart(A::AlmostBandedMatrix) = A.bands
 
 """
     fillpart(A::AlmostBandedMatrix)
 
-Fill Part of the AlmostBandedMatrix.
+Return the fill part of the `AlmostBandedMatrix`. This is typically a low-rank matrix that
+represents additional structure beyond the banded part. The fill part overlaps with the
+first `almostbandedrank(A)` rows of the banded part.
+
+# Example
+```julia
+A = AlmostBandedMatrix(brand(Float64, 10, 10, 3, 2), rand(Float64, 2, 10))
+F = fillpart(A)  # Returns the fill matrix (2×10)
+```
 """
 @inline fillpart(A::AlmostBandedMatrix) = A.fill
 
 """
     exclusive_bandpart(A::AlmostBandedMatrix)
 
-Banded Part of the AlmostBandedMatrix without the overlapping part.
+Return the banded part of the `AlmostBandedMatrix` excluding the rows that overlap with
+the fill part. This is a view of the banded matrix starting from row
+`almostbandedrank(A) + 1`.
+
+# Example
+```julia
+A = AlmostBandedMatrix(brand(Float64, 10, 10, 3, 2), rand(Float64, 2, 10))
+E = exclusive_bandpart(A)  # Returns a view of rows 3:10 of the banded part
+```
 """
 @inline function exclusive_bandpart(A)
     B, F = bandpart(A), fillpart(A)