More documentation

3 files changed, 84 insertions, 2 deletions

diff --git a/src/image.h b/src/image.h
index 92047aa1..d6e22aee 100644
--- a/src/image.h
+++ b/src/image.h
@@ -103,6 +103,14 @@ typedef struct _imagefeaturelist ImageFeatureList;
  * by-product of the scattering vector calculation and can be used later for
  * calculating intensities from differential scattering cross sections.
  *
+ * <structfield>candidate_cells</structfield> is an array of unit cells directly
+ * returned by the low-level indexing system. <structfield>ncells</structfield>
+ * is the number of candidate unit cells which were found.  The maximum number
+ * of cells which may be returned is <function>MAX_CELL_CANDIDATES</function>.
+ * <structfield>indexed_cell</structfield> contains the "correct" unit cell
+ * after cell reduction or matching has been performed.  The job of the cell
+ * reduction is to convert the list of candidate cells into a single indexed
+ * cell, or <function>NULL</function> on failure.
  **/
 struct image;
 
diff --git a/src/reflist-utils.c b/src/reflist-utils.c
index 510dfa42..19ce0ee8 100644
--- a/src/reflist-utils.c
+++ b/src/reflist-utils.c
@@ -20,6 +20,19 @@
 #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.
+ **/
+
+
 double *intensities_from_list(RefList *list)
 {
 	Reflection *refl;
diff --git a/src/reflist.c b/src/reflist.c
index beee7f2e..bf94367f 100644
--- a/src/reflist.c
+++ b/src/reflist.c
@@ -322,8 +322,8 @@ double get_intensity(const Reflection *refl)
  * @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.
+ * This function is used during post refinement (in conjunction with
+ * set_partial()) to get access to the details of the partiality calculation.
  *
  **/
 void get_partial(const Reflection *refl, double *r1, double *r2, double *p,
@@ -337,30 +337,79 @@ void get_partial(const Reflection *refl, double *r1, double *r2, double *p,
 }
 
 
+/**
+ * get_scalable:
+ * @refl: A %Reflection
+ *
+ * Returns: non-zero if this reflection was marked as useful for scaling and
+ * post refinement.
+ *
+ **/
 int get_scalable(const Reflection *refl)
 {
 	return refl->data.scalable;
 }
 
 
+/**
+ * get_redundancy:
+ * @refl: A %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
+ * as that the reflection was impossible to integrate.  Note further that each
+ * reflection in the list has its own redundancy, even if there are multiple
+ * 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.
+ *
+ **/
 int get_redundancy(const Reflection *refl)
 {
 	return refl->data.redundancy;
 }
 
 
+/**
+ * get_sum_squared_dev:
+ * @refl: A %Reflection
+ *
+ * The sum squared deviation is used to estimate the standard errors on the
+ * intensities during 'Monte Carlo' merging.
+ *
+ * Returns: the sum of the squared deviations between the intensities and the
+ * mean intensity from all measurements of the reflection (and probably its
+ * symmetry equivalents according to some point group).
+ *
+ **/
 double get_sum_squared_dev(const Reflection *refl)
 {
 	return refl->data.sum_squared_dev;
 }
 
 
+/**
+ * get_esd_intensity:
+ * @refl: A %Reflection
+ *
+ * Returns: the standard error in the intensity measurement (as returned by
+ * get_intensity()) for this reflection.
+ *
+ **/
 double get_esd_intensity(const Reflection *refl)
 {
 	return refl->data.esd_i;
 }
 
 
+/**
+ * get_phase:
+ * @refl: A %Reflection
+ *
+ * Returns: the phase for this reflection.
+ *
+ **/
 double get_phase(const Reflection *refl)
 {
 	return refl->data.phase;
@@ -369,6 +418,18 @@ double get_phase(const Reflection *refl)
 
 /********************************** Setters ***********************************/
 
+/**
+ * copy_data:
+ * @to: %Reflection to copy data into
+ * @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
+ * reflection to another.  This might be used when creating a new list from an
+ * old one, perhaps using the asymmetric indices instead of the raw indices for
+ * the new list.
+ *
+ **/
 void copy_data(Reflection *to, const Reflection *from)
 {
 	memcpy(&to->data, &from->data, sizeof(struct _refldata));