From 2653e2f84c9886c27af4f0b4b54d159882a366a1 Mon Sep 17 00:00:00 2001
From: Thomas White <taw@physics.org>
Date: Tue, 26 Jul 2011 12:21:34 +0200
Subject: Update docs

---
 src/reflist.c  |  2 +-
 src/reflist.h  |  4 ++--
 src/symmetry.c | 57 +++++++++++++++++++++++++++++++++++++++++----------------
 src/symmetry.h |  9 +++++++--
 4 files changed, 51 insertions(+), 21 deletions(-)

(limited to 'src')

diff --git a/src/reflist.c b/src/reflist.c
index 5b594d76..aefbf4e2 100644
--- a/src/reflist.c
+++ b/src/reflist.c
@@ -570,7 +570,7 @@ void set_scalable(Reflection *refl, int scalable)
 /**
  * set_refinable:
  * @refl: A %Reflection
- * @scalable: Non-zero if this reflection can be used for post refinement.
+ * @refinable: Non-zero if this reflection can be used for post refinement.
  *
  **/
 void set_refinable(Reflection *refl, int refinable)
diff --git a/src/reflist.h b/src/reflist.h
index 6c0285f1..a49d4a61 100644
--- a/src/reflist.h
+++ b/src/reflist.h
@@ -85,8 +85,8 @@ extern void set_int(Reflection *refl, double intensity);
 extern void set_scalable(Reflection *refl, int scalable);
 extern void set_refinable(Reflection *refl, int refinable);
 extern void set_redundancy(Reflection *refl, int red);
-extern void set_temp1(Reflection *refl, double dev);
-extern void set_temp2(Reflection *refl, double dev);
+extern void set_temp1(Reflection *refl, double temp);
+extern void set_temp2(Reflection *refl, double temp);
 extern void set_esd_intensity(Reflection *refl, double esd);
 extern void set_ph(Reflection *refl, double phase);
 extern void set_symmetric_indices(Reflection *refl,
diff --git a/src/symmetry.c b/src/symmetry.c
index 87088c80..a978eff1 100644
--- a/src/symmetry.c
+++ b/src/symmetry.c
@@ -46,20 +46,6 @@ struct sym_op
 };
 
 
-/**
- * SECTION:symoplist
- * @short_description: A list of point symmetry operations
- * @title: SymOpList
- * @section_id:
- * @see_also:
- * @include: "symmetry.h"
- * @Image:
- *
- * The SymOpList is an opaque data structure containing a list of point symmetry
- * operations.  It could represent an point group or a list of indexing
- * ambiguities (twin laws), or similar.
- */
-
 struct _symoplist
 {
 	struct sym_op *ops;
@@ -797,6 +783,20 @@ static SymOpList *make_m3barm()
 }
 
 
+/**
+ * get_pointgroup:
+ * @sym: A string representation of a point group
+ *
+ * This function parses @sym and returns the corresponding %SymOpList.
+ * In the string representation of the point group, use a preceding minus sign
+ * for any character which would have a "bar".  Trigonal groups must be suffixed
+ * with either "_H" or "_R" for a hexagonal or rhombohedral lattice
+ * respectively.
+ *
+ * Examples: -1 1 2/m 2 m mmm 222 mm2 4/m 4 -4 4/mmm 422 -42m -4m2 4mm
+ * 3_R -3_R 32_R 3m_R -3m_R 3_H -3_H 321_H 312_H 3m1_H 31m_H -3m1_H -31m_H
+ * 6/m 6 -6 6/mmm 622 -62m -6m2 6mm 23 m-3 432 -43m m-3m.
+ **/
 SymOpList *get_pointgroup(const char *sym)
 {
 	/* Triclinic */
@@ -999,6 +999,20 @@ void special_position(const SymOpList *ops, SymOpMask *m,
 }
 
 
+/**
+ * get_asymm:
+ * @ops: A %SymOpList, usually corresponding to a point group
+ * @h: index of a reflection
+ * @k: index of a reflection
+ * @l: index of a reflection
+ * @hp: location for asymmetric index of reflection
+ * @kp: location for asymmetric index of reflection
+ * @lp: location for asymmetric index of reflection
+ *
+ * This function determines the asymmetric version of the reflection @h, @k, @l
+ * in symmetry group @ops, and puts the result in @hp, @kp, @lp.
+ *
+ **/
 void get_asymm(const SymOpList *ops,
                signed int h, signed int k, signed int l,
                signed int *hp, signed int *kp, signed int *lp)
@@ -1103,7 +1117,6 @@ static int struct_ops_equal(const struct sym_op *op1, const struct sym_op *op2)
 }
 
 
-
 /* Return true if a*b = ans */
 static int check_mult(const struct sym_op *ans,
                       const struct sym_op *a, const struct sym_op *b)
@@ -1126,7 +1139,13 @@ static int check_mult(const struct sym_op *ans,
 }
 
 
-/* Check that every operation in "target" is also in "source" */
+/**
+ * is_subgroup:
+ * @source: A %SymOpList
+ * @target: Another %SymOpList, which might be a subgroup of @source.
+ *
+ * Returns: non-zero if every operation in @target is also in @source.
+ **/
 int is_subgroup(const SymOpList *source, const SymOpList *target)
 {
 	int n_src, n_tgt;
@@ -1423,6 +1442,12 @@ void describe_symmetry(const SymOpList *s)
 }
 
 
+/**
+ * symmetry_name:
+ * @ops: A %SymOpList
+ *
+ * Returns: a text description of @ops.
+ */
 const char *symmetry_name(const SymOpList *ops)
 {
 	return ops->name;
diff --git a/src/symmetry.h b/src/symmetry.h
index c91864bb..071ebbde 100644
--- a/src/symmetry.h
+++ b/src/symmetry.h
@@ -20,14 +20,19 @@
 /**
  * SymOpList
  *
- * Opaque type.
+ * The SymOpList is an opaque data structure containing a list of point symmetry
+ * operations.  It could represent an point group or a list of indexing
+ * ambiguities (twin laws), or similar.
  **/
 typedef struct _symoplist SymOpList;
 
 /**
  * SymOpMask
  *
- * Opaque type.
+ * The SymOpMask is an opaque data structure containing a list of flags
+ * associated with point symmetry operations in a specific %SymOpList.  It is
+ * used to filter the operations in the %SymOpList to avoid duplicating
+ * equivalent reflections when the reflection is somehow special (e.g. 'hk0').
  **/
 typedef struct _symopmask SymOpMask;
 
-- 
cgit v1.2.3