From c8f4ed68633ed005593491b85442770ee9eb4574 Mon Sep 17 00:00:00 2001
From: Anton Khirnov <anton@khirnov.net>
Date: Fri, 30 Jun 2017 09:46:25 +0200
Subject: Update documentation.

---
 brill_data.h | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/brill_data.h b/brill_data.h
index 9047414..05a3511 100644
--- a/brill_data.h
+++ b/brill_data.h
@@ -22,6 +22,25 @@
 #include <stddef.h>
 #include <stdint.h>
 
+/**
+ * API usage:
+ *
+ * First, allocate the solver context with bd_context_alloc(). All interaction
+ * with the solver is done through this context.
+ *
+ * Fill any fields in the context that are described as settable by the caller.
+ * Call bd_solve() to solve the equation determined by the option values.
+ *
+ * The Brill data is defined by the line element in cylindrical coordinates
+ * { ρ, z, φ } as
+ * dl^2 = ψ^4 (exp(-2 q(ρ, z)) (dρ^2 + dz^2) + dφ^2)
+ * The conformal factor ψ and its derivatives may be evaluated with
+ * bd_eval_psi() and the q function in the exponential can be evaluated with
+ * bd_eval_q(). The full metric can be evaluated with bd_eval_metric(). *
+ *
+ * Finally, free the solver context with bd_context_free().
+ */
+
 enum BDQFuncType {
     /**
      * q(ρ, z) = A ρ^2 exp(-ρ^2 - z^2)
@@ -95,11 +114,13 @@ typedef struct BDContext {
 
     /**
      * The number of basis functions in each direction.
+     * [0] - radial, [1] - angular
      */
     unsigned int nb_coeffs[2];
 
     /**
      * The scaling factor used in the basis functions.
+     * [0] - radial, [1] - angular
      */
     double basis_scale_factor[2];
 
@@ -107,13 +128,15 @@ typedef struct BDContext {
      * output *
      **********/
     /**
-     * The coefficients of the solution expanded in the basis.
-     * The ρ index increases along rows, z along columns.
+     * The coefficients of the solution.
+     * The adjacent elements in one row correspond to the increasing order of
+     * the first direction (radial), going between rows corresponds to the
+     * second direction (angular).
      *
      * The data is owned and managed by this library and is read-only for
      * the caller.
      */
-    double *psi_minus1_coeffs;
+    const double *psi_minus1_coeffs;
     /**
      * The number of array elements between two rows.
      */
-- 
cgit v1.2.3