Add documentation via gtk-doc

6 files changed, 280 insertions, 17 deletions

diff --git a/src/image.c b/src/image.c
index 6acf2c46..9f0127d3 100644
--- a/src/image.c
+++ b/src/image.c
@@ -18,6 +18,19 @@
 #include "image.h"
 #include "utils.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.
+ */
 
 struct _imagelist
 {
diff --git a/src/image.h b/src/image.h
index 964ed124..dc93de0f 100644
--- a/src/image.h
+++ b/src/image.h
@@ -53,15 +53,69 @@ struct imagefeature {
 typedef struct _imagefeaturelist ImageFeatureList;
 
 
-/* Structure describing an image */
+/**
+ * image:
+ *
+ * <programlisting>
+ * struct image
+ * {
+ *    float                   *data;
+ *    uint16_t                *flags;
+ *    double                  *twotheta;
+ *
+ *    UnitCell                *indexed_cell;
+ *    UnitCell                *candidate_cells[MAX_CELL_CANDIDATES];
+ *    int                     ncells;
+
+ *    struct detector         *det;
+ *    struct beam_params      *beam;
+ *    char                    *filename;
+ *
+ *    int                     id;
+ *
+ *    double                  m;
+ *
+ *    double                  lambda;
+ *    double                  div;
+ *    double                  bw;
+ *    double                  i0;
+ *    int                     i0_available;
+ *    double                  osf;
+ *    double                  profile_radius;
+ *
+ *    int                     width;
+ *    int                     height;
+ *
+ *    RefList                 *reflections;
+ *
+ *    ImageFeatureList        *features;
+ * };
+ * </programlisting>
+ *
+ * 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.  Similarly,
+ * <structfield>flags</structfield> contains an array of the same dimensions
+ * as <structfield>data</structfield> to contain the bad pixel flags.
+ * <structfield>twotheta</structfield> likewise contains an array of 2*theta
+ * (scattering angle) values in radians, since these values are generated as a
+ * by-product of the scattering vector calculation and can be used later for
+ * calculating intensities from differential scattering cross sections.
+ *
+ **/
+struct image;
+
 struct image {
 
 	float                   *data;
 	uint16_t                *flags;
 	double                  *twotheta;
+
 	UnitCell                *indexed_cell;
 	UnitCell                *candidate_cells[MAX_CELL_CANDIDATES];
 	int                     ncells;
+
 	struct detector         *det;
 	struct beam_params      *beam;  /* The nominal beam parameters */
 	char                    *filename;
diff --git a/src/reflist.c b/src/reflist.c
index 05caa96d..beee7f2e 100644
--- a/src/reflist.c
+++ b/src/reflist.c
@@ -17,6 +17,31 @@
 #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 a binary search tree indexed
+ * by the Miller indices h, k and l.  Provided the tree has been optimised (by
+ * using optimise_reflist()), any reflection can be found in a maximum 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.
+ */
+
 
 struct _refldata {
 
@@ -99,12 +124,19 @@ static Reflection *new_node(unsigned int serial)
 }
 
 
-/* Create a reflection list */
+/**
+ * reflist_new:
+ *
+ * Creates a new reflection list.
+ *
+ * Returns: the new reflection list, or NULL on error.
+ */
 RefList *reflist_new()
 {
 	RefList *new;
 
 	new = malloc(sizeof(struct _reflist));
+	if ( new == NULL ) return NULL;
 
 	/* Create pseudo-root with invalid indices.
 	 * The "real" root will be the left child of this. */
@@ -122,6 +154,12 @@ static void recursive_free(Reflection *refl)
 }
 
 
+/**
+ * reflist_free:
+ * @list: The reflection list to free.
+ *
+ * Destroys a reflection list.
+ */
 void reflist_free(RefList *list)
 {
 	if ( list == NULL ) return;
@@ -132,8 +170,22 @@ void reflist_free(RefList *list)
 
 /********************************** Search ************************************/
 
-/* Return the first reflection in 'list' with the given indices, or NULL */
-Reflection *find_refl(const RefList *list, INDICES)
+/**
+ * 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
+ *
+ * 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
+ * indices could be found.
+ **/
+Reflection *find_refl(const RefList *list, signed int h, signed int k, signed int l)
 {
 	unsigned int search = SERIAL(h, k, l);
 	Reflection *refl = list->head->child[0];
@@ -174,7 +226,16 @@ Reflection *find_refl(const RefList *list, INDICES)
 }
 
 
-/* Find the next reflection in 'refl's list with the same indices, or NULL */
+/**
+ * next_found_refl:
+ * @refl: A reflection returned by find_refl() or next_found_refl()
+ *
+ * This function returns the next reflection in @refl's list with the same
+ * indices.
+ *
+ * Returns: The found reflection, or NULL if there are no more reflections with
+ * the same indices.
+ **/
 Reflection *next_found_refl(Reflection *refl)
 {
 	if ( refl->next != NULL ) assert(refl->serial == refl->next->serial);
@@ -185,12 +246,25 @@ Reflection *next_found_refl(Reflection *refl)
 
 /********************************** Getters ***********************************/
 
+/**
+ * get_excitation_error:
+ * @refl: A %Reflection
+ *
+ * Returns: The excitation error for the reflection.
+ **/
 double get_excitation_error(const Reflection *refl)
 {
 	return refl->data.excitation_error;
 }
 
 
+/**
+ * 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
+ *
+ **/
 void get_detector_pos(const Reflection *refl, double *fs, double *ss)
 {
 	*fs = refl->data.fs;
@@ -198,6 +272,14 @@ void get_detector_pos(const Reflection *refl, double *fs, double *ss)
 }
 
 
+/**
+ * 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
+ *
+ **/
 void get_indices(const Reflection *refl,
                  signed int *h, signed int *k, signed int *l)
 {
@@ -207,18 +289,43 @@ void get_indices(const Reflection *refl,
 }
 
 
+/**
+ * get_partiality:
+ * @refl: A %Reflection
+ *
+ * Returns: The partiality of the reflection.
+ **/
 double get_partiality(const Reflection *refl)
 {
 	return refl->data.p;
 }
 
 
+/**
+ * get_intensity:
+ * @refl: A %Reflection
+ *
+ * Returns: The intensity of the reflection.
+ **/
 double get_intensity(const Reflection *refl)
 {
 	return refl->data.intensity;
 }
 
 
+/**
+ * get_partial:
+ * @refl: A %Reflection
+ * @r1: Location at which to store the first excitation error
+ * @r2: Location at which to store the second excitation error
+ * @p: Location at which to store the partiality
+ * @clamp_low: Location at which to store the first clamp status
+ * @clamp_high: Location at which to store the second clamp status
+ *
+ * This function is used during post refinement to get access to the details of
+ * the partiality calculation.
+ *
+ **/
 void get_partial(const Reflection *refl, double *r1, double *r2, double *p,
                  int *clamp_low, int *clamp_high)
 {
@@ -370,7 +477,7 @@ static void insert_node(Reflection *head, Reflection *new)
 }
 
 
-Reflection *add_refl(RefList *list, INDICES)
+Reflection *add_refl(RefList *list, signed int h, signed int k, signed int l)
 {
 	Reflection *new;
 
@@ -688,6 +795,21 @@ static void vine_to_tree(Reflection *root, int size)
 }
 
 
+/**
+ * optimise_reflist:
+ * @list: The reflection list to optimise
+ *
+ * Optimises the ordering of reflections in the list such that the list can be
+ * searched in the fastest possible way.
+ *
+ * This is a relatively expensive operation, so in typical usage you would call
+ * it only after adding or removing many reflections from a list, when the list
+ * is unlikely to be significantly modified for a long period of time.
+ *
+ * Note that only adding or deleting reflections may reduce the efficiency of
+ * the list.  Changing the contents of the reflections (e.g. updating intensity
+ * values) does not.
+ **/
 void optimise_reflist(RefList *list)
 {
 	int n_items;
diff --git a/src/reflist.h b/src/reflist.h
index 0f8741cf..f380ba85 100644
--- a/src/reflist.h
+++ b/src/reflist.h
@@ -16,30 +16,40 @@
 #include <config.h>
 #endif
 
-
+/**
+ * RefList:
+ *
+ * This data structure is opaque.  You must use the available accessor functions
+ * to read and write its contents.
+ */
 typedef struct _reflist RefList;
+
+/**
+ * Reflection:
+ *
+ * This data structure is opaque.  You must use the available accessor functions
+ * to read and write its contents.
+ */
 typedef struct _reflection Reflection;
 typedef struct _reflistiterator RefListIterator;
 
-#define INDICES signed int h, signed int k, signed int l
-
 /* Creation/deletion */
 extern RefList *reflist_new(void);
 extern void reflist_free(RefList *list);
 
 /* Search */
-extern Reflection *find_refl(const RefList *list, INDICES);
+extern Reflection *find_refl(const RefList *list, signed int h, signed int k, signed int l);
 extern Reflection *next_found_refl(Reflection *refl);
 
 /* Get */
 extern double get_excitation_error(const Reflection *refl);
 extern void get_detector_pos(const Reflection *refl, double *fs, double *ss);
+extern double get_partiality(const Reflection *refl);
 extern void get_indices(const Reflection *refl,
                         signed int *h, signed int *k, signed int *l);
-extern double get_partiality(const Reflection *refl);
 extern double get_intensity(const Reflection *refl);
-extern void get_partial(const Reflection *refl, double *r1, double *r2, double *p,
-                        int *clamp_low, int *clamp_high);
+extern void get_partial(const Reflection *refl, double *r1, double *r2,
+                        double *p, int *clamp_low, int *clamp_high);
 extern int get_scalable(const Reflection *refl);
 extern int get_redundancy(const Reflection *refl);
 extern double get_sum_squared_dev(const Reflection *refl);
@@ -60,7 +70,8 @@ extern void set_esd_intensity(Reflection *refl, double esd);
 extern void set_ph(Reflection *refl, double phase);
 
 /* Insertion */
-extern Reflection *add_refl(RefList *list, INDICES);
+extern Reflection *add_refl(RefList *list,
+                            signed int h, signed int k, signed int l);
 
 /* Deletion */
 extern void delete_refl(Reflection *refl);
diff --git a/src/utils.c b/src/utils.c
index 1d023783..7a27e057 100644
--- a/src/utils.c
+++ b/src/utils.c
@@ -23,6 +23,28 @@
 #include "image.h"
 
 
+/**
+ * SECTION:utils
+ * @short_description: Miscellaneous utilities
+ * @title: Utilities
+ * @section_id:
+ * @see_also:
+ * @include: "utils.h"
+ * @Image:
+ *
+ * Wibble
+ */
+
+/**
+ * show_matrix_eqn:
+ * @M: A matrix
+ * @v: A vector
+ * @r: The number of elements in @v and the side length of @M.
+ *
+ * Displays a matrix equation of the form @M.a = @v.
+ *
+ * @M must be square.
+ **/
 void show_matrix_eqn(gsl_matrix *M, gsl_vector *v, int r)
 {
 	int i, j;
@@ -312,6 +334,17 @@ int assplode(const char *a, const char *delims, char ***pbits,
 	return n;
 }
 
+/**
+ * SECTION:reflitemlist
+ * @short_description: The index list and indexed arrays
+ * @title: ReflItemList
+ * @section_id:
+ * @see_also:
+ * @include: "utils.h"
+ * @Image:
+ *
+ * Wibble
+ */
 
 struct _reflitemlist {
 	struct refl_item *items;
@@ -333,10 +366,18 @@ static void alloc_items(ReflItemList *items)
 }
 
 
+/**
+ * new_items:
+ *
+ * Creates a new %ReflItemList.
+ *
+ * Returns: The new list, or NULL.
+ **/
 ReflItemList *new_items()
 {
 	ReflItemList *new;
 	new = malloc(sizeof(ReflItemList));
+	if ( new == NULL ) return NULL;
 	new->max_items = 1024;
 	new->n_items = 0;
 	new->items = NULL;
diff --git a/src/utils.h b/src/utils.h
index 169892d4..a7a93404 100644
--- a/src/utils.h
+++ b/src/utils.h
@@ -45,8 +45,25 @@
 
 /* ------------------------------ Quaternions ------------------------------- */
 
-struct quaternion
-{
+/**
+ * quaternion:
+ *
+ * <programlisting>
+ * struct quaternion
+ * {
+ *    double w
+ *    double x
+ *    double y
+ *    double z
+ * };
+ * </programlisting>
+ *
+ * A structure representing a quaternion.
+ *
+ **/
+struct quaternion;
+
+struct quaternion {
 	double w;
 	double x;
 	double y;
@@ -186,7 +203,12 @@ static inline double angle_between(double x1, double y1, double z1,
 
 /* ----------- Reflection lists indexed by sequence (not indices) ----------- */
 
-typedef struct _reflitemlist ReflItemList;  /* Opaque */
+/**
+ * ReflItemList
+ *
+ * Opaque type.
+ **/
+typedef struct _reflitemlist ReflItemList;
 
 struct refl_item {
 	signed int h;