From 0551004d4d90f8a64a8d44ddb3617f7e8dde1819 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marek=20Ne=C4=8Dada?= <marek@necada.org>
Date: Sun, 24 Apr 2022 22:28:23 +0300
Subject: [PATCH] Comments, doxygen

Remove old (not valid anymore) comments from vswf.h

Doxygenise translations_dbg.h
---
 qpms/translations_dbg.h | 38 +++++++++++++++++++++++++++++++-------
 qpms/vswf.h             |  4 ++--
 2 files changed, 33 insertions(+), 9 deletions(-)

diff --git a/qpms/translations_dbg.h b/qpms/translations_dbg.h
index 262c07e..e617277 100644
--- a/qpms/translations_dbg.h
+++ b/qpms/translations_dbg.h
@@ -1,17 +1,41 @@
+/*! \file translations_dbg.h
+ * \brief Auxiliary functions for debugging and testing (complementary to translations.h)
+ * 
+ * The following functions evaluate the SSWFs the same way as
+ * certain functions in translations.h, but they leave them
+ * as they are, without rearranging them into the translation
+ * operators.
+ */
 #ifndef TRANSLATIONS_DBG_H
 
-// the following functions evaluate the SSWFs the same way as
-// certain functions in translations.h, but they leave them
-// as they are, without rearranging them into the translation
-// operators.
-
 #include "translations.h"
 
+/// Evaluates scalar spherical wavefunctions at a point (spherical coordinates)
+/**
+ * \f[
+ *   \phi_l^m (kr, \theta, \varphi) = h_l(kr) \rawLeg{l}{m}(\cos \theta) e^{im\varphi} 
+ * \f]
+ *
+ * The wavefunctions are evaluated up to the degree `2 * c->lMax + 1`.
+ *
+ * Currently, THIS ALWAYS USES NON-NORMALISED LEGENDRE FUNCTIONS (TODO FIXME?).
+ */
 int qpms_trans_calculator_test_sswf(const qpms_trans_calculator *c,
-    _Complex double *dest, const csph_t kdlj, const  qpms_bessel_t J);
+    _Complex double *dest, ///< Result array, length `qpms_lMax2nelem_sc(c->lMax)`
+    const csph_t kdlj, ///< Evaluation point (incl. wavenumber)
+    const  qpms_bessel_t J);
 
+/// Evaluates scalar spherical wavefunctions at a point (cartesian coordinates)
+/**
+ * Currently, THIS ALWAYS USES NON-NORMALISED LEGENDRE FUNCTIONS (TODO FIXME?).
+ *
+ * \see qpms_trans_calculator_test_sswf()
+ */
 int qpms_trans_calculator_test_sswf_lc3p(const qpms_trans_calculator *c,
-    _Complex double *dest, const _Complex double k, const cart3_t r, const qpms_bessel_t J);
+    _Complex double *dest, ///< Result array, length `qpms_lMax2nelem_sc(c->lMax)`
+    const _Complex double k, ///< Wavenumber
+    const cart3_t r, ///< Evaluation point (excl. wavenumber)
+    const qpms_bessel_t J);
 
 
 #ifdef LATTICESUMS32
diff --git a/qpms/vswf.h b/qpms/vswf.h
index 86e68aa..140d911 100644
--- a/qpms/vswf.h
+++ b/qpms/vswf.h
@@ -247,8 +247,8 @@ csphvec_t qpms_eval_vswf_csph(csph_t where,
 		qpms_l_t lMax, qpms_bessel_t btyp, qpms_normalisation_t norm);
 
 qpms_vswfset_sph_t *qpms_vswfset_make(qpms_l_t lMax, sph_t kdlj,
-		qpms_bessel_t btyp, qpms_normalisation_t norm);//NI
-void qpms_vswfset_sph_pfree(qpms_vswfset_sph_t *);//NI
+		qpms_bessel_t btyp, qpms_normalisation_t norm);
+void qpms_vswfset_sph_pfree(qpms_vswfset_sph_t *);
 
 #ifdef __cplusplus
 }