Documentation and comments

2 files changed, 24 insertions, 2 deletions

diff --git a/src/reflist-utils.c b/src/reflist-utils.c
index 191c4bd9..a572faf7 100644
--- a/src/reflist-utils.c
+++ b/src/reflist-utils.c
@@ -263,7 +263,7 @@ void write_reflections_to_file(FILE *fh, RefList *list, UnitCell *cell)
  * 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
+ * This is a convenience function which simply opens @filename and then calls
  * write_reflections_to_file.
  *
  * Returns: zero on success, non-zero on failure.
@@ -375,6 +375,18 @@ RefList *read_reflections(const char *filename)
 }
 
 
+/**
+ * asymmetric_indices:
+ * @in: A %RefList
+ * @sym: A %SymOpList
+ *
+ * This function creates a newly allocated copy of @in, but indexed using the
+ * asymmetric indices according to @sym instead of the original indices.  The
+ * original indices are stored and can be retrieved using
+ * get_symmetric_indices() if required.
+ *
+ * Returns: the new %RefList, or NULL on failure.
+ **/
 RefList *asymmetric_indices(RefList *in, const SymOpList *sym)
 {
 	Reflection *refl;
diff --git a/src/symmetry.c b/src/symmetry.c
index a978eff1..70820db2 100644
--- a/src/symmetry.c
+++ b/src/symmetry.c
@@ -1012,6 +1012,13 @@ void special_position(const SymOpList *ops, SymOpMask *m,
  * This function determines the asymmetric version of the reflection @h, @k, @l
  * in symmetry group @ops, and puts the result in @hp, @kp, @lp.
  *
+ * This is a relatively expensive operation because of its generality.
+ * Therefore, if you know you'll need to make repeated use of the asymmetric
+ * indices, consider creating a new %RefList indexed according to the asymmetric
+ * indices themselves with asymmetric_indices().  If you do that, you'll still
+ * be able to get the original versions of the indices with
+ * get_symmetric_indices().
+ *
  **/
 void get_asymm(const SymOpList *ops,
                signed int h, signed int k, signed int l,
@@ -1189,7 +1196,9 @@ int is_subgroup(const SymOpList *source, const SymOpList *target)
  * inversions.
  * To count the number of possibilities, use num_ops() on the result.
  *
- * Returns: A %SymOpList containing the twinning operators
+ * Returns: A %SymOpList containing the twinning operators, or NULL if the
+ * source symmetry cannot be generated from that target symmetry without using
+ * mirror or inversion operations.
  */
 SymOpList *get_ambiguities(const SymOpList *source, const SymOpList *target)
 {
@@ -1293,6 +1302,7 @@ SymOpList *get_ambiguities(const SymOpList *source, const SymOpList *target)
 	free_symopmask(used);
 	used = new_symopmask(src_reordered);
 
+	/* This is the first method from Flack (1987) */
 	for ( i=0; i<n_src; i++ ) {
 
 		int j;