From ebd58089ed75d16b75d78d87f1e62fe0d1e5fcdb Mon Sep 17 00:00:00 2001
From: Fredrik Ekre <ekrefredrik@gmail.com>
Date: Mon, 25 Jul 2022 21:18:42 +0200
Subject: [PATCH] Add documentation for HYPRE.LibHYPRE submodule.

---
 docs/make.jl         |  1 +
 docs/src/index.md    | 12 ++----------
 docs/src/libhypre.md | 23 +++++++++++++++++++++++
 3 files changed, 26 insertions(+), 10 deletions(-)
 create mode 100644 docs/src/libhypre.md

diff --git a/docs/make.jl b/docs/make.jl
index 08ee1d3..a11fdd2 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -16,6 +16,7 @@ makedocs(
     modules = [HYPRE],
     pages = Any[
         "Home" => "index.md",
+        "libhypre.md",
     ],
     draft = liveserver,
 )
diff --git a/docs/src/index.md b/docs/src/index.md
index f05b00d..bf24992 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -1,12 +1,4 @@
 # HYPRE.jl
 
-Documentation for HYPRE.jl
-
-```@docs
-HYPRE.solve!
-HYPRE.solve
-```
-
-```@docs
-HYPRE.HYPRESolver
-```
+HYPRE.jl is a Julia wrapper for the [HYPRE library](https://github.com/hypre-space/hypre),
+which provide parallel solvers for sparse linear systems.
diff --git a/docs/src/libhypre.md b/docs/src/libhypre.md
new file mode 100644
index 0000000..092625f
--- /dev/null
+++ b/docs/src/libhypre.md
@@ -0,0 +1,23 @@
+# LibHYPRE
+
+The submodule `HYPRE.LibHYPRE` contains auto-generated[^1] bindings to the HYPRE library.
+The module exports all `HYPRE_*` symbols. Function names and arguments are identical to the
+C-library -- refer to the [HYPRE manual](https://hypre.readthedocs.io/) for details.
+
+Functions from the `LibHYPRE` submodule can be used together with the "Julian" interface.
+This is useful when you need some functionality from the library which can't be accessed
+through the Julia interface. Many functions require passing a reference to a matrix/vector
+or a solver. These can be obtained as follows:
+
+| C type signature     | Argument to pass                        |
+|:---------------------|:----------------------------------------|
+| `HYPRE_IJMatrix`     | `A.IJMatrix` where `A::HYPREMatrix`     |
+| `HYPRE_IJVector`     | `b.IJVector` where `b::HYPREVector`     |
+| `HYPRE_ParCSRMatrix` | `A.ParCSRMatrix` where `A::HYPREMatrix` |
+| `HYPRE_ParVector`    | `b.ParVector` where `b::HYPREVector`    |
+| `HYPRE_Solver`       | `s.Solver` where `s::HYPRESolver`       |
+
+[^1]: Bindings are generated using
+      [Clang.jl](https://github.com/JuliaInterop/Clang.jl), see
+      [gen/generator.jl]
+      (https://github.com/fredrikekre/HYPRE.jl/blob/master/gen/generator.jl).