Sculpt: Write documentation in sculpt_undo.c

Referenced by issue #103787, Regression: UV Relax Brush tears apart UVs
Referenced by issue #100483, Mirror vertex group weight paint

source/blender/editors/sculpt_paint/sculpt_undo.c

@@ -4,6 +4,29 @@
 /** \file
  * \ingroup edsculpt
  * Implements the Sculpt Mode tools.
+ *
+ * Usage Guide
+ * ===========
+ *
+ * The sculpt undo system is a delta-based system. Each undo step stores
+ * the difference with the prior one.
+ * 
+ * To use the sculpt undo system, you must call SCULPT_undo_push_begin
+ * inside an operator exec or invoke callback (ED_sculpt_undo_geometry_begin
+ * may be called if you wish to save a non-delta copy of the entire mesh).
+ * This will initialize the sculpt undo stack and set up an undo step.
+ * 
+ * At the end of the operator you should call SCULPT_undo_push_end.
+ *
+ * SCULPT_undo_push_end and ED_sculpt_undo_geometry_begin both take a
+ * wmOperatorType as an argument. There are _ex versions that allow a custom
+ * name; try to avoid using them. These can break the redo panel since it requires
+ * the undo push have the same name as the calling operator.
+ *
+ * Note: Sculpt undo steps are not appended to the global undo stack until
+ * the operator finishes.  We use BKE_undosys_step_push_init_with_type to build
+ * a tentative undo step with is appended later when the operator ends.
+ * Operators must have the OPTYPE_UNDO flag set for this to work properly.
  */
 
 #include <stddef.h>
@@ -1142,8 +1165,7 @@ static SculptUndoNode *sculpt_undo_alloc_node(Object *ob, PBVHNode *node, Sculpt
       unode->co = MEM_callocN(alloc_size, "SculptUndoNode.co");
       usculpt->undo_size += alloc_size;
 
-      /* FIXME: Should explain why this is allocated here, to be freed in
-       * `SCULPT_undo_push_end_ex()`? */
+      /* Needed for original data lookup. */
       alloc_size = sizeof(*unode->no) * (size_t)allvert;
       unode->no = MEM_callocN(alloc_size, "SculptUndoNode.no");
       usculpt->undo_size += alloc_size;