aboutsummaryrefslogtreecommitdiff
path: root/libcrystfel
diff options
context:
space:
mode:
Diffstat (limited to 'libcrystfel')
-rw-r--r--libcrystfel/src/asdf.c6
-rw-r--r--libcrystfel/src/asdf.h5
-rw-r--r--libcrystfel/src/cell-utils.c162
-rw-r--r--libcrystfel/src/cell-utils.h6
-rw-r--r--libcrystfel/src/cell.c62
-rw-r--r--libcrystfel/src/cell.h28
-rw-r--r--libcrystfel/src/crystal.c30
-rw-r--r--libcrystfel/src/crystal.h6
-rw-r--r--libcrystfel/src/detector.c30
-rw-r--r--libcrystfel/src/detector.h124
-rw-r--r--libcrystfel/src/dirax.c2
-rw-r--r--libcrystfel/src/dirax.h3
-rw-r--r--libcrystfel/src/events.c8
-rw-r--r--libcrystfel/src/events.h7
-rw-r--r--libcrystfel/src/felix.c2
-rw-r--r--libcrystfel/src/felix.h5
-rw-r--r--libcrystfel/src/filters.c1
-rw-r--r--libcrystfel/src/filters.h4
-rw-r--r--libcrystfel/src/geometry.c30
-rw-r--r--libcrystfel/src/geometry.h20
-rw-r--r--libcrystfel/src/hdf5-file.c80
-rw-r--r--libcrystfel/src/hdf5-file.h5
-rw-r--r--libcrystfel/src/histogram.c2
-rw-r--r--libcrystfel/src/histogram.h5
-rw-r--r--libcrystfel/src/image.c15
-rw-r--r--libcrystfel/src/image.h200
-rw-r--r--libcrystfel/src/index.c3
-rw-r--r--libcrystfel/src/index.h85
-rw-r--r--libcrystfel/src/integer_matrix.c141
-rw-r--r--libcrystfel/src/integer_matrix.h9
-rw-r--r--libcrystfel/src/integration.c3
-rw-r--r--libcrystfel/src/integration.h70
-rw-r--r--libcrystfel/src/mosflm.c1
-rw-r--r--libcrystfel/src/mosflm.h5
-rw-r--r--libcrystfel/src/peakfinder8.c16
-rw-r--r--libcrystfel/src/peakfinder8.h5
-rw-r--r--libcrystfel/src/peaks.c1
-rw-r--r--libcrystfel/src/peaks.h5
-rw-r--r--libcrystfel/src/predict-refine.c3
-rw-r--r--libcrystfel/src/predict-refine.h5
-rw-r--r--libcrystfel/src/rational.c48
-rw-r--r--libcrystfel/src/rational.h9
-rw-r--r--libcrystfel/src/reflist-utils.c93
-rw-r--r--libcrystfel/src/reflist-utils.h13
-rw-r--r--libcrystfel/src/reflist.c345
-rw-r--r--libcrystfel/src/reflist.h34
-rw-r--r--libcrystfel/src/render.c1
-rw-r--r--libcrystfel/src/render.h4
-rw-r--r--libcrystfel/src/statistics.c12
-rw-r--r--libcrystfel/src/statistics.h5
-rw-r--r--libcrystfel/src/stream.c124
-rw-r--r--libcrystfel/src/stream.h26
-rw-r--r--libcrystfel/src/symmetry.c196
-rw-r--r--libcrystfel/src/symmetry.h13
-rw-r--r--libcrystfel/src/taketwo.c50
-rw-r--r--libcrystfel/src/taketwo.h2
-rw-r--r--libcrystfel/src/thread-pool.c47
-rw-r--r--libcrystfel/src/thread-pool.h28
-rw-r--r--libcrystfel/src/utils.c76
-rw-r--r--libcrystfel/src/utils.h20
-rw-r--r--libcrystfel/src/xds.c1
-rw-r--r--libcrystfel/src/xds.h5
-rw-r--r--libcrystfel/src/xgandalf.c2
-rw-r--r--libcrystfel/src/xgandalf.h5
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;