More docs on using the C API directly.

docs/src/libhypre.md

@@ -1,13 +1,21 @@
-# LibHYPRE
+# LibHYPRE C API
 
-The submodule `HYPRE.LibHYPRE` contains auto-generated[^1] bindings to the HYPRE library.
+The submodule `HYPRE.LibHYPRE` contains auto-generated bindings to the HYPRE library and
-The module exports all `HYPRE_*` symbols. Function names and arguments are identical to the
+give access to the HYPRE C API directly[^1]. The module exports all `HYPRE_*` symbols.
-C-library -- refer to the [HYPRE manual](https://hypre.readthedocs.io/) for details.
+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.
+The example program
-This is useful when you need some functionality from the library which can't be accessed
+[`examples/ex5.jl`](https://github.com/fredrikekre/HYPRE.jl/blob/master/examples/ex5.jl) is
-through the Julia interface. Many functions require passing a reference to a matrix/vector
+an (almost) line-to-line translation of the corresponding example program
-or a solver. These can be obtained as follows:
+[`examples/ex5.c`](https://github.com/hypre-space/hypre/blob/ac9d7d0d7b43cd3d0c7f24ec5d64b58fbf900097/src/examples/ex5.c)
+written in C, and showcases how HYPRE.jl can be used to interact with the HYPRE library
+directly.
+
+Functions from the `LibHYPRE` submodule can be used together with the high level interface.
+This is useful when you need some functionality from the library which isn't exposed in the
+high level 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                     |
 |:---------------------|:-------------------------------------|

examples/ex5.jl

@@ -1,5 +1,9 @@
 # Example translated from C to Julia based on this original source (MIT license):
 # https://github.com/hypre-space/hypre/blob/ac9d7d0d7b43cd3d0c7f24ec5d64b58fbf900097/src/examples/ex5.c
+#
+# Note that this is more or less a line-by-line translation (Julia and C are surprisingly
+# similar!), and therefore the code here is not very "Julian" in the style. Nevertheless, it
+# showcases how HYPRE.jl can be used to interact with the C API directly.
 
 # Example 5
 #