From 27efabfe36b54f11cdcc7ccbc59d47fa182f0061 Mon Sep 17 00:00:00 2001
From: Anton Khirnov <anton@khirnov.net>
Date: Fri, 29 Jul 2022 20:39:27 +0200
Subject: teukolsky_data.h: update documentation

Fix the description of TD_FAMILY_TIME_ANTISYM_CUBIC to match the code.
Expand/add documentation where it was missing or insufficient.
---
 teukolsky_data.h | 26 +++++++++++++++++++++-----
 1 file changed, 21 insertions(+), 5 deletions(-)

diff --git a/teukolsky_data.h b/teukolsky_data.h
index 861613d..3569e61 100644
--- a/teukolsky_data.h
+++ b/teukolsky_data.h
@@ -45,8 +45,8 @@ enum TDFamily {
      * exponential and a quadrupole angular term.
      * Similar to that used in Abrahams&Evans PhysRevD v49,n8 (1994).
      * Conformally flat spatial metric.
-     *  r       /   x         x  3 \        /    x  2  \
-     * K  =  a | 3 ---  - 2 (---)   | * exp| - (---)    | sin(2θ)
+     *  r       /   x  3      x    \        /    x  2  \
+     * K  =  a |  (---)   -  ---    | * exp| - (---)    | sin(2θ)
      *  θ       \   L         L    /        \    L     /
      */
     TD_FAMILY_TIME_ANTISYM_CUBIC = 0,
@@ -89,7 +89,7 @@ typedef struct TDContext {
      ********************************/
 
     /**
-     * The amplitude in the I function.
+     * The amplitude parameter for the seed function.
      * Defaults to 1.
      */
     double amplitude;
@@ -127,10 +127,24 @@ typedef struct TDContext {
      */
     unsigned int nb_threads;
 
+    /**
+     * Spectral coefficients of the solution are exported here. Mainly useful
+     * for debugging, Use td_eval_*() to evaluate the solution.
+     *
+     * [0]: ψ - 1
+     * [1]: K^r_r
+     * [2]: K^φ_φ
+     */
     double *coeffs[3];
 
+    /**
+     * Set to 1 to produce the "upper branch" solution (see thesis for details).
+     */
     unsigned int solution_branch;
 
+    /**
+     * The family to use, defaults to TD_FAMILY_TIME_ANTISYM_CUBIC.
+     */
     enum TDFamily family;
 } TDContext;
 
@@ -145,7 +159,7 @@ TDContext *td_context_alloc(void);
 void td_context_free(TDContext **td);
 
 /**
- * Solve the equation for the conformal factor ψ and export the expansion coefficients in the
+ * Solve the constraint equations and export the expansion coefficients in the
  * context.
  *
  * @return >= 0 on success, a negative error code on failure
@@ -199,7 +213,9 @@ int td_eval_krt(const TDContext *td,
                 const unsigned int diff_order[2],
                 double *out);
 /**
- * Compute the values of lapse that would make the spacetime slice maximal.
+ * Compute the values of lapse for maximal slicing (i.e. that make the time
+ * derivative of K vanish).
+ *
  * Parameters are the same as for td_eval_psi().
  */
 int td_eval_lapse(const TDContext *td,
-- 
cgit v1.2.3