Update docs

4 files changed, 102 insertions, 42 deletions

diff --git a/doc/reference/libcrystfel/CrystFEL-sections.txt b/doc/reference/libcrystfel/CrystFEL-sections.txt
index 3968dd5d..072f8b38 100644
--- a/doc/reference/libcrystfel/CrystFEL-sections.txt
+++ b/doc/reference/libcrystfel/CrystFEL-sections.txt
@@ -380,7 +380,6 @@ find_panel_by_name
 simple_geometry
 record_image
 get_pixel_extents
-get_q
 get_q_for_panel
 get_tt
 smallest_q
@@ -416,7 +415,6 @@ find_event
 get_event_string
 get_event_from_event_string
 event_path_placeholder_subst
-partial_event_substitution
 retrieve_full_path
 initialize_filename_plus_event
 free_filename_plus_event
diff --git a/libcrystfel/src/detector.h b/libcrystfel/src/detector.h
index e9dd1154..a2be2b47 100644
--- a/libcrystfel/src/detector.h
+++ b/libcrystfel/src/detector.h
@@ -3,12 +3,12 @@
  *
  * Detector properties
  *
- * Copyright © 2012-2016 Deutsches Elektronen-Synchrotron DESY,
+ * Copyright © 2012-2017 Deutsches Elektronen-Synchrotron DESY,
  *                       a research centre of the Helmholtz Association.
  * Copyright © 2012 Richard Kirian
  *
  * Authors:
- *   2009-2016 Thomas White <taw@physics.org>
+ *   2009-2017 Thomas White <taw@physics.org>
  *   2011-2012 Richard Kirian <rkirian@asu.edu>
  *   2014      Valerio Mariani
  *   2011      Andrew Aquila
@@ -42,7 +42,6 @@ struct rg_collection;
 struct detector;
 struct panel;
 struct badregion;
-struct detector;
 struct beam_params;
 struct hdfile;
 struct event;
@@ -80,6 +79,47 @@ struct rg_collection
 };
 
 
+/**
+ * panel:
+ *  @name: Text name for the panel (fixed length array)
+ *  @cnx: Location of corner, in pixels, x coordinate
+ *  @cny: Location of corner, in pixels, y coordinate
+ *  @coffset: The offset to be applied from @clen (which may come from elsewhere)
+ *  @clen: The distance from the interaction point to the corner of the first pixel
+ *  @clen_from: Location to get @clen from, e.g. from HDF5 file
+ *  @mask: Location of mask data
+ *  @mask_file: Filename for mask data
+ *  @satmap: Location of per-pixel saturation map
+ *  @satmap_file: Filename for saturation map
+ *  @res: Resolution of panel in pixels per metre
+ *  @badrow: Readout direction (for filtering out clusters of peaks)
+ *  @no_index: Non-zero if panel is entirely "bad"
+ *  @adu_per_photon: Number of detector intensity units per photon
+ *  @adu_per_eV: Number of detector intensity units per eV of photon energy
+ *  @max_adu: Saturation value
+ *  @dim_structure: Dimension structure
+ *  @fsx: Real-space x-direction of data fast-scan direction
+ *  @fsy: Real-space y-direction of data fast-scan direction
+ *  @fsz: Real-space z-direction of data fast-scan direction
+ *  @ssx: Real-space x-direction of data slow-scan direction
+ *  @ssy: Real-space y-direction of data slow-scan direction
+ *  @ssz: Real-space z-direction of data slow-scan direction
+ *  @rail_x: x direction of camera length "rail"
+ *  @rail_y: y direction of camera length "rail"
+ *  @rail_z: z direction of camera length "rail"
+ *  @clen_for_centering: Value of clen (without coffset) at which beam is centered
+ *  @xfs: Data fast-scan direction of real-space x-direction
+ *  @yfs: Data fast-scan direction of real-space y-direction
+ *  @xss: Data slow-scan direction of real-space x-direction
+ *  @yss: Data slow-scan direction of real-space y-direction
+ *  @orig_min_fs: Minimum fs coordinate of data in file
+ *  @orig_max_fs: Maximum fs coordinate of data in file
+ *  @orig_min_ss: Minimum ss coordinate of data in file (inclusive)
+ *  @orig_max_ss: Maximum ss coordinate of data in file (inclusive)
+ *  @data: Location of data in file
+ *  @w: Width of panel
+ *  @h: Height of panel
+ */
 struct panel
 {
         char     name[1024];  /* Name for this panel */
diff --git a/libcrystfel/src/image.h b/libcrystfel/src/image.h
index ead5cd4d..9719bb59 100644
--- a/libcrystfel/src/image.h
+++ b/libcrystfel/src/image.h
@@ -70,7 +70,26 @@ typedef enum {
 	SPECTRUM_TWOCOLOUR
 } SpectrumType;
 
-/* Structure describing a feature in an image */
+
+/**
+ * imagefeature:
+ *  @parent: Image this feature belongs to
+ *  @fs: Fast scan coordinate
+ *  @ss: Slow scan coordinate
+ *  @p: Pointer to panel
+ *  @intensity: Intensity of peak
+ *  @rx: Reciprocal x coordinate in m^-1
+ *  @ry: Reciprocal y coordinate in m^-1
+ *  @rz: Reciprocal z coordinate in m^-1
+ *  @name: Text name for feature
+ *
+ *  Represents a peak in an image.
+ *
+ *  Note carefully that the @fs and @ss coordinates are the distances, measured
+ *  in pixels, from the corner of the panel.  They are NOT pixel indices.
+ *  If the peak is in the middle of the first pixel, its coordinates would be
+ *  0.5,0.5.
+ */
 struct imagefeature {
 
 	struct image                    *parent;
@@ -84,10 +103,10 @@ struct imagefeature {
 	double                          ry;
 	double                          rz;
 
-	/* Internal use only */
-	int                             valid;
-
 	const char                      *name;
+
+	/*< private >*/
+	int                             valid;
 };
 
 
@@ -110,44 +129,46 @@ struct sample
 };
 
 
+/**
+ * beam_params:
+ *  @photon_energy: eV per photon
+ *  @photon_energy_from: HDF5 dataset name
+ *  @photon_energy_scale: Scale factor for photon energy, if it comes from HDF5
+ */
 struct beam_params
 {
-	double photon_energy;  /* eV per photon */
-	char  *photon_energy_from; /* HDF5 dataset name */
-	double photon_energy_scale;  /* Scale factor for photon energy, if the
-	                              * energy is to be from the HDF5 file */
+	double photon_energy;
+	char  *photon_energy_from;
+	double photon_energy_scale;
 };
 
 
 /**
  * image:
- *
- * <programlisting>
- * struct image
- * {
- *    Crystal                 **crystals;
- *    int                     n_crystals;
- *    IndexingMethod          indexed_by;
- *
- *    struct detector         *det;
- *    struct beam_params      *beam;
- *    char                    *filename;
- *    const struct imagefile_field_list *copyme;
- *
- *    int                     id;
- *
- *    double                  lambda;
- *    double                  div;
- *    double                  bw;
- *
- *    int                     width;
- *    int                     height;
- *
- *    long long int           num_peaks;
- *    long long int           num_saturated_peaks;
- *    ImageFeatureList        *features;
- * };
- * </programlisting>
+ *   @crystals: Array of crystals in the image
+ *   @n_crystals: The number of crystals in the image
+ *   @indexed_by: Indexing method which indexed this pattern
+ *   @det: Detector structure
+ *   @beam: Beam parameters structure
+ *   @filename: Filename for the image file
+ *   @copyme: Fields to copy from the image file to the stream
+ *   @id: ID number of the thread handling this image
+ *   @serial: Serial number for this image
+ *   @lambda: Wavelength
+ *   @div: Divergence
+ *   @bw: Bandwidth
+ *   @num_peaks: The number of peaks
+ *   @num_saturated_peaks: The number of saturated peaks
+ *   @features: The peaks found in the image
+ *   @dp: The image data, by panel
+ *   @bad: The bad pixel mask, array by panel
+ *   @sat: The per-pixel saturation mask, array by panel
+ *   @event: Event ID for the image
+ *   @stuff_from_stream: Items read back from the stream
+ *   @avg_clen: Mean of camera length values for all panels
+ *   @spectrum: Spectrum information
+ *   @nsamples: Number of spectrum samples
+ *   @spectrum_size: SIze of spectrum array
  *
  * The field <structfield>data</structfield> contains the raw image data, if it
  * is currently available.  The data might be available throughout the
@@ -204,8 +225,8 @@ struct image {
 	double                  bw;            /* Bandwidth as a fraction */
 
 	/* Detected peaks */
-	long long int           num_peaks;
-	long long int           num_saturated_peaks;
+	long long               num_peaks;
+	long long               num_saturated_peaks;
 	ImageFeatureList        *features;
 
 };
diff --git a/libcrystfel/src/index.h b/libcrystfel/src/index.h
index 8ce553ae..8dd7de21 100644
--- a/libcrystfel/src/index.h
+++ b/libcrystfel/src/index.h
@@ -75,6 +75,7 @@
  * @INDEXING_SIMULATION: Dummy value
  * @INDEXING_DEBUG: Results injector for debugging
  * @INDEXING_ASDF: Use in-built "asdf" indexer
+ * @INDEXING_ERROR: Special value for unrecognised indexing engine name
  * @INDEXING_CHECK_CELL_COMBINATIONS: Check linear combinations of unit cell
  *   axes for agreement with given cell.
  * @INDEXING_CHECK_CELL_AXES: Check unit cell axes for agreement with given