Comments, doxygen

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

Doxygenise translations_dbg.h

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

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
+		qpms_bessel_t btyp, qpms_normalisation_t norm);
-void qpms_vswfset_sph_pfree(qpms_vswfset_sph_t *);//NI
+void qpms_vswfset_sph_pfree(qpms_vswfset_sph_t *);
 
 #ifdef __cplusplus
 }