Use gtk-doc for libcrystfel only (not the contents of src)

4 files changed, 694 insertions, 0 deletions

diff --git a/doc/reference/libcrystfel/CrystFEL-docs.sgml b/doc/reference/libcrystfel/CrystFEL-docs.sgml
new file mode 100644
index 00000000..4e6cc877
--- /dev/null
+++ b/doc/reference/libcrystfel/CrystFEL-docs.sgml
@@ -0,0 +1,106 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+<book id="index">
+  <bookinfo>
+    <title>CrystFEL Reference Manual</title>
+    <releaseinfo>
+      For libcrystfel from CrystFEL 0.4.3.
+    </releaseinfo>
+    <abstract>
+    This is the internal documentation for CrystFEL.  Unless you are looking at
+    the code, writing new programs or fixing bugs, you should not need to read
+    this.  You might use the information here when reading the code or to better
+    understand how the software works, or refer to it when creating a new
+    program within the suite.
+    </abstract>
+  </bookinfo>
+
+  <chapter>
+    <title>Images</title>
+        <xi:include href="xml/image.xml"/>
+  </chapter>
+
+  <chapter>
+    <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"/>
+  </chapter>
+
+  <chapter>
+    <title>Unit cells</title>
+        <xi:include href="xml/unitcell.xml"/>
+        <xi:include href="xml/cell-utils.xml"/>
+  </chapter>
+
+  <chapter>
+    <title>Crystals</title>
+        <xi:include href="xml/crystal.xml"/>
+  </chapter>
+
+  <chapter>
+    <title>Statistics and R-factors</title>
+        <xi:include href="xml/statistics.xml"><xi:fallback /></xi:include>
+  </chapter>
+
+  <chapter>
+    <title>Symmetry</title>
+        <xi:include href="xml/symmetry.xml"><xi:fallback /></xi:include>
+  </chapter>
+
+  <chapter>
+    <title>Integer Matrices</title>
+        <xi:include href="xml/integer_matrix.xml"><xi:fallback /></xi:include>
+  </chapter>
+
+  <chapter>
+    <title>Indexing</title>
+        <xi:include href="xml/indexing.xml"><xi:fallback /></xi:include>
+  </chapter>
+
+  <chapter>
+    <title>Detector</title>
+        <xi:include href="xml/detector.xml"><xi:fallback /></xi:include>
+  </chapter>
+
+  <chapter>
+    <title>HDF5</title>
+        <xi:include href="xml/hdf5-file.xml"><xi:fallback /></xi:include>
+  </chapter>
+
+  <chapter>
+    <title>Stream</title>
+        <xi:include href="xml/stream.xml"><xi:fallback /></xi:include>
+  </chapter>
+
+  <chapter>
+    <title>Render</title>
+        <xi:include href="xml/render.xml"><xi:fallback /></xi:include>
+  </chapter>
+
+  <chapter>
+    <title>Parallel programming</title>
+        <xi:include href="xml/thread-pool.xml"><xi:fallback /></xi:include>
+  </chapter>
+
+  <chapter>
+    <title>Miscellaneous</title>
+        <xi:include href="xml/quaternion.xml"/>
+        <xi:include href="xml/utils.xml"/>
+  </chapter>
+
+  <chapter>
+    <title>Information for developers</title>
+        <xi:include href="xml/coding-standards.xml"><xi:fallback /></xi:include>
+  </chapter>
+
+  <index id="api-index-full">
+    <title>API Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+
+</book>
diff --git a/doc/reference/libcrystfel/CrystFEL-sections.txt b/doc/reference/libcrystfel/CrystFEL-sections.txt
new file mode 100644
index 00000000..5df1f2d5
--- /dev/null
+++ b/doc/reference/libcrystfel/CrystFEL-sections.txt
@@ -0,0 +1,329 @@
+<SECTION>
+<FILE>reflist</FILE>
+RefList
+Reflection
+RefListIterator
+<SUBSECTION>
+reflist_new
+reflist_free
+reflection_new
+reflection_free
+<SUBSECTION>
+add_refl
+add_refl_to_list
+<SUBSECTION>
+first_refl
+next_refl
+<SUBSECTION>
+find_refl
+next_found_refl
+<SUBSECTION>
+get_excitation_error
+get_detector_pos
+get_partiality
+get_indices
+get_symmetric_indices
+get_intensity
+get_partial
+get_scalable
+get_refinable
+get_redundancy
+get_esd_intensity
+get_phase
+get_temp1
+get_temp2
+<SUBSECTION>
+set_detector_pos
+set_partial
+set_intensity
+set_scalable
+set_refinable
+set_redundancy
+set_esd_intensity
+set_phase
+set_symmetric_indices
+set_temp1
+set_temp2
+<SUBSECTION>
+copy_data
+num_reflections
+tree_depth
+lock_reflection
+unlock_reflection
+</SECTION>
+
+<SECTION>
+<FILE>reflist-utils</FILE>
+write_reflist
+write_reflections_to_file
+read_reflections
+read_reflections_from_file
+asymmetric_indices
+res_cutoff
+check_list_symmetry
+copy_reflist
+find_equiv_in_list
+</SECTION>
+
+<SECTION>
+<FILE>unitcell</FILE>
+UnitCell
+LatticeType
+UnitCellTransformation
+<SUBSECTION>
+cell_new
+cell_new_from_cell
+cell_new_from_direct_axes
+cell_new_from_parameters
+cell_new_from_reciprocal_axes
+cell_free
+<SUBSECTION>
+cell_get_cartesian
+cell_get_parameters
+cell_get_pointgroup
+cell_get_reciprocal
+cell_get_centering
+cell_get_lattice_type
+cell_get_unique_axis
+<SUBSECTION>
+cell_set_cartesian
+cell_set_cartesian_a
+cell_set_cartesian_b
+cell_set_cartesian_c
+cell_set_parameters
+cell_set_pointgroup
+cell_set_reciprocal
+cell_set_centering
+cell_set_lattice_type
+cell_set_unique_axis
+<SUBSECTION>
+cell_transform
+cell_transform_inverse
+tfn_combine
+tfn_identity
+tfn_from_intmat
+tfn_inverse
+tfn_print
+tfn_vector
+tfn_free
+<SUBSECTION>
+
+cell_rep
+</SECTION>
+
+<SECTION>
+<FILE>cell-utils</FILE>
+cell_rotate
+rotate_cell
+cell_print
+resolution
+match_cell
+match_cell_ab
+cell_is_sensible
+validate_cell
+uncenter_cell
+bravais_lattice
+right_handed
+str_lattice
+forbidden_reflection
+load_cell_from_pdb
+</SECTION>
+
+<SECTION>
+<FILE>utils</FILE>
+show_matrix_eqn
+AssplodeFlag
+C_VACUO
+ELECTRON_CHARGE
+ERROR
+J_to_eV
+PLANCK
+STATUS
+THOMSON_LENGTH
+assplode
+biggest
+check_prefix
+chomp
+deg2rad
+eV_to_J
+gaussian_noise
+safe_basename
+progress_bar
+rad2deg
+is_odd
+poisson_noise
+notrail
+smallest
+ph_en_to_lambda
+ph_lambda_to_en
+</SECTION>
+
+<SECTION>
+<FILE>quaternion</FILE>
+quaternion
+<SUBSECTION>
+quaternion_modulus
+normalise_quaternion
+random_quaternion
+quaternion_valid
+quat_rot
+</SECTION>
+
+<SECTION>
+<FILE>image</FILE>
+image
+ImageFeatureList
+image_add_feature
+image_feature_closest
+image_feature_count
+image_feature_list_free
+image_feature_list_new
+image_get_feature
+image_remove_feature
+</SECTION>
+
+<SECTION>
+<FILE>thread-pool</FILE>
+TPGetTaskFunc
+TPWorkFunc
+TPFinalFunc
+<SUBSECTION>
+run_threads
+</SECTION>
+
+<SECTION>
+<FILE>statistics</FILE>
+stat_pearson_f_ignore
+stat_pearson_f_zero
+stat_pearson_i
+stat_r1_i
+stat_r1_ignore
+stat_r1_zero
+stat_r2
+stat_rdiff_ignore
+stat_rdiff_intensity
+stat_rdiff_zero
+stat_scale_intensity
+</SECTION>
+
+<SECTION>
+<FILE>indexing</FILE>
+IndexingMethod
+IndexingPrivate
+MAX_CELL_CANDIDATES
+build_indexer_list
+cleanup_indexing
+prepare_indexing
+index_pattern
+run_dirax
+run_mosflm
+map_all_peaks
+</SECTION>
+
+<SECTION>
+<FILE>symmetry</FILE>
+SymOpList
+SymOpMask
+<SUBSECTION>
+free_symoplist
+num_equivs
+get_pointgroup
+get_equiv
+special_position
+get_asymm
+get_ambiguities
+is_subgroup
+<SUBSECTION>
+new_symopmask
+free_symopmask
+<SUBSECTION>
+describe_symmetry
+symmetry_name
+is_centrosymmetric
+</SECTION>
+
+<SECTION>
+<FILE>integer_matrix</FILE>
+IntegerMatrix
+<SUBSECTION>
+intmat_new
+intmat_copy
+intmat_free
+<SUBSECTION>
+intmat_get
+intmat_set
+<SUBSECTION>
+intmat_intmat_mult
+intmat_intvec_mult
+intmat_det
+intmat_inverse
+<SUBSECTION>
+intmat_equals
+intmat_is_identity
+intmat_is_inversion
+<SUBSECTION>
+intmat_print
+</SECTION>
+
+<SECTION>
+<FILE>detector</FILE>
+copy_geom
+fill_in_values
+free_detector_geometry
+get_detector_geometry
+write_detector_geometry
+find_panel
+find_panel_by_name
+find_panel_number
+simple_geometry
+record_image
+get_pixel_extents
+get_q
+get_q_for_panel
+get_tt
+smallest_q
+reverse_2d_mapping
+largest_q
+</SECTION>
+
+<SECTION>
+<FILE>crystal</FILE>
+Crystal
+crystal_new
+crystal_free
+</SECTION>
+
+<SECTION>
+<FILE>hdf5-file</FILE>
+hdf5_read
+hdf5_write
+hdfile
+hdfile_close
+hdfile_get_image_binned
+hdfile_get_string_value
+hdfile_open
+hdfile_read_group
+hdfile_set_first_image
+hdfile_set_image
+</SECTION>
+
+<SECTION>
+<FILE>stream</FILE>
+parse_stream_flags
+read_chunk
+write_chunk
+write_stream_header
+skip_some_files
+is_stream
+get_value
+count_patterns
+</SECTION>
+
+<SECTION>
+<FILE>render</FILE>
+render_get_colour_scale
+render_panels
+render_scale
+render_tiff_fp
+render_tiff_int16
+</SECTION>
diff --git a/doc/reference/libcrystfel/Makefile.am b/doc/reference/libcrystfel/Makefile.am
new file mode 100644
index 00000000..e4f49b03
--- /dev/null
+++ b/doc/reference/libcrystfel/Makefile.am
@@ -0,0 +1,102 @@
+## Process this file with automake to produce Makefile.in
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# This is a blank Makefile.am for using gtk-doc.
+# Copy this to your project's API docs directory and modify the variables to
+# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
+# of using the various options.
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=CrystFEL
+
+# Uncomment for versioned docs and specify the version of the module, e.g. '2'.
+#DOC_MODULE_VERSION=2
+
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
+
+# Directories containing the source code, relative to $(srcdir).
+# gtk-doc will search all .c and .h files beneath these paths
+# for inline comments documenting functions and macros.
+# e.g. DOC_SOURCE_DIR=../../../gtk ../../../gdk
+DOC_SOURCE_DIR=../../../libcrystfel/src
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS=
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
+SCAN_OPTIONS=
+
+# Extra options to supply to gtkdoc-mkdb.
+# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
+MKDB_OPTIONS=--sgml-mode --output-format=xml
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS=
+
+# Extra options to supply to gtkdoc-mkhtml
+MKHTML_OPTIONS=
+
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
+FIXXREF_OPTIONS=
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
+# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
+HFILE_GLOB=$(top_srcdir)/libcrystfel/src/*.h
+CFILE_GLOB=$(top_srcdir)/libcrystfel/src/*.c
+
+# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
+# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
+EXTRA_HFILES=
+
+# Header files to ignore when scanning. Use base file name, no paths
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
+IGNORE_HFILES=
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES=
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
+content_files=
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+# e.g. expand_content_files=running.sgml
+expand_content_files=
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+GTKDOC_CFLAGS=
+GTKDOC_LIBS=
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
+EXTRA_DIST +=
+
+# Files not to distribute
+# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
+# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
+#DISTCLEANFILES +=
+
+# Comment this out if you want your docs-status tested during 'make check'
+#if ENABLE_GTK_DOC
+#TESTS_ENVIRONMENT = cd $(srcsrc) &&
+#TESTS = $(GTKDOC_CHECK)
+#endif
+
+-include $(top_srcdir)/git.mk
diff --git a/doc/reference/libcrystfel/xml/coding-standards.xml b/doc/reference/libcrystfel/xml/coding-standards.xml
new file mode 100644
index 00000000..d51ba293
--- /dev/null
+++ b/doc/reference/libcrystfel/xml/coding-standards.xml
@@ -0,0 +1,157 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+<refentry id="CrystFEL-coding-standards">
+<refmeta>
+<refentrytitle role="top_of_page" id="CrystFEL-coding-standards.top_of_page">CrystFEL coding standards</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>
+  Coding  standards
+</refmiscinfo>
+</refmeta>
+<refnamediv></refnamediv>
+
+
+<refsect1 id="CrystFEL-coding-standards.description" role="desc">
+<title role="desc.title">Summary</title>
+<para>
+This page documents the coding conventions used within the CrystFEL source code.  Read these to help when reading the code or before making modifications destined to be sent upstream.
+</para>
+</refsect1>
+
+
+<refsect1 id="CrystFEL-coding-standards.license">
+<title>Licensing and copyright</title>
+<para>
+CrystFEL is distributed under the terms of the GNU General Public License version 3 or higher.  Contributions are very welcome provided they also use this license.
+</para>
+<para>
+Whenever you edit a source file, don't forget to update the copyright dates at the top.  Add your name and email address if they're not there already.  Be sure to add your name to the 'AUTHORS' file in the top level folder, as well.
+</para>
+</refsect1>
+
+
+<refsect1 id="CrystFEL-coding-standards.formatting">
+<title>Formatting</title>
+<para>
+<emphasis>Indentation</emphasis> is done with <emphasis>tabs</emphasis> and
+<emphasis>alignment</emphasis> is done with spaces.  This way, the code looks
+neat whatever width you configure your editor to display tabs as.  This means,
+for example:
+</para>
+<para>
+<programlisting>
+struct something
+{
+	int thing;                   /* &lt;--- spaces used to align comments */
+	int thing_with_longer_name;  /* &lt;--- spaces used to align comments */
+}
+
+void somefunction(int something)
+{
+	/* &lt;--- Tab character used at the start of this line */
+}
+</programlisting>
+</para>
+<para>
+However, code must be <emphasis>strictly</emphasis> wrapped at 80 columns, or
+what would be 80 columns if the tabs were displayed as 8 spaces.
+If you think you need more width, you're at too many levels of indentation and
+need to break things down a bit.  There are no exceptions whatsoever.
+</para>
+<para>
+When performing a two or three dimensional iteration, for example over image
+coordinates or Miller indices, it is acceptable to indent as follows:
+</para>
+<para>
+<programlisting>
+for ( h=-10; h&lt;+10; h++ ) {
+for ( k=-10; k&lt;+10; k++ ) {
+for ( l=-10; l&lt;+10; l++ ) {
+
+	/* Do stuff */
+
+}
+}
+}
+</programlisting>
+</para>
+</refsect1>
+
+
+<refsect1 id="CrystFEL-coding-standards.brackets">
+<title>Brackets and so on</title>
+<para>
+Brackets and so on should go like this:
+</para>
+<para>
+<programlisting>
+/* Multiple line comments have stars
+ * down one side */
+void somefunction(int someparam)
+{
+	/* Single line comments use this style (not //) */
+	if ( a &lt; b ) {
+		/* 'if' statements usually have the opening brace on the same
+		 * line as the condition. */
+	} else {
+		/* 'else's are 'cuddled' */
+	}
+
+	if ( some &amp;&amp; very &amp;&amp; long &amp;&amp; condition &amp;&amp; that &amp;&amp; spans
+	     &amp;&amp; two &amp;&amp; lines )
+	{
+		/* Opening brace is on a line by itself in the case of a very
+		 * long condition */
+	}
+}
+
+/* Comments use proper capitalisation to make things look neat */
+</programlisting>
+</para>
+<para>'struct' blocks can have the braces like functions or 'if' statements.  Usually the former looks nicer if the struct is large.</para>
+<para>Parentheses should have spaces after them in 'if' statements, but not in function calls. Function arguments should have spaces after the comma.  There should be no space between the function name and the opening bracket.  That means:</para>
+<para><programlisting>
+if ( something ) {
+	do_something(a, b, c);
+}
+</programlisting></para>
+<para>instead of:</para>
+<para><programlisting>
+if (something) {
+	do_something (a,b,c);
+}
+</programlisting></para>
+</refsect1>
+
+
+<refsect1 id="CrystFEL-coding-standards.cleverness">
+<title>Cleverness</title>
+<para>
+Yes, we all know you can insert a new node into an RB-tree while simultaneously
+calculating Pi to 150 decimal places in one line of code.  You don't need to
+prove it here.  As a general rule, if you think you're about to do something clever, <emphasis>don't do it at all</emphasis>.
+</para>
+</refsect1>
+
+
+<refsect1 id="CrystFEL-coding-standards.commitmessages">
+<title>VCS commit messages</title>
+<para>The first line of your commit message should include a one line summary of the changes, in the form "Do XYZ".  That is, not "Did XYZ".</para>
+<para>Make the minimum possible changes in each commit.  Try to really distill your changes down to the bare bones, and keep 'cleaning up' in separate commits.  Remember that Git thinks about 'changes' rather than 'versions'.</para>
+</refsect1>
+
+
+<refsect1 id="CrystFEL-coding-standards.evilness">
+<title>Evil dictator</title>
+<para>
+Despite your following all of the above, I will probably still touch up your
+code in some places while (or shortly after) integrating it into mainline
+CrystFEL.  Please try not to take it personally.
+</para>
+</refsect1>
+
+</refentry>