Tidy up documentation

6 files changed, 54 insertions, 8 deletions

diff --git a/libcrystfel/src/cell-utils.h b/libcrystfel/src/cell-utils.h
index f92ab22d..8eb08ca7 100644
--- a/libcrystfel/src/cell-utils.h
+++ b/libcrystfel/src/cell-utils.h
@@ -55,7 +55,7 @@ extern int cell_is_sensible(UnitCell *cell);
 
 extern int validate_cell(UnitCell *cell);
 
-extern UnitCell *uncenter_cell(UnitCell *in, UnitCellTransformation **tr);
+extern UnitCell *uncenter_cell(UnitCell *in, UnitCellTransformation **t);
 
 extern int bravais_lattice(UnitCell *cell);
 
diff --git a/libcrystfel/src/cell.h b/libcrystfel/src/cell.h
index cde25b07..57741b41 100644
--- a/libcrystfel/src/cell.h
+++ b/libcrystfel/src/cell.h
@@ -40,8 +40,15 @@
 #include "utils.h"
 #include "integer_matrix.h"
 
-/* A 3D vector in reciprocal space.
- * Note: Heavily abused to serve as a real space vector as well */
+/**
+ * rvec:
+ * @u: x component (in reciprocal space)
+ * @v: y component (in reciprocal space)
+ * @w: z component (in reciprocal space)
+ *
+ * Structure representing a 3D vector in reciprocal space.
+ * Note: Heavily abused to serve as a real space vector as well.
+ **/
 struct rvec
 {
 	double   u;
@@ -49,6 +56,20 @@ struct rvec
 	double   w;
 };
 
+
+/**
+ * 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.
+ **/
 typedef enum
 {
 	L_TRICLINIC,
diff --git a/libcrystfel/src/index.h b/libcrystfel/src/index.h
index 9d23f3fb..4a724645 100644
--- a/libcrystfel/src/index.h
+++ b/libcrystfel/src/index.h
@@ -43,7 +43,15 @@
 #include "detector.h"
 
 
-/* Indexing methods */
+/**
+ * IndexingMethod:
+ * @INDEXING_NONE: No indexing to be performed
+ * @INDEXING_DIRAX: Invoke DirAx
+ * @INDEXING_MOSFLM: Invoke MOSFLM
+ * @INDEXING_REAX: DPS algorithm using known cell parameters
+ *
+ * An enumeration of all the available indexing methods.
+ **/
 typedef enum {
 	INDEXING_NONE,
 	INDEXING_DIRAX,
@@ -61,6 +69,12 @@ enum {
 };
 
 
+/**
+ * IndexingPrivate:
+ *
+ * This is an opaque data structure containing information needed by the
+ * indexing method.
+ **/
 typedef struct _indexingprivate IndexingPrivate;
 
 extern IndexingPrivate *indexing_private(IndexingMethod indm);
diff --git a/libcrystfel/src/integer_matrix.c b/libcrystfel/src/integer_matrix.c
index 32784f20..96159cc6 100644
--- a/libcrystfel/src/integer_matrix.c
+++ b/libcrystfel/src/integer_matrix.c
@@ -62,6 +62,8 @@ 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
  *
  * Allocates a new %IntegerMatrix with all elements set to zero.
  *
@@ -406,7 +408,7 @@ void intmat_print(const IntegerMatrix *m)
  * intmat_is_identity
  * @m: An %IntegerMatrix
  *
- * Returns true if @m is an identity matrix.
+ * Returns: true if @m is an identity matrix.
  *
  */
 int intmat_is_identity(const IntegerMatrix *m)
@@ -439,7 +441,7 @@ int intmat_is_identity(const IntegerMatrix *m)
  * intmat_is_inversion
  * @m: An %IntegerMatrix
  *
- * Returns true if @m = -I, where I is an identity matrix.
+ * Returns: true if @m = -I, where I is an identity matrix.
  *
  */
 int intmat_is_inversion(const IntegerMatrix *m)
@@ -473,7 +475,7 @@ int intmat_is_inversion(const IntegerMatrix *m)
  * @a: An %IntegerMatrix
  * @b: An %IntegerMatrix
  *
- * Returns true if @a = @b.
+ * Returns: true if @a = @b.
  *
  */
 int intmat_equals(const IntegerMatrix *a, const IntegerMatrix *b)
diff --git a/libcrystfel/src/reflist-utils.c b/libcrystfel/src/reflist-utils.c
index f2292929..04096ae4 100644
--- a/libcrystfel/src/reflist-utils.c
+++ b/libcrystfel/src/reflist-utils.c
@@ -437,6 +437,9 @@ 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
  *
  * Applies a resolution cutoff to @list, returning the new version and freeing
  * the old version.
diff --git a/libcrystfel/src/utils.h b/libcrystfel/src/utils.h
index 951d9d03..b75693db 100644
--- a/libcrystfel/src/utils.h
+++ b/libcrystfel/src/utils.h
@@ -100,6 +100,11 @@ extern void show_matrix_eqn(gsl_matrix *M, gsl_vector *v, int r);
 extern size_t notrail(char *s);
 extern void chomp(char *s);
 
+/**
+ * AssplodeFlag:
+ * @ASSPLODE_NONE: Nothing
+ * @ASSPLODE_DUPS: Don't merge deliminators
+ **/
 typedef enum {
 	ASSPLODE_NONE	= 0,
 	ASSPLODE_DUPS	= 1<<0
@@ -141,7 +146,8 @@ static inline double modulus_squared(double x, double y, double z) {
 static inline double distance3d(double x1, double y1, double z1,
                                 double x2, double y2, double z2)
 {
-	return modulus(x1-x2, y1-y2, z1-z2);
+	double d = modulus(x1-x2, y1-y2, z1-z2);
+	return d;
 }
 
 /* Answer in radians */