Add documentation for all the solvers.

docs/make.jl

@@ -19,6 +19,7 @@ makedocs(
         "matrix-vector.md",
         "solvers-preconditioners.md",
         "libhypre.md",
+        "api.md",
     ],
     draft = liveserver,
 )

docs/src/api.md

@@ -0,0 +1,26 @@
+# API
+
+## Initialization and configuration
+
+```@docs
+HYPRE.Init
+```
+
+## Solvers and preconditioners
+
+```@docs
+HYPRE.solve!
+HYPRE.solve
+```
+
+```@docs
+HYPRE.HYPRESolver
+HYPRE.BiCGSTAB
+HYPRE.BoomerAMG
+HYPRE.FlexGMRES
+HYPRE.GMRES
+HYPRE.Hybrid
+HYPRE.ILU
+HYPRE.PCG
+HYPRE.ParaSails
+```

docs/src/solvers-preconditioners.md

@@ -3,24 +3,45 @@
 HYPRE.jl wraps most of HYPREs [ParCSR solvers and
 preconditioners](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html).
 
-The synopsis for HYPRE.jl's wrappers is the same for all solvers:
+The synopsis for creating and using HYPRE.jl's solver wrappers is the same for all solvers:
+1. Set up the linear system (see [Matrix/vector representation](@ref))
+2. (Optional) Configure a preconditioner
+3. Configure a solver
+4. Use [`HYPRE.solve`](@ref) or [`HYPRE.solve!`](@ref) to solve the system
 
+Here is the corresponding pseudo-code:
 ```julia
-# Setup up linear system (see previous section)
+# 1. Setup up linear system
 A = HYPREMatrix(...)
 b = HYPREVector(...)
 
-# Create a solver
-solver = HYPRESolver(; settings...)
+# 2. Configure a preconditioner
+precond = HYPRESolver(; settings...)
 
-# Solve A x = b
+# 3. Configure a solver
+solver = HYPRESolver(; Precond = precond, settings...)
+
+# 4. Solve the system
 x = HYPRE.solve(solver, A, b)
 ```
 
+The following solvers/preconditioners are currently available:
+ - [`HYPRE.BiCGSTAB`](@ref)
+ - [`HYPRE.BoomerAMG`](@ref)
+ - [`HYPRE.FlexGMRES`](@ref)
+ - [`HYPRE.GMRES`](@ref)
+ - [`HYPRE.Hybrid`](@ref)
+ - [`HYPRE.ILU`](@ref)
+ - [`HYPRE.ParaSails`](@ref)
+ - [`HYPRE.PCG`](@ref)
+
+
+### Solver configuration
+
 Settings are passed as keyword arguments, with the names matching directly to
-`HYPRE_SolverSetXXX` calls from the HYPRE C API (see example below). Most settings are
-passed directly to HYPRE, for example `Tol = 1e-9` would be passed directly to
-`HYPRE_SolverSetTol` for the correponding solver.
+`HYPRE_SolverSet*` calls from the HYPRE C API (see example below). Most settings are passed
+directly to HYPRE, for example `Tol = 1e-9` would be passed directly to `HYPRE_SolverSetTol`
+for the correponding solver.
 
 Setting a preconditioner can be done by passing a `HYPRESolver` directly with the `Precond`
 keyword argument, without any need to also pass the corresponding `HYPRE_SolverSetup` and
@@ -30,6 +51,7 @@ settings when used as a preconditioner will have those applied automatically.
 HYPRE.jl adds finalizers to the solvers, which takes care of calling the their respective
 `HYPRE_SolverDestroy` function when the solver is garbage collected.
 
+
 #### Example: Conjugate gradient with algebraic multigrid preconditioner
 
 Here is an example of creating a `PCG` (conjugate gradient) solver with `BoomerAMG`
@@ -55,7 +77,8 @@ preconditioner. These settings are added automatically since it is passed as a
 preconditioner to the `PCG` solver.
 
 !!! not "Corresponding C code"
-    For comparison, here is the corresponding C code for setting up the solver above:
+    For comparison between the APIs, here is the corresponding C code for setting up the
+    solver above:
     ```c
     /* Setup linear system */
     HYPRE_IJMatrix A;

src/HYPRE.jl

@@ -26,6 +26,8 @@ include("Internals.jl")
 Wrapper around `HYPRE_Init`. If `finalize_atexit` is `true` a Julia exit hook is added,
 which calls `HYPRE_Finalize`. This method will also call `MPI.Init` unless MPI is already
 initialized.
+
+**Note**: This function *must* be called before using HYPRE functions.
 """
 function Init(; finalize_atexit=true)
     if !(MPI.Initialized())

src/solvers.jl

@@ -91,6 +91,14 @@ end
 # (ParCSR)BiCGSTAB #
 ####################
 
+"""
+    BiCGSTAB(; settings...)
+
+Create a `BiCGSTAB` solver. See HYPRE API reference for details and supported settings.
+
+**External links**
+ - [BiCGSTAB API reference](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html#breathe-section-title-parcsr-bicgstab-solver)
+"""
 mutable struct BiCGSTAB <: HYPRESolver
     comm::MPI.Comm
     solver::HYPRE_Solver
@@ -131,6 +139,16 @@ end
 # BoomerAMG #
 #############
 
+"""
+    BoomerAMG(; settings...)
+
+Create a `BoomerAMG` solver/preconditioner. See HYPRE API reference for details and
+supported settings.
+
+**External links**
+ - [BoomerAMG documentation](https://hypre.readthedocs.io/en/latest/solvers-boomeramg.html)
+ - [BoomerAMG API reference](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html#breathe-section-title-parcsr-boomeramg-solver-and-preconditioner)
+"""
 mutable struct BoomerAMG <: HYPRESolver
     solver::HYPRE_Solver
     function BoomerAMG(; kwargs...)
@@ -166,6 +184,14 @@ end
 # FlexGMRES #
 #############
 
+"""
+    FlexGMRES(; settings...)
+
+Create a `FlexGMRES` solver. See HYPRE API reference for details and supported settings.
+
+**External links**
+ - [FlexGMRES API reference](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html#breathe-section-title-parcsr-flexgmres-solver)
+"""
 mutable struct FlexGMRES <: HYPRESolver
     comm::MPI.Comm
     solver::HYPRE_Solver
@@ -241,6 +267,14 @@ end
 # GMRES #
 #########
 
+"""
+    GMRES(; settings...)
+
+Create a `GMRES` solver. See HYPRE API reference for details and supported settings.
+
+**External links**
+ - [GMRES API reference](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html#breathe-section-title-parcsr-gmres-solver)
+"""
 mutable struct GMRES <: HYPRESolver
     comm::MPI.Comm
     solver::HYPRE_Solver
@@ -279,6 +313,15 @@ end
 # Hybrid #
 ##########
 
+"""
+    Hybrid(; settings...)
+
+Create a `Hybrid` solver. See HYPRE API reference for details and supported settings.
+
+**External links**
+ - [Hybrid documentation](https://hypre.readthedocs.io/en/latest/solvers-hybrid.html)
+ - [Hybrid API reference](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html#breathe-section-title-parcsr-hybrid-solver)
+"""
 mutable struct Hybrid <: HYPRESolver
     solver::HYPRE_Solver
     function Hybrid(; kwargs...)
@@ -318,6 +361,16 @@ end
 # ILU #
 #######
 
+"""
+    ILU(; settings...)
+
+Create a `ILU` solver/preconditioner. See HYPRE API reference for details and supported
+settings.
+
+**External links**
+ - [ILU documentation](https://hypre.readthedocs.io/en/latest/solvers-hypre-ilu.html)
+ - [ILU API reference](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html#breathe-section-title-parcsr-ilu-solver)
+"""
 mutable struct ILU <: HYPRESolver
     solver::HYPRE_Solver
     function ILU(; kwargs...)
@@ -353,6 +406,16 @@ end
 # (ParCSR)ParaSails #
 #####################
 
+"""
+    ParaSails(comm=MPI.COMM_WORLD; settings...)
+
+Create a `ParaSails` preconditioner. See HYPRE API reference for details and supported
+settings.
+
+**External links**
+ - [ParaSails documentation](https://hypre.readthedocs.io/en/latest/solvers-parasails.html)
+ - [ParaSails API reference](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html#breathe-section-title-parcsr-parasails-preconditioner)
+"""
 mutable struct ParaSails <: HYPRESolver
     comm::MPI.Comm
     solver::HYPRE_Solver
@@ -380,6 +443,14 @@ Internals.solve_func(::ParaSails) = HYPRE_ParCSRParaSailsSolve
 # (ParCSR)PCG #
 ###############
 
+"""
+    PCG(; settings...)
+
+Create a `PCG` solver. See HYPRE API reference for details and supported settings.
+
+**External links**
+ - [PCG API reference](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html#breathe-section-title-parcsr-pcg-solver)
+"""
 mutable struct PCG <: HYPRESolver
     comm::MPI.Comm
     solver::HYPRE_Solver