Update all source code comments to Doxygen format

64 files changed, 1132 insertions, 1227 deletions

diff --git a/libcrystfel/src/asdf.c b/libcrystfel/src/asdf.c
index 9dc5f9d5..72b110d7 100644
--- a/libcrystfel/src/asdf.c
+++ b/libcrystfel/src/asdf.c
@@ -51,6 +51,9 @@
 #include "cell-utils.h"
 #include "asdf.h"
 
+/**
+ * \file asdf.h
+ */
 
 struct fftw_vars {
 	int N;
@@ -1162,6 +1165,9 @@ int run_asdf(struct image *image, void *ipriv)
 }
 
 
+/**
+ * Prepare the ASDF indexing algorithm
+ */
 void *asdf_prepare(IndexingMethod *indm, UnitCell *cell)
 {
 	struct asdf_private *dp;
diff --git a/libcrystfel/src/asdf.h b/libcrystfel/src/asdf.h
index 896f65a8..59dc6a86 100644
--- a/libcrystfel/src/asdf.h
+++ b/libcrystfel/src/asdf.h
@@ -41,6 +41,11 @@
 extern "C" {
 #endif
 
+/**
+ * \file asdf.h
+ * The ASDF indexing algorithm.
+ */
+
 #ifdef HAVE_FFTW
 
 extern int run_asdf(struct image *image, void *ipriv);
diff --git a/libcrystfel/src/cell-utils.c b/libcrystfel/src/cell-utils.c
index c0159c13..1609d816 100644
--- a/libcrystfel/src/cell-utils.c
+++ b/libcrystfel/src/cell-utils.c
@@ -47,15 +47,7 @@
 
 
 /**
- * SECTION:cell-utils
- * @short_description: Unit cell utilities
- * @title: Unit cell utilities
- * @section_id:
- * @see_also:
- * @include: "cell-utils.h"
- * @Image:
- *
- * There are some utility functions associated with the core %UnitCell.
+ * \file cell-utils.h
  **/
 
 
@@ -64,13 +56,12 @@
 
 
 /**
- * cell_rotate:
- * @in: A %UnitCell to rotate
- * @quat: A %quaternion
+ * \param in: A UnitCell to rotate
+ * \param quat: A quaternion
  *
- * Rotate a %UnitCell using a %quaternion.
+ * Rotate a UnitCell using a quaternion.
  *
- * Returns: a newly allocated rotated copy of @in.
+ * \returns a newly allocated rotated copy of \p in.
  *
  */
 UnitCell *cell_rotate(UnitCell *in, struct quaternion quat)
@@ -386,8 +377,8 @@ static RationalMatrix *create_rtnl_mtx(signed int a1, signed int a2,
 }
 
 
-/* Given a centered cell @in, return the integer transformation matrix which
- * turns a primitive cell into @in. Set new_centering and new_latt to the
+/* Given a centered cell "in", return the integer transformation matrix which
+ * turns a primitive cell into "in". Set new_centering and new_latt to the
  * centering and lattice type of the primitive cell (usually aP, sometimes rR,
  * rarely mP).  Store the inverse matrix at pCi */
 static IntegerMatrix *centering_transformation(UnitCell *in,
@@ -528,19 +519,18 @@ static IntegerMatrix *centering_transformation(UnitCell *in,
 
 
 /**
- * uncenter_cell:
- * @in: A %UnitCell
- * @C: Location at which to store the centering transformation
- * @Ci: Location at which to store the inverse centering transformation
+ * \param in: A %UnitCell
+ * \param pC: Location at which to store the centering transformation
+ * \param pCi: Location at which to store the inverse centering transformation
  *
  * Turns any cell into a primitive one, e.g. for comparison purposes.
  *
- * The transformation which was used is stored at @Ci. The centering
+ * The transformation which was used is stored at \p Ci. The centering
  * transformation, which is the transformation you should apply if you want to
- * get back the original cell, will be stored at @C.  Either or both of these
+ * get back the original cell, will be stored at \p C.  Either or both of these
  * can be NULL if you don't need that information.
  *
- * Returns: a primitive version of @in.
+ * \returns a primitive version of \p in.
  *
  */
 UnitCell *uncenter_cell(UnitCell *in, IntegerMatrix **pC, RationalMatrix **pCi)
@@ -1126,12 +1116,11 @@ static void determine_lattice(UnitCell *cell,
 
 
 /**
- * load_cell_from_pdb:
- * @filename: The filename from which to load the cell
+ * \param filename: The filename from which to load the cell
  *
  * Loads a unit cell from the CRYST1 line of a PDB file.
  *
- * Returns: a newly allocated %UnitCell.
+ * \returns a newly allocated %UnitCell.
  *
  */
 UnitCell *load_cell_from_pdb(const char *filename)
@@ -1266,11 +1255,10 @@ static int get_angle_rad(char **bits, int nbits, double *pl)
 }
 
 /**
- * write_cell:
- * @cell: a %UnitCell
- * @fh: a file handle
+ * \param cell: a %UnitCell
+ * \param fh: a file handle
  *
- * Writes @cell to @fh, in CrystFEL unit cell file format
+ * Writes \p cell to \p fh, in CrystFEL unit cell file format
  *
  */
 void write_cell(UnitCell *cell, FILE *fh)
@@ -1302,12 +1290,11 @@ void write_cell(UnitCell *cell, FILE *fh)
 
 
 /**
- * load_cell_from_file:
- * @filename: The filename from which to load the cell
+ * \param filename: The filename from which to load the cell
  *
  * Loads a unit cell from a file of any type (PDB or CrystFEL format)
  *
- * Returns: a newly allocated %UnitCell.
+ * \returns a newly allocated %UnitCell.
  *
  */
 UnitCell *load_cell_from_file(const char *filename)
@@ -1471,15 +1458,14 @@ void cell_fudge_gslcblas()
 
 
 /**
- * rotate_cell:
- * @in: A %UnitCell to rotate
- * @omega: Euler angle about +z
- * @phi: Euler angle about +x
- * @rot: Euler angle about new +z
+ * \param in: A %UnitCell to rotate
+ * \param omega: Euler angle about +z
+ * \param phi: Euler angle about +x
+ * \param rot: Euler angle about new +z
  *
  * Rotate a %UnitCell using Euler angles
  *
- * Returns: a newly allocated rotated copy of @in.
+ * \returns a newly allocated rotated copy of \p in.
  *
  */
 UnitCell *rotate_cell(UnitCell *in, double omega, double phi, double rot)
@@ -1563,14 +1549,13 @@ int cell_is_sensible(UnitCell *cell)
 
 
 /**
- * validate_cell:
- * @cell: A %UnitCell to validate
+ * \param cell: A %UnitCell to validate
  *
- * Perform some checks for crystallographic validity @cell, such as that the
+ * Perform some checks for crystallographic validity \p cell, such as that the
  * lattice is a conventional Bravais lattice.
  * Warnings are printied if any of the checks are failed.
  *
- * Returns: zero if the cell is fine, 1 if it is unconventional but otherwise
+ * \returns zero if the cell is fine, 1 if it is unconventional but otherwise
  *  OK (e.g. left-handed or not a Bravais lattice), and 2 if there is a serious
  *  problem such as the parameters being physically impossible.
  *
@@ -1615,13 +1600,12 @@ int validate_cell(UnitCell *cell)
 
 
 /**
- * forbidden_reflection:
- * @cell: A %UnitCell
- * @h: h index to check
- * @k: k index to check
- * @l: l index to check
+ * \param cell: A %UnitCell
+ * \param h: h index to check
+ * \param k: k index to check
+ * \param l: l index to check
  *
- * Returns: true if this reflection is forbidden.
+ * \returns true if this reflection is forbidden.
  *
  */
 int forbidden_reflection(UnitCell *cell,
@@ -1652,7 +1636,9 @@ int forbidden_reflection(UnitCell *cell,
 }
 
 
-/* Returns cell volume in A^3 */
+/**
+ * \returns cell volume in A^3
+ */
 double cell_get_volume(UnitCell *cell)
 {
 	double asx, asy, asz;
@@ -1681,21 +1667,20 @@ double cell_get_volume(UnitCell *cell)
 
 
 /**
- * compare_cell_parameters:
- * @a: A %UnitCell
- * @b: Another %UnitCell
- * @ltl: Maximum allowable fractional difference in axis lengths
- * @atl: Maximum allowable difference in reciprocal angles (in radians)
+ * \param cell1: A UnitCell
+ * \param cell2: Another UnitCell
+ * \param ltl: Maximum allowable fractional difference in axis lengths
+ * \param atl: Maximum allowable difference in reciprocal angles (in radians)
  *
  * Compare the two unit cells.  If the real space parameters match to within
- * fractional difference @ltl, and the inter-axial angles match within @atl,
+ * fractional difference \p ltl, and the inter-axial angles match within \p atl,
  * and the centering matches, this function returns 1.  Otherwise 0.
  *
  * This function considers the cell parameters and centering, but ignores the
  * orientation of the cell.  If you want to compare the orientation as well,
  * use compare_cell_parameters_and_orientation() instead.
  *
- * Returns: non-zero if the cells match.
+ * \returns non-zero if the cells match.
  *
  */
 int compare_cell_parameters(UnitCell *cell1, UnitCell *cell2,
@@ -1732,24 +1717,23 @@ static double moduli_check(double ax, double ay, double az,
 
 
 /**
- * compare_cell_parameters_and_orientation:
- * @a: A %UnitCell
- * @b: Another %UnitCell
- * @ltl: Maximum allowable fractional difference in reciprocal axis lengths
- * @atl: Maximum allowable difference in reciprocal angles (in radians)
+ * \param cell1: A UnitCell
+ * \param cell2: Another UnitCell
+ * \param ltl: Maximum allowable fractional difference in reciprocal axis lengths
+ * \param atl: Maximum allowable difference in reciprocal angles (in radians)
  *
  * Compare the two unit cells.  If the axes match in length (to within
- * fractional difference @ltl) and the axes are aligned to within @atl radians,
+ * fractional difference \p ltl) and the axes are aligned to within \p atl radians,
  * this function returns non-zero.
  *
  * This function compares the orientation of the cell as well as the parameters.
  * If you just want to see if the parameters are the same, use
  * compare_cell_parameters() instead.
  *
- * The cells @a and @b must have the same centering.  Otherwise, this function
+ * The cells \p a and \p b must have the same centering.  Otherwise, this function
  * always returns zero.
  *
- * Returns: non-zero if the cells match.
+ * \returns non-zero if the cells match.
  *
  */
 int compare_cell_parameters_and_orientation(UnitCell *cell1, UnitCell *cell2,
@@ -1781,26 +1765,25 @@ int compare_cell_parameters_and_orientation(UnitCell *cell1, UnitCell *cell2,
 
 
 /**
- * compare_reindexed_cell_parameters_and_orientation:
- * @a: A %UnitCell
- * @b: Another %UnitCell
- * @ltl: Maximum allowable fractional difference in reciprocal axis lengths
- * @atl: Maximum allowable difference in reciprocal angles (in radians)
- * @pmb: Place to store pointer to matrix
+ * \param a: A UnitCell
+ * \param b: Another UnitCell
+ * \param ltl: Maximum allowable fractional difference in reciprocal axis lengths
+ * \param atl: Maximum allowable difference in reciprocal angles (in radians)
+ * \param pmb: Place to store pointer to matrix
  *
  * Compare the two unit cells.  If, using any permutation of the axes, the
- * axes can be made to match in length (to within fractional difference @ltl)
- * and the axes aligned to within @atl radians, this function returns non-zero
- * and stores the transformation to map @b onto @a.
+ * axes can be made to match in length (to within fractional difference \p ltl)
+ * and the axes aligned to within \p atl radians, this function returns non-zero
+ * and stores the transformation to map \p b onto \p a.
  *
  * Note that the orientations of the cells must match, not just the parameters.
  * The comparison is done after reindexing using
  * compare_cell_parameters_and_orientation().
  *
- * The cells @a and @b must have the same centering.  Otherwise, this function
+ * The cells \p a and \p b must have the same centering.  Otherwise, this function
  * always returns zero.
  *
- * Returns: non-zero if the cells match.
+ * \returns non-zero if the cells match.
  *
  */
 int compare_reindexed_cell_parameters_and_orientation(UnitCell *a, UnitCell *b,
@@ -1973,17 +1956,17 @@ static double g6_distance(double a1, double b1, double c1,
 
 
 /**
- * compare_reindexed_cell_parameters:
- * @cell_in: A %UnitCell
- * @reference_in: Another %UnitCell
- * @ltl: Maximum allowable fractional difference in direct-space axis lengths
- * @atl: Maximum allowable difference in direct-space angles (in radians)
- * @pmb: Place to store pointer to matrix
+ * \param cell_in: A UnitCell
+ * \param reference_in: Another UnitCell
+ * \param ltl: Maximum allowable fractional difference in direct-space axis lengths
+ * \param atl: Maximum allowable difference in direct-space angles (in radians)
+ * \param csl: Non-zero to look for coincidence site lattice relationships
+ * \param pmb: Place to store pointer to matrix
  *
- * Compare the @cell_in with @reference_in.  If @cell is a derivative lattice
- * of @reference, within fractional axis length difference @ltl and absolute angle
- * difference @atl (in radians), this function returns non-zero and stores the
- * transformation which needs to be applied to @cell_in at @pmb.
+ * Compare the \p cell_in with \p reference_in.  If \p cell is a derivative lattice
+ * of \p reference, within fractional axis length difference \p ltl and absolute angle
+ * difference \p atl (in radians), this function returns non-zero and stores the
+ * transformation which needs to be applied to \p cell_in at \p pmb.
  *
  * Note that the tolerances will be applied to the primitive unit cell.  If
  * the reference cell is centered, a primitive unit cell will first be calculated.
@@ -1995,7 +1978,12 @@ static double g6_distance(double a1, double b1, double c1,
  * Only the cell parameters will be compared.  The relative orientations are
  * irrelevant.
  *
- * Returns: non-zero if the cells match, zero for no match or error.
+ * If \p csl is zero, the lattices must be derivatives of one another.  If
+ * non-zero, a coincidence site lattice relationship will be searched for,
+ * meaning that the lattice points of the transformed version of \p cell_in
+ * might not coincide with lattice points of \p reference_in.
+ *
+ * \returns non-zero if the cells match, zero for no match or error.
  *
  */
 int compare_reindexed_cell_parameters(UnitCell *cell_in, UnitCell *reference_in,
diff --git a/libcrystfel/src/cell-utils.h b/libcrystfel/src/cell-utils.h
index 79c98e61..be878c10 100644
--- a/libcrystfel/src/cell-utils.h
+++ b/libcrystfel/src/cell-utils.h
@@ -43,6 +43,12 @@
 extern "C" {
 #endif
 
+/**
+ * \file cell-utils.h
+ * Unit cell utility functions.
+ **/
+
+
 extern double resolution(UnitCell *cell,
                          signed int h, signed int k, signed int l);
 
diff --git a/libcrystfel/src/cell.c b/libcrystfel/src/cell.c
index ce9d37bb..250da801 100644
--- a/libcrystfel/src/cell.c
+++ b/libcrystfel/src/cell.c
@@ -50,15 +50,7 @@
 
 
 /**
- * SECTION:unitcell
- * @short_description: Unit cell
- * @title: UnitCell
- * @section_id:
- * @see_also:
- * @include: "cell.h"
- * @Image:
- *
- * This structure represents a unit cell.
+ * \file cell.h
  */
 
 
@@ -116,11 +108,9 @@ typedef enum {
 
 
 /**
- * cell_new:
- *
- * Create a new %UnitCell.
+ * Create a new UnitCell.
  *
- * Returns: the new unit cell, or NULL on failure.
+ * \returns the new unit cell, or NULL on failure.
  *
  */
 UnitCell *cell_new()
@@ -149,8 +139,7 @@ UnitCell *cell_new()
 
 
 /**
- * cell_free:
- * @cell: A %UnitCell to free.
+ * \param cell: A %UnitCell to free.
  *
  * Frees a %UnitCell, and all internal resources concerning that cell.
  *
@@ -163,10 +152,9 @@ void cell_free(UnitCell *cell)
 
 
 /**
- * cell_has_parameters:
- * @cell: A %UnitCell
+ * \param cell: A %UnitCell
  *
- * Returns: True if @cell has its parameters specified.
+ * \returns True if cell has its parameters specified.
  *
  */
 int cell_has_parameters(UnitCell *cell)
@@ -853,11 +841,10 @@ static char determine_centering(RationalMatrix *P, char cen)
 
 
 /**
- * cell_transform_rational:
- * @cell: A %UnitCell.
- * @t: A %RationalMatrix.
+ * \param cell: A %UnitCell.
+ * \param m: A %RationalMatrix.
  *
- * Applies @t to @cell.
+ * Applies \p m to \p cell.
  *
  * This function will determine the centering of the resulting unit cell,
  * producing '?' if any lattice points cannot be accounted for.  Note that if
@@ -867,7 +854,7 @@ static char determine_centering(RationalMatrix *P, char cen)
  *
  * The lattice type will be set to triclinic, and the unique axis to '?'.
  *
- * Returns: Transformed copy of @cell.
+ * \returns Transformed copy of \p cell.
  *
  */
 UnitCell *cell_transform_rational(UnitCell *cell, RationalMatrix *m)
@@ -910,17 +897,16 @@ UnitCell *cell_transform_rational(UnitCell *cell, RationalMatrix *m)
 
 
 /**
- * cell_transform_intmat:
- * @cell: A %UnitCell.
- * @t: An %IntegerMatrix.
+ * \param cell: A %UnitCell.
+ * \param m: An %IntegerMatrix.
  *
- * Applies @t to @cell.
+ * Applies \p m to \p cell.
  *
- * This is just a convenience function which turns @m into a %RationalMatrix
+ * This is just a convenience function which turns \p m into a %RationalMatrix
  * and then calls cell_transform_rational().  See the documentation for that
  * function for some important information.
  *
- * Returns: Transformed copy of @cell.
+ * \returns Transformed copy of \p cell.
  *
  */
 UnitCell *cell_transform_intmat(UnitCell *cell, IntegerMatrix *m)
@@ -934,13 +920,12 @@ UnitCell *cell_transform_intmat(UnitCell *cell, IntegerMatrix *m)
 
 
 /**
- * cell_transform_rational_inverse:
- * @cell: A %UnitCell.
- * @m: A %RationalMatrix
+ * \param cell: A %UnitCell.
+ * \param m: A %RationalMatrix
  *
- * Applies the inverse of @m to @cell.
+ * Applies the inverse of \p m to \p cell.
  *
- * Returns: Transformed copy of @cell.
+ * \returns Transformed copy of \p cell.
  *
  */
 UnitCell *cell_transform_rational_inverse(UnitCell *cell, RationalMatrix *m)
@@ -1001,13 +986,12 @@ UnitCell *cell_transform_rational_inverse(UnitCell *cell, RationalMatrix *m)
 
 
 /**
- * cell_transform_intmat_inverse:
- * @cell: A %UnitCell.
- * @m: An %IntegerMatrix
+ * \param cell: A %UnitCell.
+ * \param m: An %IntegerMatrix
  *
- * Applies the inverse of @m to @cell.
+ * Applies the inverse of \p m to \p cell.
  *
- * Returns: Transformed copy of @cell.
+ * \returns Transformed copy of \p cell.
  *
  */
 UnitCell *cell_transform_intmat_inverse(UnitCell *cell, IntegerMatrix *m)
diff --git a/libcrystfel/src/cell.h b/libcrystfel/src/cell.h
index c868cd29..15e13707 100644
--- a/libcrystfel/src/cell.h
+++ b/libcrystfel/src/cell.h
@@ -41,32 +41,24 @@
 #include "integer_matrix.h"
 
 /**
- * rvec:
- * @u: x component (in reciprocal space)
- * @v: y component (in reciprocal space)
- * @w: z component (in reciprocal space)
- *
+ * \file cell.h
+ * Unit cell structure
+ */
+
+/**
  * Structure representing a 3D vector in reciprocal space.
+ *
  * Note: Heavily abused to serve as a real space vector as well.
  **/
 struct rvec
 {
-	double   u;
-	double   v;
-	double   w;
+	double   u;  /**< x component (in reciprocal space) */
+	double   v;  /**< y component (in reciprocal space) */
+	double   w;  /**< z component (in reciprocal space) */
 };
 
 
 /**
- * LatticeType:
- * @L_TRICLINIC: Triclinic lattice
- * @L_MONOCLINIC: Monoclinic lattice
- * @L_ORTHORHOMBIC: Orthorhombic lattice
- * @L_TETRAGONAL: Tetragonal lattice
- * @L_RHOMBOHEDRAL: Rhombohedral lattice
- * @L_HEXAGONAL: Hexagonal lattice
- * @L_CUBIC: Cubic lattice
- *
  * An enumeration of the possible lattice types: triclinic, monoclinic,
  * orthorhombic, tetragonal, rhombohedral, hexagonal and cubic.
  **/
@@ -83,7 +75,7 @@ typedef enum
 
 
 /**
- * UnitCell:
+ * Opaque data structure representing a unit cell.
  *
  * This data structure is opaque.  You must use the available accessor functions
  * to read and write its contents.
diff --git a/libcrystfel/src/crystal.c b/libcrystfel/src/crystal.c
index 66a8e19c..ee02e1af 100644
--- a/libcrystfel/src/crystal.c
+++ b/libcrystfel/src/crystal.c
@@ -36,15 +36,7 @@
 
 
 /**
- * SECTION:crystal
- * @short_description: Crystal
- * @title: Crystal
- * @section_id:
- * @see_also:
- * @include: "crystal.h"
- * @Image:
- *
- * This structure represents a single crystal.
+ * \file crystal.h
  */
 
 
@@ -84,11 +76,9 @@ struct _crystal
 
 
 /**
- * crystal_new:
- *
- * Create a new %Crystal.
+ * Create a new \ref Crystal.
  *
- * Returns: the new unit cell, or NULL on failure.
+ * \returns The new unit cell, or NULL on failure.
  *
  */
 Crystal *crystal_new()
@@ -113,14 +103,13 @@ Crystal *crystal_new()
 
 
 /**
- * crystal_copy:
- * @cryst: A %Crystal to copy.
+ * \param cryst: A \ref Crystal to copy.
  *
- * Creates a new %Crystal which is a copy of @cryst.  The copy is a "shallow
+ * Creates a new \ref Crystal which is a copy of \p cryst.  The copy is a "shallow
  * copy", which means that copies are NOT made of the data structures which
- * @cryst contains references to, for example its %RefList.
+ * \p cryst contains references to, for example its \ref RefList.
  *
- * Returns: a (shallow) copy of @cryst, or NULL on failure.
+ * \returns A (shallow) copy of \p cryst, or NULL on failure.
  *
  */
 Crystal *crystal_copy(const Crystal *cryst)
@@ -138,10 +127,9 @@ Crystal *crystal_copy(const Crystal *cryst)
 
 
 /**
- * crystal_free:
- * @cryst: A %Crystal to free.
+ * \param cryst: A \ref Crystal to free.
  *
- * Frees a %Crystal, and all internal resources concerning that crystal.
+ * Frees a \ref Crystal, and all internal resources concerning that crystal.
  *
  */
 void crystal_free(Crystal *cryst)
diff --git a/libcrystfel/src/crystal.h b/libcrystfel/src/crystal.h
index cc5754ca..0358dc8b 100644
--- a/libcrystfel/src/crystal.h
+++ b/libcrystfel/src/crystal.h
@@ -37,10 +37,12 @@
 
 #include "cell.h"
 
+/**
+ * \file crystal.h
+ * Data structure representing a crystal
+ */
 
 /**
- * Crystal:
- *
  * This data structure is opaque.  You must use the available accessor functions
  * to read and write its contents.
  **/
diff --git a/libcrystfel/src/detector.c b/libcrystfel/src/detector.c
index 8c2f3828..2fb373f8 100644
--- a/libcrystfel/src/detector.c
+++ b/libcrystfel/src/detector.c
@@ -45,19 +45,10 @@
 
 
 /**
- * SECTION:detector
- * @short_description: Detector geometry
- * @title: Detector
- * @section_id:
- * @see_also:
- * @include: "detector.h"
- * @Image:
- *
- * This structure represents the detector geometry
+ * \file detector.h
  */
 
 
-
 struct rg_definition {
 	char *name;
 	char *pns;
@@ -2213,13 +2204,12 @@ int write_detector_geometry(const char *geometry_filename,
 
 
 /**
- * mark_resolution_range_as_bad:
- * @image: An image structure
- * @min: Minimum value of 1/d to be marked as bad
- * @max: Maximum value of 1/d to be marked as bad
+ * \param image An image structure
+ * \param min Minimum value of 1/d to be marked as bad
+ * \param max Maximum value of 1/d to be marked as bad
  *
- * Flags, in the bad pixel mask for @image, every pixel whose resolution is
- * between @min and @max.
+ * Flags, in the bad pixel mask for \p image, every pixel whose resolution is
+ * between \p min and \p max.
  *
  */
 
@@ -2266,14 +2256,12 @@ static int safe_strcmp(const char *a, const char *b)
 
 
 /**
- * single_panel_data_source:
- * @det: A detector structure
- * @element: If manually selected by the user, the HDF5 element being used.
+ * \param det A detector structure
+ * \param element If manually selected by the user, the HDF5 element being used.
  * Otherwise NULL.
  *
- * Returns: non-zero if the combination of @det and @element mean that all the
+ * \returns Non-zero if the combination of \p det and \p element mean that all the
  * data comes from a single block.
- *
  */
 int single_panel_data_source(struct detector *det, const char *element)
 {
diff --git a/libcrystfel/src/detector.h b/libcrystfel/src/detector.h
index a7a4a01f..2abd928a 100644
--- a/libcrystfel/src/detector.h
+++ b/libcrystfel/src/detector.h
@@ -53,6 +53,11 @@ struct event;
 extern "C" {
 #endif
 
+/**
+ * \file detector.h
+ * Detector geometry structure and related functions.
+ */
+
 
 struct rigid_group
 {
@@ -80,97 +85,110 @@ struct rg_collection
 
 
 /**
- * panel:
- *  @name: Text name for the panel (fixed length array)
- *  @cnx: Location of corner, in pixels, x coordinate
- *  @cny: Location of corner, in pixels, y coordinate
- *  @coffset: The offset to be applied from @clen (which may come from elsewhere)
- *  @clen: The distance from the interaction point to the corner of the first pixel
- *  @clen_from: Location to get @clen from, e.g. from HDF5 file
- *  @mask: Location of mask data
- *  @mask_file: Filename for mask data
- *  @satmap: Location of per-pixel saturation map
- *  @satmap_file: Filename for saturation map
- *  @res: Resolution of panel in pixels per metre
- *  @badrow: Readout direction (for filtering out clusters of peaks)
- *  @no_index: Non-zero if panel is entirely "bad"
- *  @adu_per_photon: Number of detector intensity units per photon
- *  @adu_per_eV: Number of detector intensity units per eV of photon energy
- *  @max_adu: Saturation value
- *  @dim_structure: Dimension structure
- *  @fsx: Real-space x-direction of data fast-scan direction
- *  @fsy: Real-space y-direction of data fast-scan direction
- *  @fsz: Real-space z-direction of data fast-scan direction
- *  @ssx: Real-space x-direction of data slow-scan direction
- *  @ssy: Real-space y-direction of data slow-scan direction
- *  @ssz: Real-space z-direction of data slow-scan direction
- *  @rail_x: x direction of camera length "rail"
- *  @rail_y: y direction of camera length "rail"
- *  @rail_z: z direction of camera length "rail"
- *  @clen_for_centering: Value of clen (without coffset) at which beam is centered
- *  @xfs: Data fast-scan direction of real-space x-direction
- *  @yfs: Data fast-scan direction of real-space y-direction
- *  @xss: Data slow-scan direction of real-space x-direction
- *  @yss: Data slow-scan direction of real-space y-direction
- *  @orig_min_fs: Minimum fs coordinate of data in file
- *  @orig_max_fs: Maximum fs coordinate of data in file
- *  @orig_min_ss: Minimum ss coordinate of data in file (inclusive)
- *  @orig_max_ss: Maximum ss coordinate of data in file (inclusive)
- *  @data: Location of data in file
- *  @w: Width of panel
- *  @h: Height of panel
+ * Represents one panel of a detector
  */
 struct panel
 {
-	char     name[1024];  /* Name for this panel */
+	/** Text name for panel (fixed length array) */
+	char     name[1024];
 
-	double   cnx;       /* Location of corner (min_fs,min_ss) in pixels */
+	/** \name Location of corner in units of the pixel size of this panel */
+	/**@{*/
+	double   cnx;
 	double   cny;
+	/**@}*/
+
+	/** The offset to be applied from \ref clen */
 	double   coffset;
-	double   clen;     /* Camera length in metres */
+
+	/** The distance from the interaction point to the corner of the
+	 * first pixel */
+	double   clen;
+
+	/** Location to get \ref clen from, e.g. from HDF5 file */
 	char    *clen_from;
+
+	/** Location of mask data */
 	char    *mask;
+
+	/** Filename for mask data */
 	char    *mask_file;
+
+	/** Location of per-pixel saturation map */
 	char    *satmap;
+
+	/** Filename for saturation map */
 	char    *satmap_file;
-	double   res;      /* Resolution in pixels per metre */
-	char     badrow;   /* 'x' or 'y' */
-	int      no_index; /* Don't index peaks in this panel if non-zero */
-	double   adu_per_photon;   /* Number of ADU per photon */
-	double   max_adu;  /* Treat pixel as unreliable if higher than this */
+
+	/** Resolution in pixels per metre  */
+	double   res;
+
+	/** Readout direction (for filtering out clusters of peaks)
+	  * ('x' or 'y') */
+	char     badrow;
+
+	/** Non-zero if panel should be considered entirely bad */
+	int      no_index;
+
+	/** Number of detector intensity units per photon */
+	double   adu_per_photon;
+
+	/** Treat pixel as unreliable if higher than this */
+	double   max_adu;
+
+	/** Location of data in file */
 	char    *data;
 
-	double   adu_per_eV;   /* Number of ADU per eV */
+	/** Number of detector intensity units per eV of photon energy */
+	double   adu_per_eV;
 
+	/** Dimension structure */
 	struct dim_structure *dim_structure;
 
+	/** \name Transformation matrix from pixel coordinates to lab frame */
+	/*@{*/
 	double fsx;
 	double fsy;
 	double fsz;
 	double ssx;
 	double ssy;
 	double ssz;
+	/*@}*/
 
+	/** \name Rail direction */
+	/*@{*/
 	double rail_x;
 	double rail_y;
 	double rail_z;
+	/*@}*/
+
+	/* Value of clen (without coffset) at which beam is centered */
 	double clen_for_centering;
 
+	/** \name Inverse of 2D part of transformation matrix */
+	/*@{*/
 	double xfs;
 	double yfs;
 	double xss;
 	double yss;
+	/*@}*/
 
-	/* Position of the panel in the data block in the file.  The panels may
-	* get moved around when the file is loaded (see hdf5_read2()),
-	* especially if the panels come from different HDF5 elements. */
+	/** \name Position of the panel in the data block in the file.
+	 * The panels may get moved around when the file is loaded (see
+	 * hdf5_read2()), especially if the panels come from different HDF5
+	 * elements. */
+	/*@{*/
 	int orig_min_fs;
 	int orig_max_fs;
 	int orig_min_ss;
 	int orig_max_ss;
+	/*@}*/
+
+	/** Width, calculated as max_fs-min_fs+1 */
+	int w;
 
-	int w;  /* Width, calculated as max_fs-min_fs+1 */
-	int h;  /* Height, calculated as max_ss-min_ss+1 */
+	/*** Height, calculated as max_ss-min_ss+1 */
+	int h;
 };
 
 
diff --git a/libcrystfel/src/dirax.c b/libcrystfel/src/dirax.c
index 53090c7c..3e02d5b5 100644
--- a/libcrystfel/src/dirax.c
+++ b/libcrystfel/src/dirax.c
@@ -56,6 +56,8 @@
 #include "cell-utils.h"
 
 
+/** \file dirax.h */
+
 #define DIRAX_VERBOSE 0
 
 #define MAX_DIRAX_CELL_CANDIDATES (5)
diff --git a/libcrystfel/src/dirax.h b/libcrystfel/src/dirax.h
index dce27c57..e3b03565 100644
--- a/libcrystfel/src/dirax.h
+++ b/libcrystfel/src/dirax.h
@@ -39,6 +39,9 @@
 extern "C" {
 #endif
 
+/** \file dirax.h
+ * DirAx indexer interface
+ */
 extern int run_dirax(struct image *image, void *ipriv);
 
 extern void *dirax_prepare(IndexingMethod *indm, UnitCell *cell);
diff --git a/libcrystfel/src/events.c b/libcrystfel/src/events.c
index 7cd05784..b1cd5d11 100644
--- a/libcrystfel/src/events.c
+++ b/libcrystfel/src/events.c
@@ -35,6 +35,7 @@
 #include <stdlib.h>
 #include <assert.h>
 
+/** \file events.h */
 
 struct event *initialize_event()
 {
@@ -229,11 +230,10 @@ static int events_equal(struct event *ev1, struct event *ev2)
 
 
 /**
- * find_event:
- * @ev: An event structure
- * @el: An event list
+ * \param ev: An event structure
+ * \param el: An event list
  *
- * Returns: the indexing into @el of the event matching @ev, of el->num_events
+ * \returns The indexing into \p el of the event matching \p ev, of el->num_events
  * if no such event is found.
  **/
 int find_event(struct event *ev, struct event_list *el)
diff --git a/libcrystfel/src/events.h b/libcrystfel/src/events.h
index d7fae24a..6e9204b3 100644
--- a/libcrystfel/src/events.h
+++ b/libcrystfel/src/events.h
@@ -33,6 +33,11 @@
 #ifndef EVENTS_H
 #define EVENTS_H
 
+/**
+ * \file events.h
+ * Event description structures
+ */
+
 struct event
 {
 	char **path_entries;
@@ -53,7 +58,7 @@ struct filename_plus_event
 	struct event *ev;
 };
 
-enum
+enum dimension_id
 {
 	HYSL_UNDEFINED = -99,
 	HYSL_PLACEHOLDER = -98,
diff --git a/libcrystfel/src/felix.c b/libcrystfel/src/felix.c
index b0cb605d..ea27093a 100644
--- a/libcrystfel/src/felix.c
+++ b/libcrystfel/src/felix.c
@@ -32,6 +32,8 @@
 #endif
 
 
+/** \file felix.h */
+
 #include <stdlib.h>
 #include <stdio.h>
 #include <math.h>
diff --git a/libcrystfel/src/felix.h b/libcrystfel/src/felix.h
index b1776293..645adaeb 100644
--- a/libcrystfel/src/felix.h
+++ b/libcrystfel/src/felix.h
@@ -36,6 +36,11 @@
 
 #include "cell.h"
 
+/**
+ * \file felix.h
+ * Felix indexer interface
+ */
+
 struct felix_options
 {
 	double ttmin;  /* radians */
diff --git a/libcrystfel/src/filters.c b/libcrystfel/src/filters.c
index cbaf6001..2f802dd3 100644
--- a/libcrystfel/src/filters.c
+++ b/libcrystfel/src/filters.c
@@ -41,6 +41,7 @@
 
 #include "image.h"
 
+/** \file filters.h */
 
 static void filter_noise_in_panel(float *data, int width, int height)
 {
diff --git a/libcrystfel/src/filters.h b/libcrystfel/src/filters.h
index 1d4f7bf0..5738726e 100644
--- a/libcrystfel/src/filters.h
+++ b/libcrystfel/src/filters.h
@@ -37,6 +37,10 @@
 extern "C" {
 #endif
 
+/**
+ * \file filters.h
+ * Image noise filtering functions
+ */
 extern void filter_cm(struct image *image);
 extern void filter_noise(struct image *image);
 extern void filter_median(struct image *image, int size);
diff --git a/libcrystfel/src/geometry.c b/libcrystfel/src/geometry.c
index 9ae6d96f..ffb17133 100644
--- a/libcrystfel/src/geometry.c
+++ b/libcrystfel/src/geometry.c
@@ -47,6 +47,7 @@
 #include "symmetry.h"
 #include "geometry.h"
 
+/** \file geometry.h */
 
 static int locate_peak_on_panel(double x, double y, double z, double k,
                                 struct panel *p,
@@ -380,6 +381,15 @@ double r_gradient(UnitCell *cell, int k, Reflection *refl, struct image *image)
 }
 
 
+/**
+ * \param cryst: A \ref Crystal
+ * \param max_res: Maximum resolution to predict to (m^-1)
+ *
+ * Calculates reflection positions for \p crys, up to maximum 1/d value
+ * \p max_res
+ *
+ * \returns A list of predicted reflections
+ */
 RefList *predict_to_res(Crystal *cryst, double max_res)
 {
 	double ax, ay, az;
@@ -713,16 +723,15 @@ static void ginn_spectrum_partialities(Crystal *cryst)
 
 
 /**
- * calculate_partialities:
- * @cryst: A %Crystal
- * @pmodel: A %PartialityModel
+ * \param cryst A \ref Crystal
+ * \param pmodel A \ref PartialityModel
  *
- * Calculates the partialities for the reflections in @cryst, given the current
+ * Calculates the partialities for the reflections in \p cryst, given the current
  * crystal and image parameters.  The crystal's image and reflection lists
- * must be set.  The specified %PartialityModel will be used.
+ * must be set.  The specified \ref PartialityModel will be used.
  *
  * You must not have changed the crystal or image parameters since you last
- * called predict_to_res() or update_predictions(), because this function
+ * called \ref predict_to_res or \ref update_predictions, because this function
  * relies on the limiting wavelength values calculated by those functions.
  */
 void calculate_partialities(Crystal *cryst, PartialityModel pmodel)
@@ -750,15 +759,14 @@ void calculate_partialities(Crystal *cryst, PartialityModel pmodel)
 
 
 /**
- * update_predictions:
- * @cryst: A %Crystal
+ * \param cryst A \ref Crystal
  *
  * Updates the predicted reflections (positions and excitation errors, but not
- * the actual partialities) of @cryst's reflections according to
+ * the actual partialities) of \p cryst's reflections according to
  * the current state of the crystal (e.g. its unit cell parameters).
  *
- * If you need to update the partialities as well, call calculate_partialities()
- * afterwards.
+ * If you need to update the partialities as well, call
+ * \ref calculate_partialities afterwards.
  */
 void update_predictions(Crystal *cryst)
 {
diff --git a/libcrystfel/src/geometry.h b/libcrystfel/src/geometry.h
index 529f112e..a9000428 100644
--- a/libcrystfel/src/geometry.h
+++ b/libcrystfel/src/geometry.h
@@ -45,24 +45,26 @@ extern "C" {
 #endif
 
 /**
- * PartialityModel:
- * @PMODEL_UNITY : Set all all partialities and Lorentz factors to 1.
- * @PMODEL_XSPHERE : Flat sphere model with super-Gaussian spectrum
- * @PMODEL_RANDOM : Randomly assigned partialities
+ * \file geometry.h
+ * Geometry of diffraction
  *
- * A %PartialityModel describes a geometrical model which can be used to
+ * This contains the prediction and partiality calculation functions.
+ */
+
+/**
+ * A PartialityModel describes a geometrical model which can be used to
  * calculate spot partialities and Lorentz correction factors.
  **/
 typedef enum {
 
-	PMODEL_UNITY,
-	PMODEL_XSPHERE,
-	PMODEL_RANDOM,
+	PMODEL_UNITY,   /**< Set all partialities and Lorentz factors to 1. */
+	PMODEL_XSPHERE, /**< Flat sphere model with super-Gaussian spectrum */
+	PMODEL_RANDOM,  /**< Randomly assigned partialities */
 
 } PartialityModel;
 
 
-/* Enumeration of parameters which may want to be refined */
+/** Enumeration of parameters which may want to be refined */
 enum gparam {
 	GPARAM_ASX,
 	GPARAM_ASY,
diff --git a/libcrystfel/src/hdf5-file.c b/libcrystfel/src/hdf5-file.c
index 7a8f359e..7aa8165d 100644
--- a/libcrystfel/src/hdf5-file.c
+++ b/libcrystfel/src/hdf5-file.c
@@ -43,19 +43,7 @@
 #include "hdf5-file.h"
 #include "utils.h"
 
-
-/**
- * SECTION:hdf5-file
- * @short_description: HDF5 file handling
- * @title: HDF5 file handling
- * @section_id:
- * @see_also:
- * @include: "hdf5-file.h"
- * @Image:
- *
- * Routines for accessing HDF5 files.
- **/
-
+/** \file hdf5-file.h */
 
 struct hdf5_write_location {
 
@@ -333,19 +321,18 @@ static float *read_hdf5_data(struct hdfile *f, char *path, int line)
 
 
 /**
- * get_peaks_cxi_2:
- * @image: An %image structure
- * @f: An %hdfile structure
- * @p: The HDF5 path to the peak data
- * @fpe: A %filename_plus_event structure specifying the event
- * @half_pixel_shift: Non-zero if 0.5 should be added to all peak coordinates
+ * \param image: An \ref image structure
+ * \param f: An \ref hdfile structure
+ * \param p: The HDF5 path to the peak data
+ * \param fpe: A \ref filename_plus_event structure specifying the event
+ * \param half_pixel_shift: Non-zero if 0.5 should be added to all peak coordinates
  *
  * Get peaks from HDF5, in "CXI format" (as in "CXIDB").  The data should be in
- * a set of arrays under @p.  The number of peaks should be in a 1D array at
- * @p/nPeaks. The fast-scan and slow-scan coordinates should be in 2D arrays at
- * @p/peakXPosRaw and @p/peakYPosRaw respectively (sorry about the naming).  The
+ * a set of arrays under \p p.  The number of peaks should be in a 1D array at
+ * \p p/nPeaks. The fast-scan and slow-scan coordinates should be in 2D arrays at
+ * \p p/peakXPosRaw and \p p/peakYPosRaw respectively (sorry about the naming).  The
  * first dimension of these arrays should be the event number (as given by
- * @fpe).  The intensities are expected to be at @p/peakTotalIntensity in a
+ * \p fpe).  The intensities are expected to be at \p p/peakTotalIntensity in a
  * similar 2D array.
  *
  * CrystFEL considers all peak locations to be distances from the corner of the
@@ -353,9 +340,9 @@ static float *read_hdf5_data(struct hdfile *f, char *path, int line)
  * geometry (see 'man crystfel_geometry').  The software which generates the
  * CXI files, including Cheetah, may instead consider the peak locations to be
  * pixel indices in the data array.  In this case, the peak coordinates should
- * have 0.5 added to them.  This will be done if @half_pixel_shift is non-zero.
+ * have 0.5 added to them.  This will be done if \p half_pixel_shift is non-zero.
  *
- * Returns: non-zero on error, zero otherwise.
+ * \returns Non-zero on error, zero otherwise.
  *
  */
 int get_peaks_cxi_2(struct image *image, struct hdfile *f, const char *p,
@@ -438,18 +425,17 @@ int get_peaks_cxi_2(struct image *image, struct hdfile *f, const char *p,
 
 
 /**
- * get_peaks_cxi:
- * @image: An %image structure
- * @f: An %hdfile structure
- * @p: The HDF5 path to the peak data
- * @fpe: A %filename_plus_event structure specifying the event
+ * \param image: An \ref image structure
+ * \param f: An \ref hdfile structure
+ * \param p: The HDF5 path to the peak data
+ * \param fpe: A \ref filename_plus_event structure specifying the event
  *
  * This is a wrapper function to preserve API compatibility with older CrystFEL
- * versions.  Use get_peaks_cxi_2() instead.
+ * versions.  Use \ref get_peaks_cxi_2 instead.
  *
- * This function is equivalent to get_peaks_cxi_2(@image, @f, @p, @fpe, 1).
+ * This function is equivalent to get_peaks_cxi_2(\p image, \p f, \p p, \p fpe, 1).
  *
- * Returns: non-zero on error, zero otherwise.
+ * \returns Non-zero on error, zero otherwise.
  *
  */
 int get_peaks_cxi(struct image *image, struct hdfile *f, const char *p,
@@ -460,13 +446,12 @@ int get_peaks_cxi(struct image *image, struct hdfile *f, const char *p,
 
 
 /**
- * get_peaks_2:
- * @image: An %image structure
- * @f: An %hdfile structure
- * @p: The HDF5 path to the peak data
- * @half_pixel_shift: Non-zero if 0.5 should be added to all peak coordinates
+ * \param image: An \ref image structure
+ * \param f: An \ref hdfile structure
+ * \param p: The HDF5 path to the peak data
+ * \param half_pixel_shift: Non-zero if 0.5 should be added to all peak coordinates
  *
- * Get peaks from HDF5.  The peak list should be located at @p in the HDF5 file,
+ * Get peaks from HDF5.  The peak list should be located at \p p in the HDF5 file,
  * a 2D array where the first dimension equals the number of peaks and second
  * dimension is three.  The first two columns contain the fast scan and slow
  * scan coordinates, respectively, of the peaks.  The third column contains the
@@ -477,9 +462,9 @@ int get_peaks_cxi(struct image *image, struct hdfile *f, const char *p,
  * geometry (see 'man crystfel_geometry').  The software which generates the
  * CXI files, including Cheetah, may instead consider the peak locations to be
  * pixel indices in the data array.  In this case, the peak coordinates should
- * have 0.5 added to them.  This will be done if @half_pixel_shift is non-zero.
+ * have 0.5 added to them.  This will be done if \p half_pixel_shift is non-zero.
  *
- * Returns: non-zero on error, zero otherwise.
+ * \returns Non-zero on error, zero otherwise.
  *
  */
 int get_peaks_2(struct image *image, struct hdfile *f, const char *p,
@@ -592,17 +577,16 @@ int get_peaks_2(struct image *image, struct hdfile *f, const char *p,
 
 
 /**
- * get_peaks:
- * @image: An %image structure
- * @f: An %hdfile structure
- * @p: The HDF5 path to the peak data
+ * \param image: An \ref image structure
+ * \param f: An \ref hdfile structure
+ * \param p: The HDF5 path to the peak data
  *
  * This is a wrapper function to preserve API compatibility with older CrystFEL
- * versions.  Use get_peaks_2() instead.
+ * versions.  Use \ref get_peaks_2 instead.
  *
- * This function is equivalent to get_peaks_2(@image, @f, @p, 1).
+ * This function is equivalent to \ref get_peaks_2(\p image, \p f, \p p, 1).
  *
- * Returns: non-zero on error, zero otherwise.
+ * \returns Non-zero on error, zero otherwise.
  *
  */
 int get_peaks(struct image *image, struct hdfile *f, const char *p)
diff --git a/libcrystfel/src/hdf5-file.h b/libcrystfel/src/hdf5-file.h
index ab53dd2e..793d83cd 100644
--- a/libcrystfel/src/hdf5-file.h
+++ b/libcrystfel/src/hdf5-file.h
@@ -52,6 +52,11 @@ struct copy_hdf5_field;
 extern "C" {
 #endif
 
+/**
+ * \file hdf5-file.h
+ * HDF5 abstraction layer
+ */
+
 extern int hdf5_write(const char *filename, const void *data,
                       int width, int height, int type);
 
diff --git a/libcrystfel/src/histogram.c b/libcrystfel/src/histogram.c
index 39f034d6..69acd987 100644
--- a/libcrystfel/src/histogram.c
+++ b/libcrystfel/src/histogram.c
@@ -38,6 +38,8 @@
 
 #include "histogram.h"
 
+/** \file histogram.h */
+
 struct _histogram
 {
 	int n_vals;
diff --git a/libcrystfel/src/histogram.h b/libcrystfel/src/histogram.h
index c3ff27f7..2b9d4928 100644
--- a/libcrystfel/src/histogram.h
+++ b/libcrystfel/src/histogram.h
@@ -37,6 +37,11 @@
 extern "C" {
 #endif
 
+/**
+ * \file histogram.h
+ * Quick histogram functions
+ */
+
 typedef struct _histogram Histogram;
 
 extern Histogram *histogram_init();
diff --git a/libcrystfel/src/image.c b/libcrystfel/src/image.c
index 5cc073d8..258d2a87 100644
--- a/libcrystfel/src/image.c
+++ b/libcrystfel/src/image.c
@@ -42,20 +42,7 @@
 #include "hdf5-file.h"
 #include "detector.h"
 
-/**
- * SECTION:image
- * @short_description: Data structure representing an image
- * @title: Image
- * @section_id:
- * @see_also:
- * @include: "image.h"
- * @Image:
- *
- * The <structname>image</structname> structure represents an image, usually one
- * frame from a large series of diffraction patterns, which might be from the
- * same or different crystals.
- */
-
+/** \file image.h */
 
 struct imagefile
 {
diff --git a/libcrystfel/src/image.h b/libcrystfel/src/image.h
index cf06d0a1..e1b3ab69 100644
--- a/libcrystfel/src/image.h
+++ b/libcrystfel/src/image.h
@@ -55,57 +55,53 @@ struct imagefile_field_list;
 #include "index.h"
 #include "events.h"
 
-
-
 /**
- * imagefeature:
- *  @parent: Image this feature belongs to
- *  @fs: Fast scan coordinate
- *  @ss: Slow scan coordinate
- *  @p: Pointer to panel
- *  @intensity: Intensity of peak
- *  @rx: Reciprocal x coordinate in m^-1
- *  @ry: Reciprocal y coordinate in m^-1
- *  @rz: Reciprocal z coordinate in m^-1
- *  @name: Text name for feature
+ * \file image.h
  *
- *  Represents a peak in an image.
- *
- *  Note carefully that the @fs and @ss coordinates are the distances, measured
- *  in pixels, from the corner of the panel.  They are NOT pixel indices.
- *  If the peak is in the middle of the first pixel, its coordinates would be
- *  0.5,0.5.
+ * Information about images
  */
+
+/** Represents a peak in an image. */
 struct imagefeature {
 
-	struct image                    *parent;
+	struct image                    *parent;   /**< Pointer to image */
+
+	/** \name Coordinates on panel (fast scan, slow scan)
+	 *  Note carefully that these are the distances, measured in pixels,
+	 *  from the corner of the panel.  They are NOT pixel indices.
+	 *  If the peak is in the middle of the first pixel, its coordinates would be
+	 *  0.5,0.5. */
+	/**@{*/
 	double                          fs;
 	double                          ss;
-	struct panel                    *p;
-	double                          intensity;
+	/**@}*/
+
+	struct panel                    *p;         /**< Pointer to panel */
+	double                          intensity;  /**< Intensity */
 
-	/* Reciprocal space coordinates (m^-1 of course) of this feature */
+	/** \name Reciprocal space coordinates (m^-1) of this feature */
+	/** @{ */
 	double                          rx;
 	double                          ry;
 	double                          rz;
+	/** @} */
 
-	const char                      *name;
+	const char                      *name;  /**< Text name, e.g. "5,3,-1" */
 
-	/*< private >*/
-	int                             valid;
+	int                             valid;  /**< \private */
 };
 
 
-/* An enum representing the image file formats we can handle */
+/** An enum representing the image file formats we can handle */
 enum imagefile_type
 {
-	IMAGEFILE_HDF5,
-	IMAGEFILE_CBF,
-	IMAGEFILE_CBFGZ
+	IMAGEFILE_HDF5,   /**< HDF5 file (single or multiple frames per file) */
+	IMAGEFILE_CBF,    /**< CBF file */
+	IMAGEFILE_CBFGZ   /**< gzipped CBF file, i.e. "file.cbf.gz" */
 };
 
 
-/* An opaque type representing a list of image features */
+/** An opaque type representing a list of image features */
 typedef struct _imagefeaturelist ImageFeatureList;
 
 
@@ -117,116 +113,106 @@ struct spectrum
 };
 
 
-/* Structure describing a wavelength sample from a spectrum */
+/** Structure describing a wavelength sample from a spectrum.
+ * \deprecated Use struct spectrum instead. */
 struct sample
 {
-	double k; /* 1/m */
-	double weight;
+	double k;         /**< Wavevector in m^-1 */
+	double weight;    /**< Relative weight */
 };
 
 
-/**
- * beam_params:
- *  @photon_energy: eV per photon
- *  @photon_energy_from: HDF5 dataset name
- *  @photon_energy_scale: Scale factor for photon energy, if it comes from HDF5
- */
 struct beam_params
 {
-	double photon_energy;
-	char  *photon_energy_from;
-	double photon_energy_scale;
+	double photon_energy;       /**< eV per photon */
+	char  *photon_energy_from;  /**< HDF5 dataset name */
+	double photon_energy_scale; /**< Scale factor for photon energy, if it
+	                             *   comes from an image header */
 };
 
 
-/**
- * image:
- *   @hit: Non-zero if the frame was determined to be a "hit"
- *   @crystals: Array of crystals in the image
- *   @n_crystals: The number of crystals in the image
- *   @indexed_by: Indexing method which indexed this pattern
- *   @n_indexing_tries: Number of times the indexer was tried before indexing
- *   @det: Detector structure
- *   @beam: Beam parameters structure
- *   @filename: Filename for the image file
- *   @copyme: Fields to copy from the image file to the stream
- *   @id: ID number of the thread handling this image
- *   @serial: Serial number for this image
- *   @lambda: Wavelength
- *   @div: Divergence
- *   @bw: Bandwidth
- *   @num_peaks: The number of peaks
- *   @num_saturated_peaks: The number of saturated peaks
- *   @features: The peaks found in the image
- *   @dp: The image data, by panel
- *   @bad: The bad pixel mask, array by panel
- *   @sat: The per-pixel saturation mask, array by panel
- *   @event: Event ID for the image
- *   @stuff_from_stream: Items read back from the stream
- *   @avg_clen: Mean of camera length values for all panels
- *   @spectrum: Spectrum information
- *   @nsamples: Number of spectrum samples
- *   @spectrum_size: Size of spectrum array
- *
- * The field <structfield>data</structfield> contains the raw image data, if it
- * is currently available.  The data might be available throughout the
- * processing of an experimental pattern, but it might not be available when
- * simulating, scaling or merging patterns.
- *
- * <structfield>crystals</structfield> is an array of %Crystal directly
- * returned by the low-level indexing system. <structfield>n_crystals</structfield>
- * is the number of crystals which were found in the image.
- *
- * <structfield>copyme</structfield> represents a list of fields in the image
- * file (e.g. HDF5 fields or CBF headers) to copy to the output stream.
- **/
-struct image;
+struct image
+{
+	/** The image data, by panel */
+	float                   **dp;
 
-struct image {
+	/** The bad pixel mask, by panel */
+	int                     **bad;
 
-	float                   **dp;    /* Data in panel */
-	int                     **bad;   /* Bad pixels by panel */
-	float                   **sat;   /* Per-pixel saturation values */
+	/** The per-pixel saturation values, by panel */
+	float                   **sat;
 
+	/** Non-zero if the frame was determined to be a "hit" */
 	int                     hit;
+
+	/**Array of crystals in the image */
 	Crystal                 **crystals;
+
+	/** The number of crystals in the image (size of \p crystals) */
 	int                     n_crystals;
+
+	/** Indexing method which indexed this pattern */
 	IndexingMethod          indexed_by;
+
+	/** Number of times the indexer was tried before succeeding */
 	int                     n_indexing_tries;
 
+	/** The detector structure */
 	struct detector         *det;
-	struct beam_params      *beam;  /* The nominal beam parameters */
+
+	/** The nominal beam parameters (or where to get them) */
+	struct beam_params      *beam;
+
+	/** \name The filename and event ID for the image
+	 * @{ */
 	char                    *filename;
 	struct event            *event;
+	/** @} */
+
+	/** A list of image file headers to copy to the stream */
 	const struct imagefile_field_list *copyme;
+
+	/** A list of metadata read from the stream */
 	struct stuff_from_stream *stuff_from_stream;
 
-	double                  avg_clen;  /* Average camera length extracted
-	                                    * from stuff_from_stream */
+	/** Mean of the camera length values for all panels */
+	double                  avg_clen;
+
+	/** ID number of the worker processing handling this image */
+	int                     id;
 
-	int                     id;   /* ID number of the thread
-	                               * handling this image */
-	int                     serial;  /* Monotonically ascending serial
-	                                  * number for this image */
+	/** Monotonically increasing serial number for this image */
+	int                     serial;
 
-	struct spectrum *spectrum; /* Beam spectrum for pink beam data */
+	/** Spectrum information (new format) */
+	struct spectrum *spectrum;
 
-	/* FIXME: These are only used in pattern_sim, which should be changed to
-	 * use the "struct spectrum" from above later */
+	/** \name Spectrum information (old format)
+	 * @{
+	 * Array of samples, number of samples, and size of the array (may be
+	 * larger than nsamples) */
 	struct sample           *spectrum0;
-	int                     nsamples; /* Number of wavelengths */
-	int                     spectrum_size;  /* Size of "spectrum" */
+	int                     nsamples;
+	int                     spectrum_size;
+	/** @} */
 
-	/* Per-shot radiation values */
-	double                  lambda;        /* Wavelength in m */
-	double                  div;           /* Divergence in radians */
-	double                  bw;            /* FWHM bandwidth as a fraction */
+	/** Wavelength of the incident radiation, in metres */
+	double                  lambda;
 
-	/* Detected peaks */
+	/** Convergence angle of the incident ration, in radians (full angle) */
+	double                  div;
+
+	/** Full-width half-maximum bandwidth as a fraction, applied to wavelength */
+	double                  bw;
+
+	/** \name Numbers of peaks.  To be deleted.
+	 * @{ */
 	long long               num_peaks;
 	long long               num_saturated_peaks;
-	double                  peak_resolution;  /* Estimate of resolution
-	                                           * based on peaks only */
+	double                  peak_resolution;
+	/** @} */
+
+	/** List of peaks found in the image */
 	ImageFeatureList        *features;
 
 };
diff --git a/libcrystfel/src/index.c b/libcrystfel/src/index.c
index ad9c0de3..6f0d1b8c 100644
--- a/libcrystfel/src/index.c
+++ b/libcrystfel/src/index.c
@@ -60,6 +60,9 @@
 #include "xgandalf.h"
 
 
+/** \file index.h */
+
+
 struct _indexingprivate
 {
 	IndexingFlags flags;
diff --git a/libcrystfel/src/index.h b/libcrystfel/src/index.h
index eaf6f912..15b21e25 100644
--- a/libcrystfel/src/index.h
+++ b/libcrystfel/src/index.h
@@ -38,6 +38,11 @@
 #include <config.h>
 #endif
 
+/**
+ * \file index.h
+ * The indexing subsystem
+ */
+
 
 #define INDEXING_DEFAULTS_DIRAX (INDEXING_DIRAX)
 
@@ -59,62 +64,64 @@
 #define INDEXING_DEFAULTS_XGANDALF (INDEXING_XGANDALF | INDEXING_USE_CELL_PARAMETERS)
 
 /**
- * IndexingMethod:
- * @INDEXING_NONE: No indexing to be performed
- * @INDEXING_DIRAX: Invoke DirAx
- * @INDEXING_MOSFLM: Invoke MOSFLM
- * @INDEXING_FELIX: Invoke Felix
- * @INDEXING_XDS: Invoke XDS
- * @INDEXING_SIMULATION: Dummy value
- * @INDEXING_DEBUG: Results injector for debugging
- * @INDEXING_ASDF: Use in-built "asdf" indexer
- * @INDEXING_TAKETWO: Use in-built "taketwo" indexer
- * @INDEXING_XGANDALF: Invoke XGANDALF
- * @INDEXING_ERROR: Special value for unrecognised indexing engine name
- * @INDEXING_USE_LATTICE_TYPE: Use lattice type and centering information to
- *   guide the indexing process.
- * @INDEXING_USE_CELL_PARAMETERS: Use the unit cell parameters to guide the
- *   indexing process.
- *
- * An enumeration of all the available indexing methods.  The dummy value
- * @INDEXING_SIMULATION is used by partial_sim to indicate that no indexing was
- * performed, and that the indexing results are just from simulation.
+ * An enumeration of all the available indexing methods.
  **/
 typedef enum {
 
-	INDEXING_NONE   = 0,
-
-	/* The core indexing methods themselves */
-	INDEXING_DIRAX  = 1,
-	INDEXING_MOSFLM = 2,
-	INDEXING_FELIX = 4,
-	INDEXING_XDS = 5,
-	INDEXING_SIMULATION = 6,
-	INDEXING_DEBUG = 7,
-	INDEXING_ASDF = 8,
-	INDEXING_TAKETWO = 9,
-	INDEXING_XGANDALF = 10,
-
-	INDEXING_ERROR = 255,  /* Unrecognised indexing engine */
-
-	/* Bits at the top of the IndexingMethod are flags which modify the
-	 * behaviour of the indexer. */
+	INDEXING_NONE   = 0,      /**< No indexing to be performed */
+
+	INDEXING_DIRAX  = 1,      /**< Invoke DirAx program */
+	INDEXING_MOSFLM = 2,      /**< Invoke MOSFLM program */
+	INDEXING_FELIX = 4,       /**< Invoke Felix program */
+	INDEXING_XDS = 5,         /**< Invoke XDS program (NB not nXDS) */
+	INDEXING_SIMULATION = 6,  /**< Dummy value for simulated data */
+	INDEXING_DEBUG = 7,       /**< Results injector for debugging */
+	INDEXING_ASDF = 8,        /**< Use built-in ASDF algorithm */
+	INDEXING_TAKETWO = 9,     /**< Use built-in TakeTwo algorithm */
+	INDEXING_XGANDALF = 10,   /**< Use XGANDALF (via optional library) */
+
+	INDEXING_ERROR = 255,     /**< Special value for unrecognised indexing
+	                           *   engine */
+
+	/** \name Bits which can be set to modify the behaviour of the above
+	 *  indexing methods */
+	/**@{*/
+	/** Use lattice type and centering information */
 	INDEXING_USE_LATTICE_TYPE        = 2048,
+
+	/** Use the cell parameters themselves */
 	INDEXING_USE_CELL_PARAMETERS     = 4096,
+	/**@}*/
+
 
 } IndexingMethod;
 
-/* This defines the bits in "IndexingMethod" which are used to represent the
+/** This defines the bits in "IndexingMethod" which are used to represent the
  * core of the indexing method */
 #define INDEXING_METHOD_MASK (0xff)
 
+/**
+ * Flags affecting how the indexing system processes the results from the
+ * indexing engine
+ */
 typedef enum {
 
+	/** Retry indexing if it doesn't work */
 	INDEXING_RETRY = 1,
+
+	/** Attempt to index remaining peaks to find more lattices */
 	INDEXING_MULTI = 2,
+
+	/** Refine the indexing solution */
 	INDEXING_REFINE = 4,
+
+	/** Check the unit cell, including derivative lattices */
 	INDEXING_CHECK_CELL_COMBINATIONS = 8,
+
+	/** Check the unit cell, only permuting axes if necessary */
 	INDEXING_CHECK_CELL_AXES = 16,
+
+	/** Check that the peaks agree with the indexing solution */
 	INDEXING_CHECK_PEAKS = 32,
 
 } IndexingFlags;
@@ -124,8 +131,6 @@ extern "C" {
 #endif
 
 /**
- * IndexingPrivate:
- *
  * This is an opaque data structure containing information needed by the
  * indexing system.
  **/
diff --git a/libcrystfel/src/integer_matrix.c b/libcrystfel/src/integer_matrix.c
index 82ff461e..1d1c3a47 100644
--- a/libcrystfel/src/integer_matrix.c
+++ b/libcrystfel/src/integer_matrix.c
@@ -40,17 +40,7 @@
 #include "utils.h"
 
 
-/**
- * SECTION:integer_matrix
- * @short_description: Integer matrices
- * @title: Integer matrices
- * @section_id:
- * @see_also:
- * @include: "integer_matrix.h"
- * @Image:
- *
- * An integer matrix library
- */
+/** \file integer_matrix.h */
 
 
 struct _integermatrix
@@ -63,13 +53,12 @@ struct _integermatrix
 
 
 /**
- * intmat_new:
- * @rows: Number of rows that the new matrix is to have
- * @cols: Number of columns that the new matrix is to have
+ * \param rows Number of rows that the new matrix is to have
+ * \param cols Number of columns that the new matrix is to have
  *
- * Allocates a new %IntegerMatrix with all elements set to zero.
+ * Allocates a new \ref IntegerMatrix with all elements set to zero.
  *
- * Returns: a new %IntegerMatrix, or NULL on error.
+ * \returns A new \ref IntegerMatrix, or NULL on error.
  **/
 IntegerMatrix *intmat_new(unsigned int rows, unsigned int cols)
 {
@@ -92,10 +81,9 @@ IntegerMatrix *intmat_new(unsigned int rows, unsigned int cols)
 
 
 /**
- * intmat_copy:
- * @m: An %IntegerMatrix
+ * \param m An \ref IntegerMatrix
  *
- * Returns: a newly allocated copy of @m, or NULL on error/
+ * \returns A newly allocated copy of \p m, or NULL on error
  **/
 IntegerMatrix *intmat_copy(const IntegerMatrix *m)
 {
@@ -116,10 +104,9 @@ IntegerMatrix *intmat_copy(const IntegerMatrix *m)
 
 
 /**
- * intmat_free:
- * @m: An %IntegerMatrix
+ * \param m An \ref IntegerMatrix
  *
- * Frees @m, unless @m is NULL in which case nothing is done.
+ * Frees \p m, unless \p m is NULL in which case nothing is done.
  **/
 void intmat_free(IntegerMatrix *m)
 {
@@ -129,6 +116,13 @@ void intmat_free(IntegerMatrix *m)
 }
 
 
+/**
+ * \param m An \ref IntegerMatrix
+ * \param rows Location to store number of rows
+ * \param cols Location to store number of columns
+ *
+ * Sets \p rows and \p cols to the size of \p m.
+ */
 void intmat_size(const IntegerMatrix *m, unsigned int *rows, unsigned int *cols)
 {
 	if ( m == NULL ) {
@@ -143,13 +137,12 @@ void intmat_size(const IntegerMatrix *m, unsigned int *rows, unsigned int *cols)
 
 
 /**
- * intmat_set:
- * @m: An %IntegerMatrix
- * @i: row number to set
- * @j: column number to set
- * @v: value to set to
+ * \param m An \ref IntegerMatrix
+ * \param i row number to set
+ * \param j column number to set
+ * \param v value to set to
  *
- * Sets the @i,@j element of @m to @v.
+ * Sets the \p i,\p j element of \p m to \p v.
  **/
 void intmat_set(IntegerMatrix *m, unsigned int i, unsigned int j, signed int v)
 {
@@ -160,14 +153,13 @@ void intmat_set(IntegerMatrix *m, unsigned int i, unsigned int j, signed int v)
 
 
 /**
- * intmat_get:
- * @m: An %IntegerMatrix
- * @i: column number to set
- * @j: row number to set
+ * \param m An \ref IntegerMatrix
+ * \param i column number to set
+ * \param j row number to set
  *
- * Gets the @i,@j element of @m.
+ * Gets the \p i,\p j element of \p m.
  *
- * Returns: the @i,@j element of @m.
+ * \returns The \p i,\p j element of \p m.
  **/
 signed int intmat_get(const IntegerMatrix *m, unsigned int i, unsigned int j)
 {
@@ -178,22 +170,21 @@ signed int intmat_get(const IntegerMatrix *m, unsigned int i, unsigned int j)
 
 
 /**
- * transform_indices:
- * @P: An %IntegerMatrix
- * @hkl: An array of signed integers
+ * \param P An \ref IntegerMatrix
+ * \param hkl An array of signed integers
  *
  * Apply transformation matrix P to a set of reciprocal space Miller indices.
  *
  * In other words:
- * Multiplies the matrix @P by the row vector @hkl.  The size of @vec must equal
- * the number of columns in @P, and the size of the result equals the number of
- * rows in @P.
+ * Multiplies the matrix \p P by the row vector \p hkl.  The size of \p vec must equal
+ * the number of columns in \p P, and the size of the result equals the number of
+ * rows in \p P.
  *
  * The multiplication looks like this:
  *    (a1, a2, a3) = (hkl1, hkl2, hkl3) P
  * Therefore matching the notation in ITA chapter 5.1.
  *
- * Returns: a newly allocated array of signed integers containing the answer,
+ * \returns A newly allocated array of signed integers containing the answer,
  * or NULL on error.
  **/
 signed int *transform_indices(const IntegerMatrix *P, const signed int *hkl)
@@ -219,13 +210,12 @@ signed int *transform_indices(const IntegerMatrix *P, const signed int *hkl)
 
 
 /**
- * intmat_intmat_mult:
- * @a: An %IntegerMatrix
- * @b: An %IntegerMatrix
+ * \param a An \ref IntegerMatrix
+ * \param b An \ref IntegerMatrix
  *
- * Multiplies the matrix @a by the matrix @b.
+ * Multiplies the matrix \p a by the matrix \p b.
  *
- * Returns: a newly allocated %IntegerMatrix containing the answer, or NULL on
+ * \returns A newly allocated \ref IntegerMatrix containing the answer, or NULL on
  * error.
  **/
 IntegerMatrix *intmat_intmat_mult(const IntegerMatrix *a,
@@ -307,12 +297,11 @@ static signed int cofactor(const IntegerMatrix *m,
 
 
 /**
- * intmat_det:
- * @m: An %IntegerMatrix
+ * \param m An \ref IntegerMatrix
  *
- * Calculates the determinant of @m.  Inefficiently.
+ * Calculates the determinant of \p m.  Inefficiently.
  *
- * Returns: the determinant of @m.
+ * \returns The determinant of \p m.
  **/
 signed int intmat_det(const IntegerMatrix *m)
 {
@@ -358,15 +347,14 @@ static IntegerMatrix *intmat_cofactors(const IntegerMatrix *m)
 
 
 /**
- * intmat_inverse:
- * @m: An %IntegerMatrix
+ * \param m An \ref IntegerMatrix
  *
- * Calculates the inverse of @m.  Inefficiently.
+ * Calculates the inverse of \p m.  Inefficiently.
  *
  * Works only if the inverse of the matrix is also an integer matrix,
- * i.e. if the determinant of @m is +/- 1.
+ * i.e. if the determinant of \p m is +/- 1.
  *
- * Returns: the inverse of @m, or NULL on error.
+ * \returns The inverse of \p m, or NULL on error.
  **/
 IntegerMatrix *intmat_inverse(const IntegerMatrix *m)
 {
@@ -409,10 +397,9 @@ IntegerMatrix *intmat_inverse(const IntegerMatrix *m)
 
 
 /**
- * intmat_print
- * @m: An %IntegerMatrix
+ * \param m An \ref IntegerMatrix
  *
- * Prints @m to stderr.
+ * Prints \param m to stderr.
  *
  */
 void intmat_print(const IntegerMatrix *m)
@@ -431,10 +418,9 @@ void intmat_print(const IntegerMatrix *m)
 
 
 /**
- * intmat_is_identity
- * @m: An %IntegerMatrix
+ * \param m An \ref IntegerMatrix
  *
- * Returns: true if @m is an identity matrix.
+ * \returns True if \p m is an identity matrix.
  *
  */
 int intmat_is_identity(const IntegerMatrix *m)
@@ -464,10 +450,9 @@ int intmat_is_identity(const IntegerMatrix *m)
 
 
 /**
- * intmat_is_inversion
- * @m: An %IntegerMatrix
+ * \param m An \ref IntegerMatrix
  *
- * Returns: true if @m = -I, where I is an identity matrix.
+ * \returns True if \p m = -I, where I is an identity matrix.
  *
  */
 int intmat_is_inversion(const IntegerMatrix *m)
@@ -497,11 +482,10 @@ int intmat_is_inversion(const IntegerMatrix *m)
 
 
 /**
- * intmat_equals
- * @a: An %IntegerMatrix
- * @b: An %IntegerMatrix
+ * \param a An \ref IntegerMatrix
+ * \param b An \ref IntegerMatrix
  *
- * Returns: true if @a = @b.
+ * \returns True if \p a = \p b.
  *
  */
 int intmat_equals(const IntegerMatrix *a, const IntegerMatrix *b)
@@ -528,10 +512,9 @@ int intmat_equals(const IntegerMatrix *a, const IntegerMatrix *b)
 
 
 /**
- * intmat_identity
- * @size: The size of the (square) matrix
+ * \param size The size of the (square) matrix
  *
- * Returns: an identity %IntegerMatrix with side length @size, or NULL on error.
+ * \returns An identity \ref IntegerMatrix with side length \p size, or NULL on error.
  *
  */
 IntegerMatrix *intmat_identity(int size)
@@ -559,11 +542,17 @@ IntegerMatrix *intmat_identity(int size)
 
 
 /**
- * intmat_set_all_3x3
- * @m: An %IntegerMatrix
- *
- * Returns: an identity %IntegerMatrix with side length @size, or NULL on error.
- *
+ * \param m11 Matrix element
+ * \param m12 Matrix element
+ * \param m13 Matrix element
+ * \param m21 Matrix element
+ * \param m22 Matrix element
+ * \param m23 Matrix element
+ * \param m31 Matrix element
+ * \param m32 Matrix element
+ * \param m33 Matrix element
+ *
+ * \returns A newly allocated 3x3 \ref IntegerMatrix with the given values.
  */
 IntegerMatrix *intmat_create_3x3(signed int m11, signed int m12, signed int m13,
                                  signed int m21, signed int m22, signed int m23,
diff --git a/libcrystfel/src/integer_matrix.h b/libcrystfel/src/integer_matrix.h
index fca6445d..dcbe63bc 100644
--- a/libcrystfel/src/integer_matrix.h
+++ b/libcrystfel/src/integer_matrix.h
@@ -34,9 +34,12 @@
 #endif
 
 /**
- * IntegerMatrix
- *
- * The IntegerMatrix is an opaque data structure representing an integer matrix.
+ * \file integer_matrix.h
+ * Matrix type containing only integers
+ */
+
+/**
+ * The \p IntegerMatrix is an opaque data structure representing an integer matrix.
  **/
 typedef struct _integermatrix IntegerMatrix;
 
diff --git a/libcrystfel/src/integration.c b/libcrystfel/src/integration.c
index 880ae87e..d9636d9f 100644
--- a/libcrystfel/src/integration.c
+++ b/libcrystfel/src/integration.c
@@ -54,6 +54,9 @@
 #include "integration.h"
 
 
+/** \file integration.h */
+
+
 enum boxmask_val
 {
 	BM_IG,  /* "Soft" ignore */
diff --git a/libcrystfel/src/integration.h b/libcrystfel/src/integration.h
index 3bf11ee8..7a230daf 100644
--- a/libcrystfel/src/integration.h
+++ b/libcrystfel/src/integration.h
@@ -36,30 +36,39 @@
 #include "geometry.h"
 
 /**
- * IntDiag:
- * @INTDIAG_NONE: Never show diagnostics
- * @INTDIAG_RANDOM: Show diagnostics for a randomly selected 1% of reflections
- * @INTDIAG_ALL: Show diagnostics for all reflections
- * @INTDIAG_INDICES: Show diagnostics when the Miller indices of the reflection
- *   are the ones specified
- * @INTDIAG_NEGATIVE: Show diagnostics when the measured intensity is less than
- *   minus three times its estimated error.
- * @INTDIAG_IMPLAUSIBLE: Show diagnostics when the measured intensity is les
- *   than minus five times its estimated error.
- * @INTDIAG_STRONG: Show diagnostics when the measured intensity is more than
- *   three times its estimated error.
- *
- * An %IntDiag describes the condition under which the integration subsystem
+ * \file integration.h
+ * Integration of reflections
+ */
+
+/**
+ * An IntDiag describes the condition under which the integration subsystem
  * should display diagnostic information to the user.
  **/
 typedef enum {
 
+	/** Never show diagnostics */
 	INTDIAG_NONE,
+
+	/** Show diagnostics for a randomly selected 1% of reflections */
 	INTDIAG_RANDOM,
+
+	/** Show diagnostics for all reflections */
 	INTDIAG_ALL,
+
+	/** Show diagnostics when the Miller indices of the reflection are the
+	 * ones specified */
 	INTDIAG_INDICES,
+
+	/** Show diagnostics when the measured intensity is less than minus
+	 * three times its estimated error. */
 	INTDIAG_NEGATIVE,
+
+	/** Show diagnostics when the measured intensity is less than minus five
+	 * times its estimated error. */
 	INTDIAG_IMPLAUSIBLE,
+
+	/** Show diagnostics when the measured intensity is more than three
+	 * times its estimated error. */
 	INTDIAG_STRONG
 
 } IntDiag;
@@ -68,36 +77,37 @@ typedef enum {
 #define INTEGRATION_DEFAULTS_PROF2D (INTEGRATION_PROF2D | INTEGRATION_CENTER)
 
 /**
- * IntegrationMethod:
- * @INTEGRATION_NONE: No integration at all
- * @INTEGRATION_RINGS: Summation of pixel values inside ring, minus background
- * @INTEGRATION_PROF2D: Two dimensional profile fitting
- * @INTEGRATION_SATURATED: Integrate saturated reflections
- * @INTEGRATION_CENTER: Center the peak in the box prior to integration
- * @INTEGRATION_RESCUT: Stop integrating at the diffraction limit of the crystal
- * @INTEGRATION_GRADIENTBG: Fit a gradient to the background
- *
- * An enumeration of all the available integration methods.
- **/
+ * An enumeration of all the available integration methods.  The first items
+ * are the actual integration methods.  The later ones are flags which can be
+ * ORed with the method to affect its behaviour.
+ */
 typedef enum {
 
+	/** No integration at all */
 	INTEGRATION_NONE   = 0,
 
-	/* The core integration methods themselves */
+	/** Summation of pixel values inside ring, minus background */
 	INTEGRATION_RINGS  = 1,
+
+	/** Two dimensional profile fitting */
 	INTEGRATION_PROF2D = 2,
 
-	/* Bits at the top of the IntegrationMethod are flags which modify the
-	 * behaviour of the integration. */
+	/** Integrate saturated reflections */
 	INTEGRATION_SATURATED = 256,
+
+	/** Center the peak in the box prior to integration */
 	INTEGRATION_CENTER = 512,
+
+	/** Stop integrating at the diffraction limit of the crystal */
 	INTEGRATION_RESCUT = 1024,
+
+	/** Fit a gradient to the background */
 	INTEGRATION_GRADIENTBG = 2048,
 
 } IntegrationMethod;
 
-/* This defines the bits in "IntegrationMethod" which are used to represent the
- * core of the integration method */
+/** This defines the bits in \ref IntegrationMethod which are used to represent the
+ * core of the integration method. */
 #define INTEGRATION_METHOD_MASK (0xff)
 
 #ifdef __cplusplus
diff --git a/libcrystfel/src/mosflm.c b/libcrystfel/src/mosflm.c
index d48dcef2..10ca49ec 100644
--- a/libcrystfel/src/mosflm.c
+++ b/libcrystfel/src/mosflm.c
@@ -90,6 +90,7 @@
 #include "peaks.h"
 #include "cell-utils.h"
 
+/** \file mosflm.h */
 
 #define MOSFLM_VERBOSE 0
 #define FAKE_CLEN (0.1)
diff --git a/libcrystfel/src/mosflm.h b/libcrystfel/src/mosflm.h
index 9339b856..d39f0854 100644
--- a/libcrystfel/src/mosflm.h
+++ b/libcrystfel/src/mosflm.h
@@ -41,6 +41,11 @@
 extern "C" {
 #endif
 
+/**
+ * \file mosflm.h
+ * MOSFLM indexer interface
+ */
+
 extern int run_mosflm(struct image *image, void *ipriv);
 
 extern void *mosflm_prepare(IndexingMethod *indm, UnitCell *cell);
diff --git a/libcrystfel/src/peakfinder8.c b/libcrystfel/src/peakfinder8.c
index 9090d48f..2c67a484 100644
--- a/libcrystfel/src/peakfinder8.c
+++ b/libcrystfel/src/peakfinder8.c
@@ -39,6 +39,8 @@
 #include "peakfinder8.h"
 
 
+/** \file peakfinder8.h */
+
 // CrystFEL-only block 1
 struct radius_maps
 {
@@ -1003,6 +1005,20 @@ static int peakfinder8_base(float *roffset, float *rthreshold,
 }
 
 
+/**
+ * \param img An \ref image structure
+ * \param max_n_peaks The maximum number of peaks to be searched for
+ * \param threshold The image threshold value, in detector units
+ * \param min_snr The minimum signal to noise ratio for a peak
+ * \param min_pix_count The minimum number of pixels in a peak
+ * \param max_pix_count The maximum number of pixels in a peak
+ * \param local_bg_radius The averaging radius for background calculation
+ * \param min_res The minimum number of pixels out from the center
+ * \param max_res The maximum number of pixels out from the center
+ * \param use_saturated Whether saturated peaks should be considered
+ *
+ * Runs the peakfinder8 peak search algorithm
+ */
 int peakfinder8(struct image *img, int max_n_peaks,
                 float threshold, float min_snr,
                 int min_pix_count, int max_pix_count,
diff --git a/libcrystfel/src/peakfinder8.h b/libcrystfel/src/peakfinder8.h
index 483eebdf..e25cf0ec 100644
--- a/libcrystfel/src/peakfinder8.h
+++ b/libcrystfel/src/peakfinder8.h
@@ -37,6 +37,11 @@
 extern "C" {
 #endif
 
+/**
+ * \file peakfinder8.h
+ * The "peakfinder8" peak search algorithm, originally implemented in Cheetah
+ */
+
 extern int peakfinder8(struct image *img, int max_n_peaks,
                        float threshold, float min_snr,
                        int mix_pix_count, int max_pix_count,
diff --git a/libcrystfel/src/peaks.c b/libcrystfel/src/peaks.c
index 49e09868..f5ce8486 100644
--- a/libcrystfel/src/peaks.c
+++ b/libcrystfel/src/peaks.c
@@ -62,6 +62,7 @@
 #include "geometry.h"
 #include "peakfinder8.h"
 
+/** \file peaks.h */
 
 static int cull_peaks_in_panel(struct image *image, struct panel *p)
 {
diff --git a/libcrystfel/src/peaks.h b/libcrystfel/src/peaks.h
index a82d8d25..b08defcd 100644
--- a/libcrystfel/src/peaks.h
+++ b/libcrystfel/src/peaks.h
@@ -44,6 +44,11 @@
 extern "C" {
 #endif
 
+/**
+ * \file peaks.h
+ * Peak search functions
+ */
+
 extern int *make_BgMask(struct image *image, struct panel *p, double ir_inn);
 
 extern void search_peaks(struct image *image, float threshold,
diff --git a/libcrystfel/src/predict-refine.c b/libcrystfel/src/predict-refine.c
index 6b151d48..11f4b630 100644
--- a/libcrystfel/src/predict-refine.c
+++ b/libcrystfel/src/predict-refine.c
@@ -42,6 +42,9 @@
 #include "cell-utils.h"
 
 
+/** \file predict-refine.h */
+
+
 /* Maximum number of iterations of NLSq to do for each image per macrocycle. */
 #define MAX_CYCLES (10)
 
diff --git a/libcrystfel/src/predict-refine.h b/libcrystfel/src/predict-refine.h
index fe700f47..5b3c05e1 100644
--- a/libcrystfel/src/predict-refine.h
+++ b/libcrystfel/src/predict-refine.h
@@ -38,6 +38,11 @@
 
 struct image;
 
+/**
+ * \file predict-refine.h
+ * Prediction refinement: refinement of indexing solutions before integration.
+ */
+
 extern int refine_prediction(struct image *image, Crystal *cr);
 extern int refine_radius(Crystal *cr, struct image *image);
 
diff --git a/libcrystfel/src/rational.c b/libcrystfel/src/rational.c
index 65b209ff..5138c3e9 100644
--- a/libcrystfel/src/rational.c
+++ b/libcrystfel/src/rational.c
@@ -40,19 +40,7 @@
 #include "integer_matrix.h"
 #include "utils.h"
 
-
-/**
- * SECTION:rational
- * @short_description: Rational numbers
- * @title: Rational numbers
- * @section_id:
- * @see_also:
- * @include: "rational.h"
- * @Image:
- *
- * A rational number library
- */
-
+/** \file rational.h */
 
 /* Eucliden algorithm for finding greatest common divisor */
 static signed int gcd(signed int a, signed int b)
@@ -206,12 +194,11 @@ Rational rtnl_abs(Rational a)
 
 
 /**
- * rtnl_format
- * @rt: A %Rational
+ * \param rt A \ref Rational
  *
- * Formats @rt as a string
+ * Formats \p rt as a string
  *
- * Returns: a string which should be freed by the caller
+ * \returns A string which should be freed by the caller
  */
 char *rtnl_format(Rational rt)
 {
@@ -259,19 +246,6 @@ Rational *rtnl_list(signed int num_min, signed int num_max,
 }
 
 
-/**
- * SECTION:rational_matrix
- * @short_description: Rational matrices
- * @title: Rational matrices
- * @section_id:
- * @see_also:
- * @include: "rational.h"
- * @Image:
- *
- * A rational matrix library
- */
-
-
 struct _rationalmatrix
 {
 	unsigned int rows;
@@ -281,13 +255,12 @@ struct _rationalmatrix
 
 
 /**
- * rtnl_mtx_new:
- * @rows: Number of rows that the new matrix is to have
- * @cols: Number of columns that the new matrix is to have
+ * \param rows Number of rows that the new matrix is to have
+ * \param cols Number of columns that the new matrix is to have
  *
- * Allocates a new %RationalMatrix with all elements set to zero.
+ * Allocates a new \ref RationalMatrix with all elements set to zero.
  *
- * Returns: a new %RationalMatrix, or NULL on error.
+ * \returns A new \ref RationalMatrix, or NULL on error.
  **/
 RationalMatrix *rtnl_mtx_new(unsigned int rows, unsigned int cols)
 {
@@ -528,10 +501,9 @@ int transform_fractional_coords_rtnl(const RationalMatrix *P,
 
 
 /**
- * rtnl_mtx_print
- * @m: A %RationalMatrix
+ * \param m A \ref RationalMatrix
  *
- * Prints @m to stderr.
+ * Prints \p m to stderr.
  *
  */
 void rtnl_mtx_print(const RationalMatrix *m)
diff --git a/libcrystfel/src/rational.h b/libcrystfel/src/rational.h
index 23c918cf..e67c603a 100644
--- a/libcrystfel/src/rational.h
+++ b/libcrystfel/src/rational.h
@@ -34,8 +34,11 @@
 #endif
 
 /**
- * Rational
- *
+ * \file rational.h
+ * %Rational numbers (including rational matrices)
+ */
+
+/**
  * The Rational is an opaque-ish data structure representing a rational number.
  *
  * "Opaque-ish" means that the structure isn't technically opaque, allowing you
@@ -50,8 +53,6 @@ typedef struct {
 
 
 /**
- * RationalMatrix
- *
  * The RationalMatrix is an opaque data structure representing a matrix of
  * rational numbers.
  **/
diff --git a/libcrystfel/src/reflist-utils.c b/libcrystfel/src/reflist-utils.c
index 70548994..d514990a 100644
--- a/libcrystfel/src/reflist-utils.c
+++ b/libcrystfel/src/reflist-utils.c
@@ -43,19 +43,18 @@
 #include "symmetry.h"
 
 
-/**
- * SECTION:reflist-utils
- * @short_description: Reflection list utilities
- * @title: RefList utilities
- * @section_id:
- * @see_also:
- * @include: "reflist-utils.h"
- * @Image:
- *
- * There are some utility functions associated with the core %RefList.
- **/
+/** \file reflist-utils.h
+ */
 
 
+/**
+ * Checks that the symmetry of \p list is indeed \p sym.
+ *
+ * \param list A list of reflections
+ * \param sym Symmetry of the reflection list
+ *
+ * \returns 0 if the symmetry is correct, otherwise 1
+ */
 int check_list_symmetry(RefList *list, const SymOpList *sym)
 {
 	Reflection *refl;
@@ -155,7 +154,7 @@ int find_equiv_in_list(RefList *list, signed int h, signed int k,
 }
 
 
-/**
+/*
  * Write the actual reflections to the file, no headers etc.
  * Reflections which have a redundancy of zero will not be written.
  * The resulting list can be read back with read_reflections_from_file().
@@ -202,19 +201,18 @@ static void write_reflections_to_file(FILE *fh, RefList *list)
 
 
 /**
- * write_reflist_2:
- * @filename: Filename
- * @list: The reflection list to write
- * @sym: A %SymOpList describing the symmetry of the list
- *
- * This function writes the contents of @list to @file,
+ * This function writes the contents of list to file,
  *
  * Reflections which have a redundancy of zero will not be written.
  *
  * The resulting list can be read back with read_reflections_from_file() or
  * read_reflections().
  *
- * Returns: zero on success, non-zero on failure.
+ * \param filename Filename
+ * \param list The reflection list to write
+ * \param sym A %SymOpList describing the symmetry of the list
+ *
+ * \returns zero on success, non-zero on failure.
  **/
 int write_reflist_2(const char *filename, RefList *list, SymOpList *sym)
 {
@@ -255,23 +253,22 @@ int write_reflist_2(const char *filename, RefList *list, SymOpList *sym)
 
 
 /**
- * write_reflist:
- * @filename: Filename
- * @list: The reflection list to write
- *
- * This function writes the contents of @list to @file,
+ * This function writes the contents of list to file,
  *
  * Reflections which have a redundancy of zero will not be written.
  *
  * The resulting list can be read back with read_reflections_from_file() or
  * read_reflections().
  *
- * This is a convenience function which simply opens @filename and then calls
+ * This is a convenience function which simply opens filename and then calls
  * write_reflections_to_file.
  *
- * Deprecated: use write_reflist_2() instead.
+ * \deprecated Use write_reflist_2() instead.
+ *
+ * \param filename Filename
+ * \param list The reflection list to write
  *
- * Returns: zero on success, non-zero on failure.
+ * \returns Zero on success, non-zero on failure.
  **/
 int write_reflist(const char *filename, RefList *list)
 {
@@ -422,8 +419,8 @@ static RefList *read_reflections_from_file(FILE *fh, char **sym)
 
 /**
  * read_reflections_2:
- * @filename: Filename to read from
- * @sym: Pointer to a "char *" at which to store the symmetry
+ * \param filename: Filename to read from
+ * \param sym: Pointer to a "char *" at which to store the symmetry
  *
  * This function reads a reflection list from a file, including the
  * symmetry from the header (e.g. "Symmetry: 4/mmm").
@@ -456,7 +453,7 @@ RefList *read_reflections_2(const char *filename, char **sym)
 
 /**
  * read_reflections:
- * @filename: Filename to read from
+ * \param filename: Filename to read from
  *
  * This function reads a reflection list from a file.
  *
@@ -470,11 +467,11 @@ RefList *read_reflections(const char *filename)
 
 /**
  * asymmetric_indices:
- * @in: A %RefList
- * @sym: A %SymOpList
+ * \param in: A %RefList
+ * \param sym: A %SymOpList
  *
- * This function creates a newly allocated copy of @in, but indexed using the
- * asymmetric indices according to @sym instead of the original indices.  The
+ * This function creates a newly allocated copy of in, but indexed using the
+ * asymmetric indices according to sym instead of the original indices.  The
  * original indices are stored and can be retrieved using
  * get_symmetric_indices() if required.
  *
@@ -515,10 +512,10 @@ RefList *asymmetric_indices(RefList *in, const SymOpList *sym)
 
 /**
  * resolution_limits:
- * @list: A %RefList
- * @cell: A %UnitCell
- * @rmin: Place to store the minimum 1/d value
- * @rmax: Place to store the maximum 1/d value
+ * \param list: A %RefList
+ * \param cell: A %UnitCell
+ * \param rmin: Place to store the minimum 1/d value
+ * \param rmax: Place to store the maximum 1/d value
  *
  * This function calculates the minimum and maximum values of 1/d, where
  * 2dsin(theta) = wavelength.  The answers are in m^-1.
@@ -550,9 +547,9 @@ void resolution_limits(RefList *list, UnitCell *cell,
 
 /**
  * max_intensity:
- * @list: A %RefList
+ * \param list: A %RefList
  *
- * Returns: The maximum intensity in @list.
+ * Returns: The maximum intensity in \p list.
  **/
 double max_intensity(RefList *list)
 {
@@ -576,12 +573,12 @@ double max_intensity(RefList *list)
 
 /**
  * res_cutoff:
- * @list: A %RefList
- * @cell: A %UnitCell with which to calculate 1/d values for @list
- * @min: Minimum acceptable value of 1/d
- * @max: Maximum acceptable value of 1/d
+ * \param list: A %RefList
+ * \param cell: A %UnitCell with which to calculate 1/d values for \p list
+ * \param min: Minimum acceptable value of 1/d
+ * \param max: Maximum acceptable value of 1/d
  *
- * Applies a resolution cutoff to @list, returning the new version and freeing
+ * Applies a resolution cutoff to \p list, returning the new version and freeing
  * the old version.
  *
  * Returns: A new %RefList with resolution cutoff applied
@@ -619,7 +616,7 @@ RefList *res_cutoff(RefList *list, UnitCell *cell, double min, double max)
 
 /**
  * copy_reflist:
- * @list: A %RefList
+ * \param list: A %RefList
  *
  * Returns: A copy of %RefList.
  **/
@@ -650,9 +647,9 @@ RefList *copy_reflist(RefList *list)
 
 /**
  * free_contribs:
- * @list: A %RefList
+ * \param list: A %RefList
  *
- * Goes through @list and frees all the reflection contribution structures.
+ * Goes through \p list and frees all the reflection contribution structures.
  **/
 void free_contribs(RefList *list)
 {
diff --git a/libcrystfel/src/reflist-utils.h b/libcrystfel/src/reflist-utils.h
index c955491a..68695ae2 100644
--- a/libcrystfel/src/reflist-utils.h
+++ b/libcrystfel/src/reflist-utils.h
@@ -31,8 +31,10 @@
 #include <config.h>
 #endif
 
+/** @cond */
 #ifndef REFLIST_UTILS_H
 #define REFLIST_UTILS_H
+/** @endcond */
 
 #include "image.h"
 #include "reflist.h"
@@ -43,8 +45,15 @@
 extern "C" {
 #endif
 
-#define REFLECTION_END_MARKER "End of reflections"
+/** \file reflist-utils.h
+ *
+ * Reflection list utility functions.
+ */
 
+/** @cond
+ * Used in stream.c as well, but not part of the API */
+#define REFLECTION_END_MARKER "End of reflections"
+/** @endcond */
 
 extern int write_reflist(const char *filename, RefList *list);
 extern int write_reflist_2(const char *filename, RefList *list, SymOpList *sym);
@@ -78,4 +87,6 @@ extern void reflist_add_command_and_version(RefList *list,
 }
 #endif
 
+/** @cond */
 #endif	/* REFLIST_UTILS_H */
+/** @endcond */
diff --git a/libcrystfel/src/reflist.c b/libcrystfel/src/reflist.c
index 9c8a6a14..ee601018 100644
--- a/libcrystfel/src/reflist.c
+++ b/libcrystfel/src/reflist.c
@@ -34,30 +34,7 @@
 #include "reflist.h"
 #include "utils.h"
 
-/**
- * SECTION:reflist
- * @short_description: The fast reflection list
- * @title: RefList
- * @section_id:
- * @see_also:
- * @include: "reflist.h"
- * @Image:
- *
- * The fast reflection list stores reflections in an RB-tree indexed
- * by the Miller indices h, k and l.  Any reflection can be found in a
- * length of time which scales logarithmically with the number of reflections in
- * the list.
- *
- * A RefList can contain any number of reflections, and can store more than
- * one reflection with a given set of indices, for example when two distinct
- * reflections are to be stored according to their asymmetric indices.
- *
- * There are getters and setters which can be used to get and set values for an
- * individual reflection.  The reflection list does not calculate any values,
- * only stores what it was given earlier.  As such, you will need to carefully
- * examine which fields your prior processing steps have filled in.
- */
-
+/** \file reflist.h */
 
 struct _refldata {
 
@@ -160,11 +137,9 @@ static Reflection *new_node(unsigned int serial)
 
 
 /**
- * reflist_new:
- *
  * Creates a new reflection list.
  *
- * Returns: the new reflection list, or NULL on error.
+ * \returns the new reflection list, or NULL on error.
  */
 RefList *reflist_new()
 {
@@ -181,10 +156,9 @@ RefList *reflist_new()
 
 
 /**
- * reflection_new:
- * @h: The h index of the new reflection
- * @k: The k index of the new reflection
- * @l: The l index of the new reflection
+ * \param h The h index of the new reflection
+ * \param k The k index of the new reflection
+ * \param l The l index of the new reflection
  *
  * Creates a new individual reflection.  You'll probably want to use
  * add_refl_to_list() at some later point.
@@ -196,8 +170,7 @@ Reflection *reflection_new(signed int h, signed int k, signed int l)
 
 
 /**
- * reflection_free:
- * @refl: The reflection to free.
+ * \param refl: The reflection to free.
  *
  * Destroys an individual reflection.
  */
@@ -222,8 +195,7 @@ static void recursive_free(Reflection *refl)
 
 
 /**
- * reflist_free:
- * @list: The reflection list to free.
+ * \param list: The reflection list to free.
  *
  * Destroys a reflection list.
  */
@@ -241,18 +213,17 @@ void reflist_free(RefList *list)
 /********************************** Search ************************************/
 
 /**
- * find_refl:
- * @list: The reflection list to search in
- * @h: The 'h' index to search for
- * @k: The 'k' index to search for
- * @l: The 'l' index to search for
+ * \param list: The reflection list to search in
+ * \param h: The 'h' index to search for
+ * \param k: The 'k' index to search for
+ * \param l: The 'l' index to search for
  *
  * This function finds the first reflection in 'list' with the given indices.
  *
  * Since a %RefList can contain multiple reflections with the same indices, you
  * may need to use next_found_refl() to get the other reflections.
  *
- * Returns: The found reflection, or NULL if no reflection with the given
+ * \returns The found reflection, or NULL if no reflection with the given
  * indices could be found.
  **/
 Reflection *find_refl(const RefList *list,
@@ -302,13 +273,12 @@ Reflection *find_refl(const RefList *list,
 
 
 /**
- * next_found_refl:
- * @refl: A reflection returned by find_refl() or next_found_refl()
+ * \param refl: A reflection returned by find_refl() or next_found_refl()
  *
- * This function returns the next reflection in @refl's list with the same
+ * This function returns the next reflection in \p refl's list with the same
  * indices.
  *
- * Returns: The found reflection, or NULL if there are no more reflections with
+ * \returns The found reflection, or NULL if there are no more reflections with
  * the same indices.
  **/
 Reflection *next_found_refl(Reflection *refl)
@@ -323,10 +293,9 @@ Reflection *next_found_refl(Reflection *refl)
 
 
 /**
- * get_detector_pos:
- * @refl: A %Reflection
- * @fs: Location at which to store the fast scan offset of the reflection
- * @ss: Location at which to store the slow scan offset of the reflection
+ * \param refl: Reflection
+ * \param fs: Location at which to store the fast scan offset of the reflection
+ * \param ss: Location at which to store the slow scan offset of the reflection
  *
  **/
 void get_detector_pos(const Reflection *refl, double *fs, double *ss)
@@ -337,10 +306,9 @@ void get_detector_pos(const Reflection *refl, double *fs, double *ss)
 
 
 /**
- * get_panel:
- * @refl: A %Reflection
+ * \param refl: Reflection
  *
- * Returns: the panel which the reflection appears on
+ * \returns the panel which the reflection appears on
  *
  **/
 struct panel *get_panel(const Reflection *refl)
@@ -350,11 +318,10 @@ struct panel *get_panel(const Reflection *refl)
 
 
 /**
- * get_indices:
- * @refl: A %Reflection
- * @h: Location at which to store the 'h' index of the reflection
- * @k: Location at which to store the 'k' index of the reflection
- * @l: Location at which to store the 'l' index of the reflection
+ * \param refl: Reflection
+ * \param h: Location at which to store the 'h' index of the reflection
+ * \param k: Location at which to store the 'k' index of the reflection
+ * \param l: Location at which to store the 'l' index of the reflection
  *
  **/
 void get_indices(const Reflection *refl,
@@ -367,11 +334,10 @@ void get_indices(const Reflection *refl,
 
 
 /**
- * get_symmetric_indices:
- * @refl: A %Reflection
- * @hs: Location at which to store the 'h' index of the reflection
- * @ks: Location at which to store the 'k' index of the reflection
- * @ls: Location at which to store the 'l' index of the reflection
+ * \param refl: Reflection
+ * \param hs: Location at which to store the 'h' index of the reflection
+ * \param ks: Location at which to store the 'k' index of the reflection
+ * \param ls: Location at which to store the 'l' index of the reflection
  *
  * This function gives the symmetric indices, that is, the "real" indices before
  * squashing down to the asymmetric reciprocal unit.  This may be useful if the
@@ -390,10 +356,9 @@ void get_symmetric_indices(const Reflection *refl,
 
 
 /**
- * get_partiality:
- * @refl: A %Reflection
+ * \param refl: Reflection
  *
- * Returns: The partiality of the reflection.  See get_lorentz().
+ * \returns The partiality of the reflection.  See get_lorentz().
  **/
 double get_partiality(const Reflection *refl)
 {
@@ -402,10 +367,9 @@ double get_partiality(const Reflection *refl)
 
 
 /**
- * get_lorentz:
- * @refl: A %Reflection
+ * \param refl: Reflection
  *
- * Returns: The Lorentz factor for the reflection.  To "scale up" a partial
+ * \returns The Lorentz factor for the reflection.  To "scale up" a partial
  * reflection, divide by this multiplied by the partiality.
  **/
 double get_lorentz(const Reflection *refl)
@@ -415,10 +379,9 @@ double get_lorentz(const Reflection *refl)
 
 
 /**
- * get_intensity:
- * @refl: A %Reflection
+ * \param refl: Reflection
  *
- * Returns: The intensity of the reflection.
+ * \returns The intensity of the reflection.
  **/
 double get_intensity(const Reflection *refl)
 {
@@ -428,9 +391,9 @@ double get_intensity(const Reflection *refl)
 
 /**
  * get_khalf
- * @refl: A %Reflection
+ * \param refl: Reflection
  *
- * Returns: the wavenumber at the centre of the reflection
+ * \returns the wavenumber at the centre of the reflection
  *
  **/
 double get_khalf(const Reflection *refl)
@@ -442,10 +405,9 @@ double get_khalf(const Reflection *refl)
 
 
 /**
- * get_kpred:
- * @refl: A %Reflection
+ * \param refl: Reflection
  *
- * Returns: the wavenumber which should be used for prediction of this reflection
+ * \returns the wavenumber which should be used for prediction of this reflection
  *
  **/
 double get_kpred(const Reflection *refl)
@@ -455,10 +417,9 @@ double get_kpred(const Reflection *refl)
 
 
 /**
- * get_exerr:
- * @refl: A %Reflection
+ * \param refl: Reflection
  *
- * Returns: the excitation error (in m^-1) for this reflection
+ * \returns the excitation error (in m^-1) for this reflection
  *
  **/
 double get_exerr(const Reflection *refl)
@@ -468,8 +429,7 @@ double get_exerr(const Reflection *refl)
 
 
 /**
- * get_redundancy:
- * @refl: A %Reflection
+ * \param refl: Reflection
  *
  * The redundancy of the reflection is the number of measurements that have been
  * made of it.  Note that a redundancy of zero may have a special meaning, such
@@ -478,7 +438,7 @@ double get_exerr(const Reflection *refl)
  * copies of the reflection in the list.  The total number of reflection
  * measurements should always be the sum of the redundancies in the entire list.
  *
- * Returns: the number of measurements of this reflection.
+ * \returns the number of measurements of this reflection.
  *
  **/
 int get_redundancy(const Reflection *refl)
@@ -488,10 +448,9 @@ int get_redundancy(const Reflection *refl)
 
 
 /**
- * get_esd_intensity:
- * @refl: A %Reflection
+ * \param refl: Reflection
  *
- * Returns: the standard error in the intensity measurement (as returned by
+ * \returns the standard error in the intensity measurement (as returned by
  * get_intensity()) for this reflection.
  *
  **/
@@ -502,11 +461,10 @@ double get_esd_intensity(const Reflection *refl)
 
 
 /**
- * get_phase:
- * @refl: A %Reflection
- * @have_phase: Place to store a non-zero value if the phase is set, or NULL.
+ * \param refl: Reflection
+ * \param have_phase: Place to store a non-zero value if the phase is set, or NULL.
  *
- * Returns: the phase for this reflection.
+ * \returns the phase for this reflection.
  *
  **/
 double get_phase(const Reflection *refl, int *have_phase)
@@ -517,10 +475,9 @@ double get_phase(const Reflection *refl, int *have_phase)
 
 
 /**
- * get_peak:
- * @refl: A %Reflection
+ * \param refl: Reflection
  *
- * Returns: the peak height (value of the highest pixel, before background
+ * \returns the peak height (value of the highest pixel, before background
  * subtraction) for this reflection.
  *
  **/
@@ -531,10 +488,9 @@ double get_peak(const Reflection *refl)
 
 
 /**
- * get_mean_bg:
- * @refl: A %Reflection
+ * \param refl: Reflection
  *
- * Returns: the mean background level for this reflection.
+ * \returns the mean background level for this reflection.
  *
  **/
 double get_mean_bg(const Reflection *refl)
@@ -544,13 +500,12 @@ double get_mean_bg(const Reflection *refl)
 
 
 /**
- * get_temp1:
- * @refl: A %Reflection
+ * \param refl: Reflection
  *
  * The temporary values can be used according to the needs of the calling
  * program.
  *
- * Returns: the first temporary value for this reflection.
+ * \returns the first temporary value for this reflection.
  *
  **/
 double get_temp1(const Reflection *refl)
@@ -560,13 +515,12 @@ double get_temp1(const Reflection *refl)
 
 
 /**
- * get_temp2:
- * @refl: A %Reflection
+ * \param refl: Reflection
  *
  * The temporary values can be used according to the needs of the calling
  * program.
  *
- * Returns: the second temporary value for this reflection.
+ * \returns the second temporary value for this reflection.
  *
  **/
 double get_temp2(const Reflection *refl)
@@ -576,13 +530,12 @@ double get_temp2(const Reflection *refl)
 
 
 /**
- * get_flag:
- * @refl: A %Reflection
+ * \param refl: Reflection
  *
  * The integer flag value can be used according to the needs of the calling
  * program.
  *
- * Returns: the flag for this reflection.
+ * \returns the flag for this reflection.
  *
  **/
 int get_flag(const Reflection *refl)
@@ -592,10 +545,9 @@ int get_flag(const Reflection *refl)
 
 
 /**
- * get_contributions:
- * @refl: A %Reflection
+ * \param refl: Reflection
  *
- * Returns: the reflection's contribution list
+ * \returns the reflection's contribution list
  *
  **/
 struct reflection_contributions *get_contributions(const Reflection *refl)
@@ -606,9 +558,8 @@ struct reflection_contributions *get_contributions(const Reflection *refl)
 /********************************** Setters ***********************************/
 
 /**
- * copy_data:
- * @to: %Reflection to copy data into
- * @from: %Reflection to copy data from
+ * \param to: %Reflection to copy data into
+ * \param from: %Reflection to copy data from
  *
  * This function is used to copy the data (which is everything listed above in
  * the list of getters and setters, apart from the indices themselves) from one
@@ -624,10 +575,9 @@ void copy_data(Reflection *to, const Reflection *from)
 
 
 /**
- * set_detector_pos:
- * @refl: A %Reflection
- * @fs: The fast scan offset of the reflection
- * @ss: The slow scan offset of the reflection
+ * \param refl: Reflection
+ * \param fs: The fast scan offset of the reflection
+ * \param ss: The slow scan offset of the reflection
  *
  **/
 void set_detector_pos(Reflection *refl, double fs, double ss)
@@ -638,9 +588,8 @@ void set_detector_pos(Reflection *refl, double fs, double ss)
 
 
 /**
- * set_panel:
- * @refl: A %Reflection
- * @p: Pointer to the panel structure on which the reflection appears
+ * \param refl: Reflection
+ * \param p: Pointer to the panel structure on which the reflection appears
  *
  * Note that the pointer will be stored, not the contents of the structure.
  *
@@ -652,9 +601,8 @@ void set_panel(Reflection *refl, struct panel *p)
 
 
 /**
- * set_khalf:
- * @refl: A %Reflection
- * @khalf: The wavenumber at which the reflection should be predicted
+ * \param refl: Reflection
+ * \param khalf: The wavenumber at which the reflection should be predicted
  *
  * Sets the wavenumber at the centre of the reflection.
  **/
@@ -665,9 +613,8 @@ void set_khalf(Reflection *refl, double khalf)
 
 
 /**
- * set_kpred:
- * @refl: A %Reflection
- * @kpred: The wavenumber at which the reflection should be predicted
+ * \param refl: Reflection
+ * \param kpred: The wavenumber at which the reflection should be predicted
  *
  * Sets the wavenumber at which the reflection should be predicted.
  * Used by predict_to_res() and update_predictions()
@@ -679,9 +626,8 @@ void set_kpred(Reflection *refl, double kpred)
 
 
 /**
- * set_exerr:
- * @refl: A %Reflection
- * @exerr: The excitation error for the reflection
+ * \param refl: Reflection
+ * \param exerr: The excitation error for the reflection
  *
  **/
 void set_exerr(Reflection *refl, double exerr)
@@ -691,9 +637,8 @@ void set_exerr(Reflection *refl, double exerr)
 
 
 /**
- * set_intensity:
- * @refl: A %Reflection
- * @p: The partiality for the reflection.
+ * \param refl: Reflection
+ * \param p: The partiality for the reflection.
  *
  * Set the partiality for the reflection.  See set_lorentz().
  **/
@@ -703,9 +648,8 @@ void set_partiality(Reflection *refl, double p)
 }
 
 /**
- * set_lorentz:
- * @refl: A %Reflection
- * @L: The Lorentz factor for the reflection.
+ * \param refl: Reflection
+ * \param L: The Lorentz factor for the reflection.
  *
  * Set the Lorentz factor for the reflection.  To "scale up" a partial
  * reflection, divide by this multiplied by the partiality.
@@ -717,9 +661,8 @@ void set_lorentz(Reflection *refl, double L)
 
 
 /**
- * set_intensity:
- * @refl: A %Reflection
- * @intensity: The intensity for the reflection.
+ * \param refl: Reflection
+ * \param intensity: The intensity for the reflection.
  *
  * Set the intensity for the reflection.
  **/
@@ -730,9 +673,8 @@ void set_intensity(Reflection *refl, double intensity)
 
 
 /**
- * set_redundancy:
- * @refl: A %Reflection
- * @red: New redundancy for the reflection
+ * \param refl: Reflection
+ * \param red: New redundancy for the reflection
  *
  * The redundancy of the reflection is the number of measurements that have been
  * made of it.  Note that a redundancy of zero may have a special meaning, such
@@ -749,9 +691,8 @@ void set_redundancy(Reflection *refl, int red)
 
 
 /**
- * set_esd_intensity:
- * @refl: A %Reflection
- * @esd: New standard error for this reflection's intensity measurement
+ * \param refl: Reflection
+ * \param esd: New standard error for this reflection's intensity measurement
  *
  **/
 void set_esd_intensity(Reflection *refl, double esd)
@@ -761,9 +702,8 @@ void set_esd_intensity(Reflection *refl, double esd)
 
 
 /**
- * set_phase:
- * @refl: A %Reflection
- * @phase: New phase for the reflection
+ * \param refl: Reflection
+ * \param phase: New phase for the reflection
  *
  **/
 void set_phase(Reflection *refl, double phase)
@@ -774,9 +714,8 @@ void set_phase(Reflection *refl, double phase)
 
 
 /**
- * set_peak:
- * @refl: A %Reflection
- * @peak: New peak height for the reflection
+ * \param refl: Reflection
+ * \param peak: New peak height for the reflection
  *
  **/
 void set_peak(Reflection *refl, double peak)
@@ -786,9 +725,8 @@ void set_peak(Reflection *refl, double peak)
 
 
 /**
- * set_mean_bg:
- * @refl: A %Reflection
- * @mean_bg: New peak height for the reflection
+ * \param refl: Reflection
+ * \param mean_bg: New peak height for the reflection
  *
  **/
 void set_mean_bg(Reflection *refl, double mean_bg)
@@ -798,11 +736,10 @@ void set_mean_bg(Reflection *refl, double mean_bg)
 
 
 /**
- * set_symmetric_indices:
- * @refl: A %Reflection
- * @hs: The 'h' index of the reflection
- * @ks: The 'k' index of the reflection
- * @ls: The 'l' index of the reflection
+ * \param refl: Reflection
+ * \param hs: The 'h' index of the reflection
+ * \param ks: The 'k' index of the reflection
+ * \param ls: The 'l' index of the reflection
  *
  * This function gives the symmetric indices, that is, the "real" indices before
  * squashing down to the asymmetric reciprocal unit.  This may be useful if the
@@ -820,9 +757,8 @@ void set_symmetric_indices(Reflection *refl,
 
 
 /**
- * set_temp1
- * @refl: A %Reflection
- * @temp: New temporary value for the reflection
+ * \param refl: A \ref Reflection
+ * \param temp: New temporary value for the reflection
  *
  * The temporary values can be used according to the needs of the calling
  * program.
@@ -835,9 +771,8 @@ void set_temp1(Reflection *refl, double temp)
 
 
 /**
- * set_temp2
- * @refl: A %Reflection
- * @temp: New temporary value for the reflection
+ * \param refl: A \ref Reflection
+ * \param temp: New temporary value for the reflection
  *
  * The temporary values can be used according to the needs of the calling
  * program.
@@ -850,11 +785,10 @@ void set_temp2(Reflection *refl, double temp)
 
 
 /**
- * set_flag
- * @refl: A %Reflection
- * @flag: New flag value
+ * \param refl: A \ref Reflection
+ * \param flag: New flag value
  *
- * @flag is an integer value which can be used according to the needs of the
+ * \param flag is an integer value which can be used according to the needs of the
  * calling program.
  *
  **/
@@ -865,9 +799,8 @@ void set_flag(Reflection *refl, int flag)
 
 
 /**
- * set_contributions:
- * @refl: A %Reflection
- * @contribs: Pointer to the contribution list
+ * \param refl: Reflection
+ * \param contribs: Pointer to the contribution list
  *
  * Note that the pointer will be stored, not the contents of the structure.
  *
@@ -973,17 +906,16 @@ static void add_to_list(RefList *list, Reflection *new,
 
 
 /**
- * add_refl
- * @list: A %RefList
- * @h: The 'h' index of the reflection
- * @k: The 'k' index of the reflection
- * @l: The 'l' index of the reflection
+ * \param list: A %RefList
+ * \param h: The 'h' index of the reflection
+ * \param k: The 'k' index of the reflection
+ * \param l: The 'l' index of the reflection
  *
- * Adds a new reflection to @list.  Note that the implementation allows there to
+ * Adds a new reflection to \p list.  Note that the implementation allows there to
  * be multiple reflections with the same indices in the list, so this function
  * should succeed even if the given indices already feature in the list.
  *
- * Returns: The newly created reflection, or NULL on failure.
+ * \returns The newly created reflection, or NULL on failure.
  *
  **/
 Reflection *add_refl(RefList *list, signed int h, signed int k, signed int l)
@@ -1004,11 +936,10 @@ Reflection *add_refl(RefList *list, signed int h, signed int k, signed int l)
 
 
 /**
- * add_refl_to_list
- * @refl: A %Reflection
- * @list: A %RefList
+ * \param refl: Reflection
+ * \param list: A %RefList
  *
- * Adds a @refl to @list.
+ * Adds \p refl to \p list.
  *
  **/
 void add_refl_to_list(Reflection *refl, RefList *list)
@@ -1034,15 +965,14 @@ struct _reflistiterator {
 
 
 /**
- * first_refl:
- * @list: A %RefList to iterate over
- * @piter: Address at which to store a %RefListIterator
+ * \param list: A %RefList to iterate over
+ * \param piter: Address at which to store a %RefListIterator
  *
  * This function sets up the state required for iteration over the entire list,
  * and then returns the first reflection in the list.  An iterator object will
  * be created and its address stored at the location given in piter.
  *
- * Returns: the first reflection in the list.
+ * \returns the first reflection in the list.
  *
  **/
 Reflection *first_refl(RefList *list, RefListIterator **piter)
@@ -1089,14 +1019,13 @@ Reflection *first_refl(RefList *list, RefListIterator **piter)
 
 
 /**
- * first_refl_const:
- * @list: A %RefList to iterate over
- * @piter: Address at which to store a %RefListIterator
+ * \param list: A %RefList to iterate over
+ * \param piter: Address at which to store a %RefListIterator
  *
  * As first_refl(), except returns a const %Reflection.
  * Use this when you don't need to modify any of the reflections.
  *
- * Returns: the first reflection in the list.
+ * \returns the first reflection in the list.
  *
  **/
 const Reflection *first_refl_const(const RefList *list, RefListIterator **piter)
@@ -1143,14 +1072,13 @@ const Reflection *first_refl_const(const RefList *list, RefListIterator **piter)
 
 
 /**
- * next_refl:
- * @refl: A reflection
- * @iter: A %RefListIterator
+ * \param refl: A reflection
+ * \param iter: A %RefListIterator
  *
  * This function looks up the next reflection in the list that was given earlier
  * to first_refl().
  *
- * Returns: the next reflection in the list, or NULL if no more.
+ * \returns the next reflection in the list, or NULL if no more.
  *
  **/
 Reflection *next_refl(Reflection *refl, RefListIterator *iter)
@@ -1197,14 +1125,13 @@ Reflection *next_refl(Reflection *refl, RefListIterator *iter)
 
 
 /**
- * next_refl_const:
- * @refl: A reflection
- * @iter: A %RefListIterator
+ * \param refl: A reflection
+ * \param iter: A %RefListIterator
  *
  * As next_refl(), except returns a const %Reflection.
  * Use this when you don't need to modify any of the reflections.
  *
- * Returns: the next reflection in the list, or NULL if no more.
+ * \returns the next reflection in the list, or NULL if no more.
  *
  **/
 const Reflection *next_refl_const(const Reflection *refl, RefListIterator *iter)
@@ -1286,10 +1213,9 @@ static int recursive_count(Reflection *refl)
 
 
 /**
- * num_reflections:
- * @list: A %RefList
+ * \param list: A %RefList
  *
- * Returns: the number of reflections in @list.
+ * \returns the number of reflections in \p list.
  *
  **/
 int num_reflections(RefList *list)
@@ -1299,13 +1225,12 @@ int num_reflections(RefList *list)
 
 
 /**
- * tree_depth:
- * @list: A %RefList
+ * \param list: A %RefList
  *
  * If the depth of the tree is more than about 20, access to the list will be
  * slow.  This should never happen.
  *
- * Returns: the depth of the RB-tree used internally to represent @list.
+ * \returns the depth of the RB-tree used internally to represent \p list.
  *
  **/
 int tree_depth(RefList *list)
@@ -1315,8 +1240,7 @@ int tree_depth(RefList *list)
 
 
 /**
- * lock_reflection:
- * @refl: A %Reflection
+ * \param refl: Reflection
  *
  * Acquires a lock on the reflection.
  */
@@ -1327,8 +1251,7 @@ void lock_reflection(Reflection *refl)
 
 
 /**
- * unlock_reflection:
- * @refl: A %Reflection
+ * \param refl: Reflection
  *
  * Releases a lock on the reflection.
  */
@@ -1346,10 +1269,9 @@ static void reflist_set_notes(RefList *reflist, const char *notes)
 
 
 /**
- * reflist_get_notes:
- * @reflist: A %RefList
+ * \param reflist: Reflection list
  *
- * Returns the notes field for @reflist, or NULL if there are no notes.
+ * \returns the notes field for \p reflist, or NULL if there are no notes.
  * See reflist_add_notes() for more details.
  */
 const char *reflist_get_notes(RefList *reflist)
@@ -1359,11 +1281,10 @@ const char *reflist_get_notes(RefList *reflist)
 
 
 /**
- * reflist_add_notes:
- * @reflist: A %RefList
- * @notes_add: Notes to add
+ * \param reflist: Reflection list
+ * \param notes_add: Notes to add
  *
- * Appends the string @notes_add to the notes field for @reflist.  The notes
+ * Appends the string \p notes_add to the notes field for \p reflist.  The notes
  * will be stored in the reflection list file by, e.g.,
  * write_reflist(), and are meant to be for humans to read.
  * Possible uses include making a record of the command line arguments used to
diff --git a/libcrystfel/src/reflist.h b/libcrystfel/src/reflist.h
index 30bbaa28..110280d6 100644
--- a/libcrystfel/src/reflist.h
+++ b/libcrystfel/src/reflist.h
@@ -38,11 +38,26 @@
 #define GET_K(serial) ((((serial) & 0x000ffc00)>>10)-512)
 #define GET_L(serial) (((serial) & 0x000003ff)-512)
 
+/**
+ * \file reflist.h
+ * The fast reflection list stores reflections in an RB-tree indexed
+ * by the Miller indices h, k and l.  Any reflection can be found in a
+ * length of time which scales logarithmically with the number of reflections in
+ * the list.
+ *
+ * A RefList can contain any number of reflections, and can store more than
+ * one reflection with a given set of indices, for example when two distinct
+ * reflections are to be stored according to their asymmetric indices.
+ *
+ * There are getters and setters which can be used to get and set values for an
+ * individual reflection.  The reflection list does not calculate any values,
+ * only stores what it was given earlier.  As such, you will need to carefully
+ * examine which fields your prior processing steps have filled in.
+ */
+
 
 /**
- * RefList:
- *
- * A %RefList represents a list of Bragg reflections.
+ * A RefList represents a list of Bragg reflections.
  *
  * This data structure is opaque.  You must use the available accessor functions
  * to read and write its contents.
@@ -51,9 +66,7 @@
 typedef struct _reflist RefList;
 
 /**
- * Reflection:
- *
- * A %Reflection represents a single Bragg reflection.
+ * A Reflection represents a single Bragg reflection.
  *
  * This data structure is opaque.  You must use the available accessor functions
  * to read and write its contents.
@@ -62,10 +75,8 @@ typedef struct _reflist RefList;
 typedef struct _reflection Reflection;
 
 /**
- * RefListIterator:
- *
- * A %RefListIterator is an opaque data type used when iterating over a
- * %RefList.
+ * A RefListIterator is an opaque data type used when iterating over a
+ * RefList.
  *
  **/
 typedef struct _reflistiterator RefListIterator;
@@ -85,8 +96,9 @@ struct reflection_contributions
 	Crystal    **contrib_crystals;
 };
 
-/* Creation/deletion */
 extern RefList *reflist_new(void);
+
+
 extern void reflist_free(RefList *list);
 extern Reflection *reflection_new(signed int h, signed int k, signed int l);
 extern void reflection_free(Reflection *refl);
diff --git a/libcrystfel/src/render.c b/libcrystfel/src/render.c
index 2dcb7b93..f7dd86fc 100644
--- a/libcrystfel/src/render.c
+++ b/libcrystfel/src/render.c
@@ -42,6 +42,7 @@
 #include "filters.h"
 #include "utils.h"
 
+/** \file render.h */
 
 static void render_rgb(double val, double max,
                        double *rp, double *gp, double *bp)
diff --git a/libcrystfel/src/render.h b/libcrystfel/src/render.h
index c2e5965a..0c2360b1 100644
--- a/libcrystfel/src/render.h
+++ b/libcrystfel/src/render.h
@@ -33,6 +33,10 @@
 #ifndef RENDER_H
 #define RENDER_H
 
+/**
+ * \file render.h
+ * Colour scale for rendering
+ */
 
 enum {
 	SCALE_COLOUR,
diff --git a/libcrystfel/src/statistics.c b/libcrystfel/src/statistics.c
index ccf35194..ff8f233c 100644
--- a/libcrystfel/src/statistics.c
+++ b/libcrystfel/src/statistics.c
@@ -39,17 +39,7 @@
 #include "statistics.h"
 #include "utils.h"
 
-/**
- * SECTION:statistics
- * @short_description: Intensity statistics and R-factors
- * @title: Statistics
- * @section_id:
- * @see_also:
- * @include: "statistics.h"
- * @Image:
- *
- * These functions are for calculating various figures of merit.
- */
+/** \file statistics.h */
 
 
 struct r_params {
diff --git a/libcrystfel/src/statistics.h b/libcrystfel/src/statistics.h
index 17338dad..4e2d2aff 100644
--- a/libcrystfel/src/statistics.h
+++ b/libcrystfel/src/statistics.h
@@ -39,6 +39,11 @@ extern "C" {
 
 #include "reflist.h"
 
+/**
+ * \file statistics.h
+ * Intensity statistic calculations
+ */
+
 extern double stat_scale_intensity(RefList *list1, RefList *list2);
 
 extern double stat_r1_zero(RefList *list1, RefList *list2,
diff --git a/libcrystfel/src/stream.c b/libcrystfel/src/stream.c
index 66b3b657..5aac2eab 100644
--- a/libcrystfel/src/stream.c
+++ b/libcrystfel/src/stream.c
@@ -52,6 +52,8 @@
 #include "reflist.h"
 #include "reflist-utils.h"
 
+/** \file stream.h */
+
 #define LATEST_MAJOR_VERSION (2)
 #define LATEST_MINOR_VERSION (3)
 
@@ -816,6 +818,18 @@ static int write_crystal(Stream *st, Crystal *cr, int include_reflections)
 }
 
 
+/**
+ * \param st A \ref Stream
+ * \param i An \ref image structure
+ * \param imfile A \ref imagefile structure
+ * \param include_peaks Whether to include peak search results in stream
+ * \param include_reflections Whether to include integration results in stream
+ * \param ev A \ref event strucutre
+ *
+ * Writes a new chunk to \p st.
+ *
+ * \returns non-zero on error.
+ */
 int write_chunk(Stream *st, struct image *i, struct imagefile *imfile,
                 int include_peaks, int include_reflections, struct event *ev)
 {
@@ -1180,7 +1194,9 @@ static int read_and_store_field(struct image *image, const char *line)
 }
 
 
-/* Read the next chunk from a stream and fill in 'image' */
+/**
+ * Read the next chunk from a stream and fill in 'image'
+ */
 int read_chunk_2(Stream *st, struct image *image,  StreamReadFlags srf)
 {
 	char line[1024];
@@ -1332,6 +1348,15 @@ int read_chunk_2(Stream *st, struct image *image,  StreamReadFlags srf)
 }
 
 
+
+/**
+ * \param st A \ref Stream
+ * \param image An \ref image structure to be filled
+ *
+ * Reads a chunk from \p st, placing the information in \p image.
+ *
+ * \returns non-zero on error.
+ */
 int read_chunk(Stream *st, struct image *image)
 {
 	return read_chunk_2(st, image, STREAM_READ_UNITCELL
@@ -1469,18 +1494,17 @@ Stream *open_stream_for_read(const char *filename)
 
 
 /**
- * open_stream_fd_for_write
- * @fd: File descriptor (e.g. from open()) to use for stream data.
+ * \param fd File descriptor (e.g. from open()) to use for stream data.
  *
- * Creates a new %Stream from @fd, so that stream data can be written to @fd
- * using write_chunk().
+ * Creates a new \ref Stream from \p fd, so that stream data can be written to \p fd
+ * using \ref write_chunk.
  *
- * In contrast to open_stream_for_write(), this function does not write any of
+ * In contrast to \ref open_stream_for_write, this function does not write any of
  * the usual headers.  This function is mostly for use when multiple substreams
  * need to be multiplexed into a single master stream.  The master would be
- * opened using open_stream_for_write(), and the substreams using this function.
+ * opened using \ref open_stream_for_write, and the substreams using this function.
  *
- * Returns: a %Stream, or NULL on failure.
+ * \returns A \ref Stream, or NULL on failure.
  */
 Stream *open_stream_fd_for_write(int fd)
 {
@@ -1517,19 +1541,18 @@ static void write_cell_to_stream(Stream *st, UnitCell *cell)
 
 
 /**
- * open_stream_for_write_4
- * @filename: Filename of new stream
- * @geom_filename: The geometry filename to copy
- * @cell: A %UnitCell to write into the stream
- * @argc: The number of arguments to the program
- * @argv: The arguments to the program
- * @indm_str: The list of indexing methods
+ * \param filename Filename of new stream
+ * \param geom_filename The geometry filename to copy
+ * \param cell A \ref UnitCell to write into the stream
+ * \param argc The number of arguments to the program
+ * \param argv The arguments to the program
+ * \param indm_str The list of indexing methods
  *
- * Creates a new stream with name @filename, and adds the stream format
+ * Creates a new stream with name \p filename, and adds the stream format
  * and version header, plus a verbatim copy of the geometry file and the unit
  * cell in CrystFEL format.
  *
- * Returns: a %Stream, or NULL on failure.
+ * \returns A \ref Stream, or NULL on failure.
  */
 Stream *open_stream_for_write_4(const char *filename,
                                 const char *geom_filename, UnitCell *cell,
@@ -1586,16 +1609,15 @@ Stream *open_stream_for_write_3(const char *filename,
 
 
 /**
- * open_stream_for_write_2
- * @filename: Filename of new stream
- * @geom_filename: The geometry filename to copy
- * @argc: The number of arguments to the program
- * @argv: The arguments to the program
+ * \param filename Filename of new stream
+ * \param geom_filename The geometry filename to copy
+ * \param argc The number of arguments to the program
+ * \param argv The arguments to the program
  *
- * Creates a new stream with name @filename, and adds the stream format
+ * Creates a new stream with name \p filename, and adds the stream format
  * and version header, plus a verbatim copy of the geometry file
  *
- * Returns: a %Stream, or NULL on failure.
+ * \returns A \ref Stream, or NULL on failure.
  */
 Stream *open_stream_for_write_2(const char *filename,
                                 const char *geom_filename, int argc,
@@ -1636,16 +1658,15 @@ Stream *open_stream_for_write_2(const char *filename,
 
 
 /**
- * open_stream_for_write
- * @filename: Filename of new stream
+ * \param filename Filename of new stream
  *
- * Creates a new stream with name @filename, and adds the stream format
+ * Creates a new stream with name \p filename, and adds the stream format
  * and version headers.
  *
- * You may want to follow this with a call to write_command() to record the
+ * You may want to follow this with a call to \ref write_command to record the
  * command line.
  *
- * Returns: a %Stream, or NULL on failure.
+ * \returns A \ref Stream, or NULL on failure.
  */
 Stream *open_stream_for_write(const char *filename)
 {
@@ -1654,17 +1675,16 @@ Stream *open_stream_for_write(const char *filename)
 
 
 /**
- * get_stream_fd
- * @st: A %Stream
+ * \param st A \ref Stream
  *
- * This function gets the integer file descriptor for @st, a bit like fileno().
+ * This function gets the integer file descriptor for \p st, a bit like fileno().
  *
- * This is useful in conjunction with open_stream_fd_for_write(), to get the
+ * This is useful in conjunction with \ref open_stream_fd_for_write, to get the
  * underlying file descriptor to which the multiplexed stream data should be
  * written.  In this case, the only other operations you should ever do (or have
- * done) on @st are open_stream_for_write() and close_stream().
+ * done) on \p st are \ref open_stream_for_write and \ref close_stream.
  *
- * Returns: an integer file descriptor
+ * \returns An integer file descriptor
  */
 int get_stream_fd(Stream *st)
 {
@@ -1672,6 +1692,11 @@ int get_stream_fd(Stream *st)
 }
 
 
+/**
+ * \param st A \ref Stream
+ *
+ * Closes the stream
+ */
 void close_stream(Stream *st)
 {
 	free(st->audit_info);
@@ -1702,14 +1727,13 @@ int is_stream(const char *filename)
 
 
 /**
- * write_command
- * @st: A %Stream
- * @argc: number of arguments
- * @argv: command-line arguments
+ * \param st A \ref Stream
+ * \param argc number of arguments
+ * \param argv command-line arguments
  *
- * Writes the command line to @st.  @argc and @argv should be exactly as were
+ * Writes the command line to \p st.  \p argc and \p argv should be exactly as were
  * given to main().  This should usually be called immediately after
- * open_stream_for_write().
+ * ref open_stream_for_write.
  */
 void write_command(Stream *st, int argc, char *argv[])
 {
@@ -1727,12 +1751,11 @@ void write_command(Stream *st, int argc, char *argv[])
 
 
 /**
- * write_geometry_file
- * @st: A %Stream
- * @geom_filename: geomtry file name
+ * \param st A \ref Stream
+ * \param geom_filename geomtry file name
  *
- * Writes the content of the geometry file to @st. This should usually be
- * called immediately after write_command().
+ * Writes the content of the geometry file to \p st. This should usually be
+ * called immediately after \ref write_command.
  */
 void write_geometry_file(Stream *st, const char *geom_filename) {
 
@@ -1770,16 +1793,15 @@ void write_geometry_file(Stream *st, const char *geom_filename) {
 
 
 /**
- * rewind_stream:
- * @st: A %Stream
+ * \param st A \ref Stream
  *
- * Attempts to set the file pointer for @st to the start of the stream, so that
- * later calls to read_chunk() will repeat the sequence of chunks from the
+ * Attempts to set the file pointer for \p st to the start of the stream, so that
+ * later calls to \ref read_chunk will repeat the sequence of chunks from the
  * start.
  *
  * Programs must not assume that this operation always succeeds!
  *
- * Returns: non-zero if the stream could not be rewound.
+ * \returns Non-zero if the stream could not be rewound.
  */
 int rewind_stream(Stream *st)
 {
diff --git a/libcrystfel/src/stream.h b/libcrystfel/src/stream.h
index bd7aa690..ea271d9b 100644
--- a/libcrystfel/src/stream.h
+++ b/libcrystfel/src/stream.h
@@ -35,6 +35,10 @@
 #include <config.h>
 #endif
 
+/**
+ * \file stream.h
+ * Stream functions (for indexing results)
+ */
 
 struct image;
 struct hdfile;
@@ -56,27 +60,31 @@ struct imagefile;
 /* REFLECTION_END_MARKER is over in reflist-utils.h because it is also
  * used to terminate a standalone list of reflections */
 
+/**
+ * An opaque structure representing a stream being read or written
+ */
 typedef struct _stream Stream;
 
 /**
- * StreamReadFlags:
- * @STREAM_READ_UNITCELL: Read the unit cell
- * @STREAM_READ_REFLECTIONS: Read the integrated reflections
- * @STREAM_READ_PEAKS: Read the peak search results
- * @STREAM_READ_CRYSTALS: Read the general information about crystals
- *
  * A bitfield of things that can be read from a stream.  Use this (and
- * read_chunk_2()) to read the stream faster if you don't need the entire
+ * \ref read_chunk_2) to read the stream faster if you don't need the entire
  * contents of the stream.
  *
- * Using either or both of @STREAM_READ_REFLECTIONS and @STREAM_READ_UNITCELL
- * implies @STREAM_READ_CRYSTALS.
+ * Using either or both of \p STREAM_READ_REFLECTIONS and \p STREAM_READ_UNITCELL
+ * implies \p STREAM_READ_CRYSTALS.
  **/
 typedef enum {
 
+	/** Read the unit cell */
 	STREAM_READ_UNITCELL = 1,
+
+	/** Read the integrated reflections */
 	STREAM_READ_REFLECTIONS = 2,
+
+	/** Read the peak search results */
 	STREAM_READ_PEAKS = 4,
+
+	/** Read the general information about crystals */
 	STREAM_READ_CRYSTALS = 8,
 
 } StreamReadFlags;
diff --git a/libcrystfel/src/symmetry.c b/libcrystfel/src/symmetry.c
index cee29d5a..6739daaf 100644
--- a/libcrystfel/src/symmetry.c
+++ b/libcrystfel/src/symmetry.c
@@ -45,18 +45,7 @@
 #include "symop-lex.h"
 
 
-/**
- * SECTION:symmetry
- * @short_description: Point symmetry handling
- * @title: Symmetry
- * @section_id:
- * @see_also:
- * @include: "symmetry.h"
- * @Image:
- *
- * Routines to handle point symmetry.
- */
-
+/** \file symmetry.h */
 
 struct _symoplist
 {
@@ -84,9 +73,9 @@ static void alloc_ops(SymOpList *ops)
 
 /**
  * new_symopmask:
- * @list: A %SymOpList
+ * \param list A \ref SymOpList
  *
- * Returns: a new %SymOpMask, which you can use when filtering out special
+ * \returns A new \ref SymOpMask, which you can use when filtering out special
  * reflections.
  **/
 SymOpMask *new_symopmask(const SymOpList *list)
@@ -129,10 +118,9 @@ static SymOpList *new_symoplist()
 
 
 /**
- * free_symoplist:
- * @ops: A %SymOpList to free
+ * \param ops A \ref SymOpList to free
  *
- * Frees a %SymOpList and all associated resources.
+ * Frees a \ref SymOpList and all associated resources.
  **/
 void free_symoplist(SymOpList *ops)
 {
@@ -148,10 +136,9 @@ void free_symoplist(SymOpList *ops)
 }
 
 /**
- * free_symopmask:
- * @m: A %SymOpMask to free
+ * \param m A \ref SymOpMask to free
  *
- * Frees a %SymOpMask and all associated resources.
+ * Frees a \ref SymOpMask and all associated resources.
  **/
 void free_symopmask(SymOpMask *m)
 {
@@ -170,11 +157,10 @@ static int num_ops(const SymOpList *ops)
 
 
 /**
- * add_symop:
- * @ops: A %SymOpList
- * @m: An %IntegerMatrix
+ * \param ops A \ref SymOpList
+ * \param m An \ref IntegerMatrix
  *
- * Adds @m to @ops.
+ * Adds \p m to \p ops.
  **/
 void add_symop(SymOpList *ops, IntegerMatrix *m)
 {
@@ -210,10 +196,9 @@ static void add_symop_v(SymOpList *ops,
 
 
 /**
- * get_symop:
- * @ops: A %SymOpList
- * @m: A %SymOpMask
- * @idx: Index of the operation to get
+ * \param ops A \ref SymOpList
+ * \param m A \ref SymOpMask
+ * \param idx Index of the operation to get
  *
  * This function returns a pointer to an integer matrix specifying a symmetry
  * operation contained in the symmetry operator list, and identified by the
@@ -270,13 +255,12 @@ static signed int *v(signed int h, signed int k, signed int i, signed int l)
 
 
 /**
- * num_equivs:
- * @ops: A %SymOpList
- * @m: A %SymOpMask, which has been shown to special_position()
+ * \param ops A \ref SymOpList
+ * \param m A \ref SymOpMask, which has been shown to \ref special_position
  *
- * Returns: the number of equivalent reflections for a general reflection
+ * \returns The number of equivalent reflections for a general reflection
  * in point group "ops", which were not flagged by your call to
- * special_position().
+ * \ref special_position.
  **/
 int num_equivs(const SymOpList *ops, const SymOpMask *m)
 {
@@ -1056,10 +1040,9 @@ static SymOpList *getpg_arbitrary_ua(const char *sym, size_t s)
 
 
 /**
- * get_pointgroup:
- * @sym: A string representation of a point group
+ * \param sym A string representation of a point group
  *
- * This function parses @sym and returns the corresponding %SymOpList.
+ * This function parses \p sym and returns the corresponding \ref SymOpList.
  * In the string representation of the point group, use a preceding minus sign
  * for any character which would have a "bar".  Trigonal groups must be suffixed
  * with either "_H" or "_R" for a hexagonal or rhombohedral lattice
@@ -1135,26 +1118,25 @@ static void do_op(const IntegerMatrix *op,
 
 
 /**
- * get_equiv:
- * @ops: A %SymOpList
- * @m: A %SymOpMask, which has been shown to special_position()
- * @idx: Index of the operation to use
- * @h: index of reflection
- * @k: index of reflection
- * @l: index of reflection
- * @he: location to store h index of equivalent reflection
- * @ke: location to store k index of equivalent reflection
- * @le: location to store l index of equivalent reflection
+ * \param ops A \ref SymOpList
+ * \param m A \ref SymOpMask, which has been shown to \ref special_position
+ * \param idx Index of the operation to use
+ * \param h index of reflection
+ * \param k index of reflection
+ * \param l index of reflection
+ * \param he location to store h index of equivalent reflection
+ * \param ke location to store k index of equivalent reflection
+ * \param le location to store l index of equivalent reflection
  *
- * This function applies the @idx-th symmetry operation from @ops to the
- * reflection @h, @k, @l, and stores the result at @he, @ke and @le.
+ * This function applies the \p idx-th symmetry operation from \p ops to the
+ * reflection \p h, \p k, \p l, and stores the result at \p he, \p ke and \p le.
  *
  * Call this function multiple times with idx=0 .. num_equivs(ops, m) to get all
  * of the equivalent reflections in turn.
  *
  * If you don't mind that the same equivalent might appear twice, simply let
- * @m = NULL.  Otherwise, call new_symopmask() and then special_position() to
- * set up a %SymOpMask appropriately.
+ * \p m = NULL.  Otherwise, call \ref new_symopmask and then
+ * \ref special_position to set up a \ref SymOpMask appropriately.
  **/
 void get_equiv(const SymOpList *ops, const SymOpMask *m, int idx,
                signed int h, signed int k, signed int l,
@@ -1168,16 +1150,14 @@ void get_equiv(const SymOpList *ops, const SymOpMask *m, int idx,
 
 
 /**
- * special_position:
- * @ops: A %SymOpList, usually corresponding to a point group
- * @m: A %SymOpMask created with new_symopmask()
- * @h: index of a reflection
- * @k: index of a reflection
- * @l: index of a reflection
- *
- * This function sets up @m to contain information about which operations in
- * @ops map the reflection @h, @k, @l onto itself.
+ * \param ops A \ref SymOpList, usually corresponding to a point group
+ * \param m A \ref SymOpMask created with \ref new_symopmask
+ * \param h index of a reflection
+ * \param k index of a reflection
+ * \param l index of a reflection
  *
+ * This function sets up \p m to contain information about which operations in
+ * \p ops map the reflection \p h, \p k, \p l onto itself.
  **/
 void special_position(const SymOpList *ops, SymOpMask *m,
                       signed int h, signed int k, signed int l)
@@ -1233,15 +1213,14 @@ static int any_negative(signed int h, signed int k, signed int l)
 
 
 /**
- * is_centric:
- * @h: h index
- * @k: k index
- * @l: l index
- * @ops: A %SymOpList
+ * \param h h index
+ * \param k k index
+ * \param l l index
+ * \param ops A \ref SymOpList
  *
  * A reflection is centric if it is related by symmetry to its Friedel partner.
  *
- * Returns: true if @h @k @l is centric in @ops.
+ * \returns True if \p h \p k \p l is centric in \p ops.
  *
  **/
 int is_centric(signed int h, signed int k, signed int l, const SymOpList *ops)
@@ -1261,24 +1240,23 @@ int is_centric(signed int h, signed int k, signed int l, const SymOpList *ops)
 
 
 /**
- * get_asymm:
- * @ops: A %SymOpList, usually corresponding to a point group
- * @h: index of a reflection
- * @k: index of a reflection
- * @l: index of a reflection
- * @hp: location for asymmetric index of reflection
- * @kp: location for asymmetric index of reflection
- * @lp: location for asymmetric index of reflection
+ * \param ops A \ref SymOpList, usually corresponding to a point group
+ * \param h index of a reflection
+ * \param k index of a reflection
+ * \param l index of a reflection
+ * \param hp location for asymmetric index of reflection
+ * \param kp location for asymmetric index of reflection
+ * \param lp location for asymmetric index of reflection
  *
- * This function determines the asymmetric version of the reflection @h, @k, @l
- * in symmetry group @ops, and puts the result in @hp, @kp, @lp.
+ * This function determines the asymmetric version of the reflection \p h, \p k, \p l
+ * in symmetry group \p ops, and puts the result in \p hp, \p kp, \p lp.
  *
  * This is a relatively expensive operation because of its generality.
  * Therefore, if you know you'll need to make repeated use of the asymmetric
- * indices, consider creating a new %RefList indexed according to the asymmetric
- * indices themselves with asymmetric_indices().  If you do that, you'll still
+ * indices, consider creating a new \ref RefList indexed according to the asymmetric
+ * indices themselves with \ref asymmetric_indices.  If you do that, you'll still
  * be able to get the original versions of the indices with
- * get_symmetric_indices().
+ * \ref get_symmetric_indices.
  *
  **/
 void get_asymm(const SymOpList *ops,
@@ -1338,10 +1316,9 @@ void get_asymm(const SymOpList *ops,
 
 
 /**
- * is_centrosymmetric:
- * @s: A %SymOpList
+ * \param s A \ref SymOpList
  *
- * Returns: non-zero if @s contains an inversion operation
+ * \returns Non-zero if \p s contains an inversion operation
  */
 int is_centrosymmetric(const SymOpList *s)
 {
@@ -1374,11 +1351,10 @@ static int check_mult(const IntegerMatrix *ans,
 
 
 /**
- * is_subgroup:
- * @source: A %SymOpList
- * @target: Another %SymOpList, which might be a subgroup of @source.
+ * \param source A \ref SymOpList
+ * \param target Another \ref SymOpList, which might be a subgroup of \p source.
  *
- * Returns: non-zero if every operation in @target is also in @source.
+ * \returns Non-zero if every operation in \p target is also in \p source.
  **/
 int is_subgroup(const SymOpList *source, const SymOpList *target)
 {
@@ -1529,19 +1505,18 @@ static SymOpList *flack_reorder(const SymOpList *source)
 
 
 /**
- * get_ambiguities:
- * @source: The "source" symmetry, a %SymOpList
- * @target: The "target" symmetry, a %SymOpList
+ * \param source The "source" symmetry, a \ref SymOpList
+ * \param target The "target" symmetry, a \ref SymOpList
 
- * Calculates twinning laws.  Returns a %SymOpList containing the twinning
- * operators, which are the symmetry operations which can be added to @target
- * to generate @source.  Only rotations are allowable - no mirrors nor
+ * Calculates twinning laws.  Returns a \ref SymOpList containing the twinning
+ * operators, which are the symmetry operations which can be added to \p target
+ * to generate \p source.  Only rotations are allowable - no mirrors nor
  * inversions.
- * To count the number of possibilities, use num_equivs() on the result.
+ * To count the number of possibilities, use \ref num_equivs on the result.
  *
  * The algorithm used is "Algorithm A" from Flack (1987), Acta Cryst A43 p564.
  *
- * Returns: A %SymOpList containing the twinning operators, or NULL if the
+ * \returns a \ref SymOpList containing the twinning operators, or NULL if the
  * source symmetry cannot be generated from that target symmetry without using
  * mirror or inversion operations.
  */
@@ -1661,13 +1636,12 @@ RationalMatrix *parse_symmetry_operation(const char *s)
 
 
 /**
- * parse_cell_transformation
- * @s: Textual representation of cell transformation
+ * \param s Textual representation of cell transformation
  *
- * Parses @s, for example 'a,(b+a)/2,c', and returns the corresponding
- * %RationalMatrix.
+ * Parses \p s, for example 'a,(b+a)/2,c', and returns the corresponding
+ * \ref RationalMatrix.
  *
- * Returns: A %RationalMatrix describing the transformation, or NULL on error.
+ * \returns a \ref RationalMatrix describing the transformation, or NULL on error.
  *
  */
 RationalMatrix *parse_cell_transformation(const char *s)
@@ -1677,13 +1651,12 @@ RationalMatrix *parse_cell_transformation(const char *s)
 
 
 /**
- * parse_symmetry_operations
- * @s: Textual representation of a list of symmetry operations
+ * \param s Textual representation of a list of symmetry operations
  *
- * Parses @s, for example 'h,k,l;k,h,-l', and returns the corresponding
- * %SymOpList
+ * Parses \p s, for example 'h,k,l;k,h,-l', and returns the corresponding
+ * \ref SymOpList
  *
- * Returns: A %SymOpList, or NULL on error.
+ * \returns a \ref SymOpList, or NULL on error.
  *
  */
 SymOpList *parse_symmetry_operations(const char *s)
@@ -1789,8 +1762,7 @@ static char *name_equiv(const IntegerMatrix *op)
 
 
 /**
- * describe_symmetry:
- * @s: A %SymOpList
+ * \param s A \ref SymOpList
  *
  * Writes the name and a list of operations to stderr.
  */
@@ -1833,10 +1805,9 @@ void describe_symmetry(const SymOpList *s)
 
 
 /**
- * symmetry_name:
- * @ops: A %SymOpList
+ * \param ops A \ref SymOpList
  *
- * Returns: a text description of @ops.
+ * \returns A text description of \p ops.
  */
 const char *symmetry_name(const SymOpList *ops)
 {
@@ -1845,12 +1816,11 @@ const char *symmetry_name(const SymOpList *ops)
 
 
 /**
- * set_symmetry_name:
- * @ops: A %SymOpList
- * @name: New name for the %SymOpList
+ * \param ops A \ref SymOpList
+ * \param name New name for the \ref SymOpList
  *
- * Sets the text description of @ops to @name.  See symmetry_name().
- * @name will be copied, so you can safely free it after calling this function,
+ * Sets the text description of \p ops to \p name.  See \ref symmetry_name.
+ * \p name will be copied, so you can safely free it after calling this function,
  * if that's otherwise appropriate.
  */
 void set_symmetry_name(SymOpList *ops, const char *name)
diff --git a/libcrystfel/src/symmetry.h b/libcrystfel/src/symmetry.h
index ab2aa934..42a2b9fb 100644
--- a/libcrystfel/src/symmetry.h
+++ b/libcrystfel/src/symmetry.h
@@ -39,8 +39,11 @@
 #include "rational.h"
 
 /**
- * SymOpList
- *
+ * \file symmetry.h
+ * Point group symmetry
+ */
+
+/**
  * The SymOpList is an opaque data structure containing a list of point symmetry
  * operations.  It could represent an point group or a list of indexing
  * ambiguities (twin laws), or similar.
@@ -48,11 +51,9 @@
 typedef struct _symoplist SymOpList;
 
 /**
- * SymOpMask
- *
  * The SymOpMask is an opaque data structure containing a list of flags
- * associated with point symmetry operations in a specific %SymOpList.  It is
- * used to filter the operations in the %SymOpList to avoid duplicating
+ * associated with point symmetry operations in a specific \ref SymOpList.  It is
+ * used to filter the operations in the \ref SymOpList to avoid duplicating
  * equivalent reflections when the reflection is somehow special (e.g. 'hk0').
  **/
 typedef struct _symopmask SymOpMask;
diff --git a/libcrystfel/src/taketwo.c b/libcrystfel/src/taketwo.c
index 933fa76a..ddbfe173 100644
--- a/libcrystfel/src/taketwo.c
+++ b/libcrystfel/src/taketwo.c
@@ -29,19 +29,22 @@
  */
 
 /**
- * \class TakeTwo
- * Code outline.
- * --- Get ready for calculation ---
- * Pre-calculate symmetry operations (generate_rotation_symops())
- * Pre-calculate theoretical vectors from unit cell dimensions
+ * \file taketwo.h
+
+ * ## Code outline
+
+ * ### Get ready for calculation
+ * * Pre-calculate symmetry operations (generate_rotation_symops())
+ * * Pre-calculate theoretical vectors from unit cell dimensions
  * (gen_theoretical_vecs())
- * Generate observed vectors from data (gen_observed_vecs())
- * Match observed vectors to theoretical vectors (match_obs_to_cell_vecs())
+ * * Generate observed vectors from data (gen_observed_vecs())
+ * * Match observed vectors to theoretical vectors (match_obs_to_cell_vecs())
+ *
+ * ### Business bit
  *
- * --- Business bit ---
  * ... n.b. rearranging to find all seeds in advance.
  *
- * Find starting seeds (find_seeds()):
+ * * Find starting seeds (find_seeds()):
  *   - Loop through pairs of observed vectors
  *   - If they share a spot, find matching pairs of theoretical vectors
  *   - Remove all duplicate matches due to symmetry operations
@@ -50,7 +53,7 @@
  *   - If it returns a membership greater than the highest member threshold,
  *   return the matrix to CrystFEL.
  *
- * Extending a seed (start_seed()):
+ * * Extending a seed (start_seed()):
  *   - Generate a rotation matrix which matches the chosen start seed.
  *   - Loop through all observed vectors starting from 0.
  *   - Find another vector to add to the network, if available
@@ -64,7 +67,7 @@
  *   - If the membership does not, then resume the loop and search for the
  *   next vector.
  *
- * Finding the next member (find_next_index()):
+ * * Finding the next member (find_next_index()):
  *   - Go through the observed vectors, starting from the last index + 1 to
  *   explore only the "new" vectors.
  *   - If the vector does not share a spot with the current array of vectors,
@@ -75,20 +78,12 @@
  *   for a single matching theoretical vector.
  *   - If it does match, we can return a success.
  *
- * Tidying the solution (finish_solution()):
+ * * Tidying the solution (finish_solution()):
  *   - This chooses the most common rotation matrix of the bunch to choose to
  *   send to CrystFEL. But this should probably take the average instead,
  *   which is very possible.
  *
- * Clean up the mess (cleanup_taketwo_obs_vecs())
- */
-
-/**
- * Helen's to-do list
- * -
- *
- *
- * - Improve the final solution
+ * * Clean up the mess (cleanup_taketwo_obs_vecs())
  */
 
 #include <gsl/gsl_matrix.h>
@@ -106,13 +101,12 @@
 #include "symmetry.h"
 
 /**
- * spotvec
- * @obsvec: an observed vector between two spots
- * @matches: array of matching theoretical vectors from unit cell
- * @match_num: number of matches
- * @distance: length of obsvec (do I need this?)
- * @her_rlp: pointer to first rlp position for difference vec
- * @his_rlp: pointer to second rlp position for difference vec
+ * \param obsvec an observed vector between two spots
+ * \param matches array of matching theoretical vectors from unit cell
+ * \param match_num number of matches
+ * \param distance length of obsvec (do I need this?)
+ * \param her_rlp pointer to first rlp position for difference vec
+ * \param his_rlp pointer to second rlp position for difference vec
  *
  * Structure representing 3D vector between two potential Bragg peaks
  * in reciprocal space, and an array of potential matching theoretical
diff --git a/libcrystfel/src/taketwo.h b/libcrystfel/src/taketwo.h
index fcd7aebc..6960446d 100644
--- a/libcrystfel/src/taketwo.h
+++ b/libcrystfel/src/taketwo.h
@@ -34,6 +34,8 @@
 #include "cell.h"
 #include "index.h"
 
+/** \file taketwo.h */
+
 struct taketwo_options
 {
 	int member_thresh;
diff --git a/libcrystfel/src/thread-pool.c b/libcrystfel/src/thread-pool.c
index 709b1521..936baf92 100644
--- a/libcrystfel/src/thread-pool.c
+++ b/libcrystfel/src/thread-pool.c
@@ -41,19 +41,7 @@
 #include "utils.h"
 
 
-/**
- * SECTION:thread-pool
- * @short_description: The thread pool
- * @title: The thread pool
- * @section_id:
- * @see_also:
- * @include: "thread-pool.h"
- * @Image:
- *
- * The thread pool helps when running many tasks in parallel.  It takes care of
- * starting and stopping threads, and presents a relatively simple interface to
- * the individual programs.
- */
+/** \file thread-pool.h */
 
 /* --------------------------- Status label stuff --------------------------- */
 
@@ -151,32 +139,31 @@ static void *task_worker(void *pargsv)
 
 
 /**
- * run_threads:
- * @n_threads: The number of threads to run in parallel
- * @work: The function to be called to do the work
- * @get_task: The function which will determine the next unassigned task
- * @final: The function which will be called to clean up after a task
- * @queue_args: A pointer to any data required to determine the next task
- * @max: Stop calling get_task after starting this number of jobs
- * @cpu_num: Ignored
- * @cpu_groupsize: Ignored
- * @cpu_offset: Ignored
+ * \param n_threads The number of threads to run in parallel
+ * \param work The function to be called to do the work
+ * \param get_task The function which will determine the next unassigned task
+ * \param final The function which will be called to clean up after a task
+ * \param queue_args A pointer to any data required to determine the next task
+ * \param max Stop calling get_task after starting this number of jobs
+ * \param cpu_num Ignored
+ * \param cpu_groupsize Ignored
+ * \param cpu_offset Ignored
  *
- * 'get_task' will be called every time a worker is idle.  It returns either
+ * \p get_task will be called every time a worker is idle.  It returns either
  * NULL, indicating that no further work is available, or a pointer which will
- * be passed to 'work'.
+ * be passed to \p work.
  *
- * 'final' will be called once per image, and will be given both queue_args
+ * \p final will be called once per image, and will be given both queue_args
  * and the last task pointer.
  *
- * 'get_task' and 'final' will be called only under lock, and so do NOT need to
+ * \p get_task and \p final will be called only under lock, and so do NOT need to
  * be re-entrant or otherwise thread safe.  'work', of course, needs to be
  * thread safe.
  *
- * Work will stop after 'max' tasks have been processed whether get_task
- * returned NULL or not.  If "max" is zero, all tasks will be processed.
+ * Work will stop after \p max tasks have been processed whether get_task
+ * returned NULL or not.  If \p max is zero, all tasks will be processed.
  *
- * Returns: The number of tasks completed.
+ * \returns The number of tasks completed.
  **/
 int run_threads(int n_threads, TPWorkFunc work,
                 TPGetTaskFunc get_task, TPFinalFunc final,
diff --git a/libcrystfel/src/thread-pool.h b/libcrystfel/src/thread-pool.h
index 5a305d5d..d1def8b9 100644
--- a/libcrystfel/src/thread-pool.h
+++ b/libcrystfel/src/thread-pool.h
@@ -43,41 +43,39 @@ extern "C" {
 extern pthread_mutex_t stderr_lock;
 extern signed int get_status_label(void);
 
+/**
+ * \file thread-pool.h
+ * Thread pool.
+ */
 
 /**
- * TPGetTaskFunc:
- * @qargs: The queue_args pointer which was given to run_threads().
- * Returns: A pointer which will be passed to the worker function.
+ * \p qargs: The queue_args pointer which was given to run_threads().
+ * \returns a pointer which will be passed to the worker function.
  *
  * This function is called, non-reentrantly, to get a new work item to give to
  * your work function.  The stuff you need to generate the new work item should
- * have been stored in @qargs which was passed to run_threads().
- *
+ * have been stored in \p qargs which was passed to \ref run_threads.
  **/
 typedef void *(*TPGetTaskFunc)(void *qargs);
 
 
 /**
- * TPWorkFunc:
- * @work: The queue_args pointer which was given to run_threads().
- * @cookie: A small integral number which is guaranteed to be unique among all
+ * \param work The queue_args pointer which was given to \ref run_threads.
+ * \param cookie A small integral number which is guaranteed to be unique among all
  * currently running threads.
  *
  * This function is called, reentrantly, for each work item.
- *
  **/
 typedef void (*TPWorkFunc)(void *work, int cookie);
 
 
 /**
- * TPFinalFunc:
- * @qargs: The queue_args pointer which was given to run_threads().
- * @work: The pointer which was returned by your get_task function.
+ * \param qargs The queue_args pointer which was given to \ref run_threads.
+ * \param work The pointer which was returned by your get_task function.
  *
  * This function is called, non-reentrantly, after each work item has been
- * completed.  A typical use might be to update some counters inside @qargs
- * according to fields withing @work which were filled by your 'work' function.
- *
+ * completed.  A typical use might be to update some counters inside \p qargs
+ * according to fields withing \p work which were filled by your 'work' function.
  **/
 typedef void (*TPFinalFunc)(void *qargs, void *work);
 
diff --git a/libcrystfel/src/utils.c b/libcrystfel/src/utils.c
index 19dfe2a8..a2ba2c60 100644
--- a/libcrystfel/src/utils.c
+++ b/libcrystfel/src/utils.c
@@ -46,25 +46,13 @@
 #include "utils.h"
 #include "image.h"
 
+/** \file utils.h */
 
 /**
- * SECTION:utils
- * @short_description: Miscellaneous utilities
- * @title: Utilities
- * @section_id:
- * @see_also:
- * @include: "utils.h"
- * @Image:
+ * \param M A matrix
+ * \param v A vector
  *
- * Wibble
- */
-
-/**
- * show_matrix_eqn:
- * @M: A matrix
- * @v: A vector
- *
- * Displays a matrix equation of the form @M.a = @v.
+ * Displays a matrix equation of the form \p M.a = \p v.
  **/
 void show_matrix_eqn(gsl_matrix *M, gsl_vector *v)
 {
@@ -91,8 +79,7 @@ void show_matrix_eqn(gsl_matrix *M, gsl_vector *v)
 
 
 /**
- * show_matrix:
- * @M: A matrix
+ * \param M A matrix
  *
  * Displays a matrix.
  **/
@@ -155,11 +142,10 @@ static int check_eigen(gsl_vector *e_val, int verbose)
 
 
 /**
- * solve_svd:
- * @v: a gsl_vector
- * @M: a gsl_matrix
- * @n_filt: pointer to store the number of filtered eigenvalues
- * @verbose: flag for verbosity on the terminal
+ * \param v a gsl_vector
+ * \param M a gsl_matrix
+ * \param pn_filt pointer to store the number of filtered eigenvalues
+ * \param verbose flag for verbosity on the terminal
  *
  * Solves the matrix equation M.x = v, returning x.
  * Performs rescaling and eigenvalue filtering.
@@ -412,7 +398,8 @@ static int assplode_extract(char ***pbits, int n, size_t n_captured,
 }
 
 
-/* Split the string 'a' using 'delims' as a zero-terminated list of
+/**
+ * Split the string 'a' using 'delims' as a zero-terminated list of
  *  deliminators.
  * Store each segment in bits[0...n] where n is the number of segments and is
  *  the return value.  pbits = &bits
@@ -569,26 +556,11 @@ void utils_fudge_gslcblas()
 
 
 /**
- * SECTION:quaternion
- * @short_description: Simple quaternion handling
- * @title: Quaternion
- * @section_id:
- * @see_also:
- * @include: "utils.h"
- * @Image:
- *
- * There is a simple quaternion structure in CrystFEL.  At the moment, it is
- * only used when simulating patterns, as an argument to cell_rotate() to
- * orient the unit cell.
- */
-
-/**
- * quaternion_modulus:
- * @q: A %quaternion
+ * \param q A \ref quaternion
  *
  * If a quaternion represents a pure rotation, its modulus should be unity.
  *
- * Returns: the modulus of the given quaternion.
+ * \returns The modulus of the given quaternion.
  **/
 double quaternion_modulus(struct quaternion q)
 {
@@ -597,12 +569,11 @@ double quaternion_modulus(struct quaternion q)
 
 
 /**
- * normalise_quaternion:
- * @q: A %quaternion
+ * \param q A \ref quaternion
  *
  * Rescales the quaternion such that its modulus is unity.
  *
- * Returns: the normalised version of @q
+ * \returns The normalised version of \p q
  **/
 struct quaternion normalise_quaternion(struct quaternion q)
 {
@@ -621,10 +592,9 @@ struct quaternion normalise_quaternion(struct quaternion q)
 
 
 /**
- * random_quaternion:
- * @rng: A GSL random number generator to use
+ * \param rng A GSL random number generator to use
  *
- * Returns: a randomly generated, normalised, quaternion.
+ * \returns A randomly generated, normalised, quaternion.
  **/
 struct quaternion random_quaternion(gsl_rng *rng)
 {
@@ -641,8 +611,7 @@ struct quaternion random_quaternion(gsl_rng *rng)
 
 
 /**
- * quaternion_valid:
- * @q: A %quaternion
+ * \param q A \ref quaternion
  *
  * Checks if the given quaternion is normalised.
  *
@@ -650,7 +619,7 @@ struct quaternion random_quaternion(gsl_rng *rng)
  * <code>(modulus > 0.999) && (modulus < 1.001)</code>, and so should not be
  * relied upon to spot anything other than the most obvious input error.
  *
- * Returns: 1 if the quaternion is normalised, 0 if not.
+ * \returns 1 if the quaternion is normalised, 0 if not.
  **/
 int quaternion_valid(struct quaternion q)
 {
@@ -667,13 +636,12 @@ int quaternion_valid(struct quaternion q)
 
 
 /**
- * quat_rot
- * @q: A vector (in the form of a "struct rvec")
- * @z: A %quaternion
+ * \param q A vector (in the form of an \ref rvec struct)
+ * \param z A \ref quaternion
  *
  * Rotates a vector according to a quaternion.
  *
- * Returns: A rotated version of @p.
+ * \returns a rotated version of \p p.
  **/
 struct rvec quat_rot(struct rvec q, struct quaternion z)
 {
diff --git a/libcrystfel/src/utils.h b/libcrystfel/src/utils.h
index 65ab9b00..cd21bd93 100644
--- a/libcrystfel/src/utils.h
+++ b/libcrystfel/src/utils.h
@@ -46,6 +46,11 @@
 #include "thread-pool.h"
 
 
+/**
+ * \file utils.h
+ * Miscellaneous utility functions
+ */
+
 /* -------------------------- Fundamental constants  ------------------------ */
 
 /* Electron charge in C */
@@ -75,13 +80,11 @@ extern size_t notrail(char *s);
 extern void chomp(char *s);
 
 /**
- * AssplodeFlag:
- * @ASSPLODE_NONE: Nothing
- * @ASSPLODE_DUPS: Don't merge deliminators
+ * Controls the behaviour of \ref assplode.
  **/
 typedef enum {
-	ASSPLODE_NONE	= 0,
-	ASSPLODE_DUPS	= 1<<0
+	ASSPLODE_NONE	= 0,    /**< Nothing */
+	ASSPLODE_DUPS	= 1<<0  /**< Don't merge deliminators */
 } AssplodeFlag;
 extern int assplode(const char *a, const char *delims, char ***pbits,
                     AssplodeFlag flags);
@@ -237,14 +240,7 @@ extern void strip_extension(char *bfn);
 /* ------------------------------ Quaternions ------------------------------- */
 
 /**
- * quaternion:
- *  @w: component
- *  @x: component
- *  @y: component
- *  @z: component
- *
  * A structure representing a quaternion.
- *
  **/
 struct quaternion;
 
diff --git a/libcrystfel/src/xds.c b/libcrystfel/src/xds.c
index 3c5864a5..c0fccc7b 100644
--- a/libcrystfel/src/xds.c
+++ b/libcrystfel/src/xds.c
@@ -59,6 +59,7 @@
 #include "detector.h"
 #include "cell-utils.h"
 
+/** \file xds.h */
 
 /* Fake pixel size and camera length, both in metres */
 #define FAKE_PIXEL_SIZE (70e-6)
diff --git a/libcrystfel/src/xds.h b/libcrystfel/src/xds.h
index c89b615c..811c0dc9 100644
--- a/libcrystfel/src/xds.h
+++ b/libcrystfel/src/xds.h
@@ -42,6 +42,11 @@
 extern "C" {
 #endif
 
+/**
+ * \file xds.h
+ * XDS indexer interface
+ */
+
 extern int run_xds(struct image *image, void *ipriv);
 
 extern void *xds_prepare(IndexingMethod *indm, UnitCell *cell);
diff --git a/libcrystfel/src/xgandalf.c b/libcrystfel/src/xgandalf.c
index 51819956..1900d784 100644
--- a/libcrystfel/src/xgandalf.c
+++ b/libcrystfel/src/xgandalf.c
@@ -39,6 +39,8 @@
 #include "xgandalf/adaptions/crystfel/ExperimentSettings.h"
 #include "xgandalf/adaptions/crystfel/IndexerPlain.h"
 
+/** \file xgandalf.h */
+
 struct xgandalf_private_data {
 	IndexerPlain *indexer;
 	reciprocalPeaks_1_per_A_t reciprocalPeaks_1_per_A;
diff --git a/libcrystfel/src/xgandalf.h b/libcrystfel/src/xgandalf.h
index 1aced417..09dbf7d4 100644
--- a/libcrystfel/src/xgandalf.h
+++ b/libcrystfel/src/xgandalf.h
@@ -35,6 +35,11 @@
 
 #include <stddef.h>
 
+/**
+ * \file xgandalf.h
+ * XGANDALF indexer interface
+ */
+
 struct xgandalf_options {
 	unsigned int sampling_pitch;
 	unsigned int grad_desc_iterations;