diff options
Diffstat (limited to 'libcrystfel')
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; |