BMesh: add a BM_faces_join() to return a duplicate face (if found)

Every call to BM_faces_join and BM_faces_join_pair has been adjusted to
provide the new face pointer, and a BLI_assert_msg has been added so
that doubles are now consistently identified and flagged as a problem.
BM_faces_join is now also capable of automatically reusing a double
when it is found. This new behavior is currently unused at this point.
Future patch-sets will begin to use it, allowing simplification of
calling functions.

Ref: !137406

source/blender/python/bmesh/bmesh_py_utils.cc

@@ -653,7 +653,11 @@ static PyObject *bpy_bm_utils_face_join(PyObject * /*self*/, PyObject *args)
 
   /* Go ahead and join the face!
    * --------------------------- */
-  f_new = BM_faces_join(bm, face_array, int(face_seq_len), do_remove);
+  BMFace *f_double;
+  f_new = BM_faces_join(bm, face_array, int(face_seq_len), do_remove, &f_double);
+  /* See #BM_faces_join note on callers asserting when `r_double` is non-null. */
+  BLI_assert_msg(f_double == nullptr,
+                 "Doubled face detected at " AT ". Resulting mesh may be corrupt.");
 
   PyMem_FREE(face_array);