-/* merge_trees() but with recursive ancestor consolidation */
-int merge_recursive(struct merge_options *o,
+/*
+ * merge_recursive is like merge_trees() but with recursive ancestor
+ * consolidation and, if the commit is clean, creation of a commit.
+ *
+ * NOTE: empirically, about a decade ago it was determined that with more
+ * than two merge bases, optimal behavior was found when the
+ * merge_bases were passed in the order of oldest commit to newest
+ * commit. Also, merge_bases will be consumed (emptied) so make a
+ * copy if you need it.
+ *
+ * Outputs:
+ * - See RETURN VALUES above
+ * - If merge is clean, a commit is created and its address written to *result
+ * - opt->repo->index has the new index
+ * - $GIT_INDEX_FILE is not updated
+ * - The working tree is updated with results of the merge
+ */
+int merge_recursive(struct merge_options *opt,