add documentation, add safety check

git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@9592 57a11ea4-9604-0410-9ed3-97b8803252fd

src/engine/qofinstance.c

@@ -123,6 +123,10 @@ void
 qof_instance_gemini (QofInstance *to, QofInstance *from)
 {
   time_t now;
+
+  /* Books must differ for a gemini to be meaningful */
+  if (!from || !to || (from->book == to->book)) return;
+
   now = time(0);
 
   /* Make a note of where the copy came from */

src/engine/qofinstance.h

@@ -60,9 +60,14 @@ KvpFrame* qof_instance_get_slots (QofInstance *);
 /** return value of is_dirty flag */
 gboolean qof_instance_is_dirty (QofInstance *);
 
-/** pair things up. Currently, this routine only inserts a
+/** Pair things up.  This routine inserts a kvp value into each instance
- * pair of guid-pointers pointing to each other.  it
+ *  containing the guid of the other.  In this way, if one has one of the
- * doesn't copy any data.
+ *  pair, one can always find the other by looking up it's guid.  Typically,
+ *  you will want to use qof_instance_lookup_twin() to find the twin.
+ *  (The current implementation assumes the two instances belong to different
+ *  books, and will not add gemini kvp's unless the books differ.  Note that
+ *  the gemini kvp includes the book guid as well, so that the right book can
+ *  be found.
  */
 void qof_instance_gemini (QofInstance *to, QofInstance *from);