More documentation

5 files changed, 95 insertions, 2 deletions

diff --git a/doc/reference/CrystFEL-docs.sgml b/doc/reference/CrystFEL-docs.sgml
index 61223e86..fa973b86 100644
--- a/doc/reference/CrystFEL-docs.sgml
+++ b/doc/reference/CrystFEL-docs.sgml
@@ -28,6 +28,7 @@
     <title>Handling reflection data</title>
         <abstract>There are three main reflection list thingies.</abstract>
         <xi:include href="xml/reflist.xml"/>
+        <xi:include href="xml/reflist-utils.xml"/>
         <xi:include href="xml/reflitemlist.xml"/>
   </chapter>
 
diff --git a/doc/reference/CrystFEL-sections.txt b/doc/reference/CrystFEL-sections.txt
index a308b78d..e39c384a 100644
--- a/doc/reference/CrystFEL-sections.txt
+++ b/doc/reference/CrystFEL-sections.txt
@@ -16,7 +16,17 @@ get_indices
 get_partiality
 get_intensity
 get_partial
+get_scalable
+get_redundancy
+get_sum_squared_dev
+get_esd_intensity
+get_phase
 <SUBSECTION>
+copy_data
+</SECTION>
+
+<SECTION>
+<FILE>reflist-utils</FILE>
 write_reflist
 write_reflections_to_file
 read_reflections
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));