Update docs

5 files changed, 79 insertions, 0 deletions

diff --git a/doc/reference/CrystFEL-docs.sgml b/doc/reference/CrystFEL-docs.sgml
index ba20fbea..61223e86 100644
--- a/doc/reference/CrystFEL-docs.sgml
+++ b/doc/reference/CrystFEL-docs.sgml
@@ -32,6 +32,11 @@
   </chapter>
 
   <chapter>
+    <title>Unit cells</title>
+        <xi:include href="xml/unitcell.xml"/>
+  </chapter>
+
+  <chapter>
     <title>Miscellaneous</title>
         <xi:include href="xml/quaternion.xml"/>
         <xi:include href="xml/utils.xml"/>
diff --git a/doc/reference/CrystFEL-sections.txt b/doc/reference/CrystFEL-sections.txt
index b6021270..a308b78d 100644
--- a/doc/reference/CrystFEL-sections.txt
+++ b/doc/reference/CrystFEL-sections.txt
@@ -16,6 +16,11 @@ get_indices
 get_partiality
 get_intensity
 get_partial
+<SUBSECTION>
+write_reflist
+write_reflections_to_file
+read_reflections
+read_reflections_from_file
 </SECTION>
 
 <SECTION>
@@ -26,6 +31,13 @@ new_items
 </SECTION>
 
 <SECTION>
+<FILE>unitcell</FILE>
+UnitCell
+<SUBSECTION>
+cell_new
+</SECTION>
+
+<SECTION>
 <FILE>utils</FILE>
 show_matrix_eqn
 </SECTION>
diff --git a/src/cell.c b/src/cell.c
index cd0e0975..cb846db5 100644
--- a/src/cell.c
+++ b/src/cell.c
@@ -26,6 +26,20 @@
 #include "image.h"
 
 
+/**
+ * SECTION:unitcell
+ * @short_description: Unit cell
+ * @title: UnitCell
+ * @section_id:
+ * @see_also:
+ * @include: "cell.h"
+ * @Image:
+ *
+ * This structure represents a unit cell.
+ */
+
+
+
 /* Weighting factor of lengths relative to angles */
 #define LWEIGHT (10.0e-9)
 
@@ -64,6 +78,15 @@ struct _unitcell {
 
 /************************** Setters and Constructors **************************/
 
+
+/**
+ * cell_new:
+ *
+ * Create a new %UnitCell.
+ *
+ * Returns: the new unit cell, or NULL on failure.
+ *
+ */
 UnitCell *cell_new()
 {
 	UnitCell *cell;
diff --git a/src/cell.h b/src/cell.h
index 09d9144d..84948fb4 100644
--- a/src/cell.h
+++ b/src/cell.h
@@ -26,6 +26,13 @@ struct rvec
 	double   w;
 };
 
+
+/**
+ * UnitCell:
+ *
+ * This data structure is opaque.  You must use the available accessor functions
+ * to read and write its contents.
+ **/
 typedef struct _unitcell UnitCell;
 
 extern UnitCell *cell_new(void);
diff --git a/src/reflist-utils.c b/src/reflist-utils.c
index ba212bd1..510dfa42 100644
--- a/src/reflist-utils.c
+++ b/src/reflist-utils.c
@@ -164,6 +164,20 @@ int find_equiv_in_list(RefList *list, signed int h, signed int k,
 }
 
 
+/**
+ * write_reflections_to_file:
+ * @fh: File handle to write to
+ * @list: The reflection list to write
+ * @cell: Unit cell to use for generating 1/d values, or NULL.
+ *
+ * This function writes the contents of @list to @fh, using @cell to generate
+ * 1/d values to ease later processing.  If @cell is NULL, 1/d values will not
+ * be included ('-' will be written in their place).
+ *
+ * Reflections which have a redundancy of zero will not be written.
+ *
+ * The resulting list can be read back with read_reflections_from_file().
+ **/
 void write_reflections_to_file(FILE *fh, RefList *list, UnitCell *cell)
 {
 	Reflection *refl;
@@ -207,6 +221,24 @@ void write_reflections_to_file(FILE *fh, RefList *list, UnitCell *cell)
 }
 
 
+/**
+ * write_reflist:
+ * @filename: Filename
+ * @list: The reflection list to write
+ * @cell: Unit cell to use for generating 1/d values, or NULL.
+ *
+ * This function writes the contents of @list to @file, using @cell to generate
+ * 1/d values to ease later processing.  If @cell is NULL, 1/d values will not
+ * be included ('-' will be written in their place).
+ *
+ * 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 @file and then calls
+ * write_reflections_to_file.
+ **/
 int write_reflist(const char *filename, RefList *list, UnitCell *cell)
 {
 	FILE *fh;