Merge branch 'master' into asset-uuid

8 files changed, 355 insertions, 116 deletions

diff --git a/source/blender/blenkernel/BKE_modifier.h b/source/blender/blenkernel/BKE_modifier.h
index e4cf7d44f05..766ca78dc50 100644
--- a/source/blender/blenkernel/BKE_modifier.h
+++ b/source/blender/blenkernel/BKE_modifier.h
@@ -41,6 +41,8 @@ struct ModifierData;
 struct Object;
 struct Scene;
 struct bArmature;
+struct BlendWriter;
+struct BlendDataReader;
 
 typedef enum {
   /* Should not be used, only for None modifier type */
@@ -355,6 +357,21 @@ typedef struct ModifierTypeInfo {
 
   /* Register the panel types for the modifier's UI. */
   void (*panelRegister)(struct ARegionType *region_type);
+
+  /* Is called when the modifier is written to a file. The modifier data struct itself is written
+   * already.
+   *
+   * This method should write any additional arrays and referenced structs that should be
+   * stored in the file.
+   */
+  void (*blendWrite)(struct BlendWriter *writer, const struct ModifierData *md);
+
+  /* Is called when the modifier is read from a file.
+   *
+   * It can be used to update pointers to arrays and other structs. Furthermore, fields that have
+   * not been written (e.g. runtime data) can be reset.
+   */
+  void (*blendRead)(struct BlendDataReader *reader, struct ModifierData *md);
 } ModifierTypeInfo;
 
 /* Used to find a modifier's panel type. */
diff --git a/source/blender/blenkernel/BKE_paint.h b/source/blender/blenkernel/BKE_paint.h
index 144e091d971..6e4f2efeeb8 100644
--- a/source/blender/blenkernel/BKE_paint.h
+++ b/source/blender/blenkernel/BKE_paint.h
@@ -24,7 +24,6 @@
  * \ingroup bke
  */
 
-#include "BLI_ghash.h"
 #include "BLI_utildefines.h"
 #include "DNA_object_enums.h"
 
@@ -39,6 +38,7 @@ struct CurveMapping;
 struct Depsgraph;
 struct EnumPropertyItem;
 struct GHash;
+struct GSet;
 struct GridPaintMask;
 struct ImagePool;
 struct MLoop;
@@ -269,7 +269,7 @@ typedef struct SculptClothLengthConstraint {
 typedef struct SculptClothSimulation {
   SculptClothLengthConstraint *length_constraints;
   int tot_length_constraints;
-  GSet *created_length_constraints;
+  struct GSet *created_length_constraints;
   int capacity_length_constraints;
   float *length_constraint_tweak;
 
diff --git a/source/blender/blenkernel/intern/camera.c b/source/blender/blenkernel/intern/camera.c
index 5ec4c84c013..7c0e4064cdb 100644
--- a/source/blender/blenkernel/intern/camera.c
+++ b/source/blender/blenkernel/intern/camera.c
@@ -54,7 +54,9 @@
 
 #include "MEM_guardedalloc.h"
 
-/****************************** Camera Datablock *****************************/
+/* -------------------------------------------------------------------- */
+/** \name Camera Data-Block
+ * \{ */
 
 static void camera_init_data(ID *id)
 {
@@ -128,7 +130,11 @@ IDTypeInfo IDType_ID_CA = {
     .foreach_id = camera_foreach_id,
 };
 
-/******************************** Camera Usage *******************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Camera Usage
+ * \{ */
 
 void *BKE_camera_add(Main *bmain, const char *name)
 {
@@ -188,7 +194,11 @@ int BKE_camera_sensor_fit(int sensor_fit, float sizex, float sizey)
   return sensor_fit;
 }
 
-/******************************** Camera Params *******************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Camera Parameter Access
+ * \{ */
 
 void BKE_camera_params_init(CameraParams *params)
 {
@@ -380,7 +390,11 @@ void BKE_camera_params_compute_matrix(CameraParams *params)
   }
 }
 
-/***************************** Camera View Frame *****************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Camera View Frame
+ * \{ */
 
 void BKE_camera_view_frame_ex(const Scene *scene,
                               const Camera *camera,
@@ -482,6 +496,12 @@ void BKE_camera_view_frame(const Scene *scene, const Camera *camera, float r_vec
       scene, camera, 1.0, false, dummy_scale, dummy_asp, dummy_shift, &dummy_drawsize, r_vec);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Camera View Frame Fit to Points
+ * \{ */
+
 #define CAMERA_VIEWFRAME_NUM_PLANES 4
 
 typedef struct CameraViewFrameData {
@@ -723,7 +743,11 @@ bool BKE_camera_view_frame_fit_to_coords(const Depsgraph *depsgraph,
   return camera_frame_fit_calc_from_data(&params, &data_cb, r_co, r_scale);
 }
 
-/******************* multiview matrix functions ***********************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Camera Multi-View Matrix
+ * \{ */
 
 static void camera_model_matrix(const Object *camera, float r_modelmat[4][4])
 {
@@ -1038,6 +1062,12 @@ void BKE_camera_multiview_params(const RenderData *rd,
   }
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Camera Background Image
+ * \{ */
+
 CameraBGImage *BKE_camera_background_image_new(Camera *cam)
 {
   CameraBGImage *bgpic = MEM_callocN(sizeof(CameraBGImage), "Background Image");
@@ -1072,3 +1102,5 @@ void BKE_camera_background_image_clear(Camera *cam)
     bgpic = next_bgpic;
   }
 }
+
+/** \} */
diff --git a/source/blender/blenkernel/intern/collection.c b/source/blender/blenkernel/intern/collection.c
index a9d3c7c1b65..6f63da18a22 100644
--- a/source/blender/blenkernel/intern/collection.c
+++ b/source/blender/blenkernel/intern/collection.c
@@ -53,7 +53,9 @@
 
 #include "MEM_guardedalloc.h"
 
-/******************************** Prototypes ********************************/
+/* -------------------------------------------------------------------- */
+/** \name Prototypes
+ * \{ */
 
 static bool collection_child_add(Collection *parent,
                                  Collection *collection,
@@ -72,7 +74,11 @@ static CollectionParent *collection_find_parent(Collection *child, Collection *c
 
 static bool collection_find_child_recursive(Collection *parent, Collection *collection);
 
-/****************************** Collection Datablock ************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Collection Data-Block
+ * \{ */
 
 /**
  * Only copy internal data of Collection ID from source
@@ -168,7 +174,11 @@ IDTypeInfo IDType_ID_GR = {
     .foreach_id = collection_foreach_id,
 };
 
-/***************************** Add Collection *******************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Add Collection
+ * \{ */
 
 /* Add new collection, without view layer syncing. */
 static Collection *collection_add(Main *bmain,
@@ -238,7 +248,11 @@ void BKE_collection_add_from_object(Main *bmain,
   BKE_main_collection_sync(bmain);
 }
 
-/*********************** Free and Delete Collection ****************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Free and Delete Collection
+ * \{ */
 
 /** Free (or release) any data used by this collection (does not free the collection itself). */
 void BKE_collection_free(Collection *collection)
@@ -303,7 +317,12 @@ bool BKE_collection_delete(Main *bmain, Collection *collection, bool hierarchy)
   return true;
 }
 
-/***************************** Collection Copy *******************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Collection Copy
+ * \{ */
+
 static Collection *collection_duplicate_recursive(Main *bmain,
                                                   Collection *parent,
                                                   Collection *collection_old,
@@ -456,7 +475,11 @@ Collection *BKE_collection_duplicate(Main *bmain,
   return collection_new;
 }
 
-/********************************* Naming *******************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Collection Naming
+ * \{ */
 
 /**
  * The automatic/fallback name of a new collection.
@@ -496,7 +519,11 @@ const char *BKE_collection_ui_name_get(struct Collection *collection)
   }
 }
 
-/* **************** Object List Cache *******************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Object List Cache
+ * \{ */
 
 static void collection_object_cache_fill(ListBase *lb, Collection *collection, int parent_restrict)
 {
@@ -569,7 +596,11 @@ Base *BKE_collection_or_layer_objects(const ViewLayer *view_layer, Collection *c
   }
 }
 
-/*********************** Scene Master Collection ***************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Scene Master Collection
+ * \{ */
 
 Collection *BKE_collection_master_add()
 {
@@ -594,7 +625,11 @@ Scene *BKE_collection_master_scene_search(const Main *bmain, const Collection *m
   return NULL;
 }
 
-/*********************** Cyclic Checks ************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Cyclic Checks
+ * \{ */
 
 static bool collection_object_cyclic_check_internal(Object *object, Collection *collection)
 {
@@ -634,7 +669,11 @@ bool BKE_collection_object_cyclic_check(Main *bmain, Object *object, Collection
   return collection_object_cyclic_check_internal(object, collection);
 }
 
-/******************* Collection Object Membership *******************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Collection Object Membership
+ * \{ */
 
 bool BKE_collection_has_object(Collection *collection, const Object *ob)
 {
@@ -695,7 +734,11 @@ bool BKE_collection_is_empty(Collection *collection)
          BLI_listbase_is_empty(&collection->children);
 }
 
-/********************** Collection Objects *********************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Collection Objects
+ * \{ */
 
 static void collection_tag_update_parent_recursive(Main *bmain,
                                                    Collection *collection,
@@ -1043,7 +1086,11 @@ void BKE_collection_object_move(
   }
 }
 
-/***************** Collection Scene Membership ****************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Collection Scene Membership
+ * \{ */
 
 bool BKE_collection_is_in_scene(Collection *collection)
 {
@@ -1068,7 +1115,31 @@ void BKE_collections_after_lib_link(Main *bmain)
   BKE_main_collection_sync(bmain);
 }
 
-/********************** Collection Children *******************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Collection Children
+ * \{ */
+
+static bool collection_find_instance_recursive(Collection *collection,
+                                               Collection *instance_collection)
+{
+  LISTBASE_FOREACH (CollectionObject *, collection_object, &collection->gobject) {
+    if (collection_object->ob != NULL &&
+        /* Object from a given collection should never instanciate that collection either. */
+        ELEM(collection_object->ob->instance_collection, instance_collection, collection)) {
+      return true;
+    }
+  }
+
+  LISTBASE_FOREACH (CollectionChild *, collection_child, &collection->children) {
+    if (collection_find_instance_recursive(collection_child->collection, instance_collection)) {
+      return true;
+    }
+  }
+
+  return false;
+}
 
 bool BKE_collection_find_cycle(Collection *new_ancestor, Collection *collection)
 {
@@ -1082,7 +1153,9 @@ bool BKE_collection_find_cycle(Collection *new_ancestor, Collection *collection)
     }
   }
 
-  return false;
+  /* Find possible objects in collection or its children, that would instanciate the given ancestor
+   * collection (that would also make a fully invalid cycle of dependencies) .*/
+  return collection_find_instance_recursive(collection, new_ancestor);
 }
 
 static CollectionChild *collection_find_child(Collection *parent, Collection *collection)
@@ -1239,7 +1312,11 @@ void BKE_main_collections_parent_relations_rebuild(Main *bmain)
   /* Scene's master collections will be 'root' parent of most of our collections, so start with
    * them. */
   for (Scene *scene = bmain->scenes.first; scene != NULL; scene = scene->id.next) {
-    collection_parents_rebuild_recursive(scene->master_collection);
+    /* This function can be called from readfile.c, when this pointer is not guaranteed to be NULL.
+     */
+    if (scene->master_collection != NULL) {
+      collection_parents_rebuild_recursive(scene->master_collection);
+    }
   }
 
   /* We may have parent chains outside of scene's master_collection context? At least, readfile's
@@ -1255,7 +1332,11 @@ void BKE_main_collections_parent_relations_rebuild(Main *bmain)
   }
 }
 
-/********************** Collection index *********************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Collection Index
+ * \{ */
 
 static Collection *collection_from_index_recursive(Collection *collection,
                                                    const int index,
@@ -1341,7 +1422,11 @@ bool BKE_collection_objects_select(ViewLayer *view_layer, Collection *collection
   }
 }
 
-/***************** Collection move (outliner drag & drop) *********************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Collection move (outliner drag & drop)
+ * \{ */
 
 bool BKE_collection_move(Main *bmain,
                          Collection *to_parent,
@@ -1434,7 +1519,11 @@ bool BKE_collection_move(Main *bmain,
   return true;
 }
 
-/**************************** Iterators ******************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Iterators
+ * \{ */
 
 /* scene collection iteractor */
 
@@ -1620,3 +1709,5 @@ void BKE_scene_objects_iterator_end(BLI_Iterator *iter)
     MEM_freeN(data);
   }
 }
+
+/** \} */
diff --git a/source/blender/blenkernel/intern/lib_id.c b/source/blender/blenkernel/intern/lib_id.c
index ca23ec90c97..ab9b11f436a 100644
--- a/source/blender/blenkernel/intern/lib_id.c
+++ b/source/blender/blenkernel/intern/lib_id.c
@@ -123,6 +123,16 @@ static void lib_id_library_local_paths(Main *bmain, Library *lib, ID *id)
                         (void *)bpath_user_data);
 }
 
+static int lib_id_clear_library_data_users_update_cb(LibraryIDLinkCallbackData *cb_data)
+{
+  ID *id = cb_data->user_data;
+  if (*cb_data->id_pointer == id) {
+    DEG_id_tag_update_ex(cb_data->bmain, cb_data->id_owner, ID_RECALC_TAG_FOR_UNDO);
+    return IDWALK_RET_STOP_ITER;
+  }
+  return IDWALK_RET_NOP;
+}
+
 /**
  * Pull an ID out of a library (make it local). Only call this for IDs that
  * don't have other library users.
@@ -145,6 +155,21 @@ static void lib_id_clear_library_data_ex(Main *bmain, ID *id)
     }
   }
 
+  /* Conceptually, an ID made local is not the same as the linked one anymore. Reflect that by
+   * regenerating its session UUID. */
+  BKE_lib_libblock_session_uuid_renew(id);
+
+  /* We need to tag this IDs and all of its users, conceptually new local ID and original linked
+   * ones are two completely different data-blocks that were virtually remaped, even though in
+   * reality they remain the same data. For undo this info is critical now. */
+  DEG_id_tag_update_ex(bmain, id, ID_RECALC_COPY_ON_WRITE);
+  ID *id_iter;
+  FOREACH_MAIN_ID_BEGIN (bmain, id_iter) {
+    BKE_library_foreach_ID_link(
+        bmain, id_iter, lib_id_clear_library_data_users_update_cb, id, IDWALK_READONLY);
+  }
+  FOREACH_MAIN_ID_END;
+
   /* Internal shape key blocks inside data-blocks also stores id->lib,
    * make sure this stays in sync (note that we do not need any explicit handling for real EMBEDDED
    * IDs here, this is down automatically in `lib_id_expand_local_cb()`. */
@@ -1047,8 +1072,10 @@ void BKE_lib_libblock_session_uuid_ensure(ID *id)
 /**
  * Re-generate a new session-wise uuid for the given \a id.
  *
- * \warning This has a very specific use-case (to handle UI-related data-blocks that are kept
- * across new file reading, when we do keep existing UI). No other usage is expected currently.
+ * \warning This has a few very specific use-cases, no other usage is expected currently:
+ *   - To handle UI-related data-blocks that are kept across new file reading, when we do keep
+ * existing UI.
+ *   - For IDs that are made local without needing any copying.
  */
 void BKE_lib_libblock_session_uuid_renew(ID *id)
 {
diff --git a/source/blender/blenkernel/intern/seqmodifier.c b/source/blender/blenkernel/intern/seqmodifier.c
index 80ad8561333..75f7ed82165 100644
--- a/source/blender/blenkernel/intern/seqmodifier.c
+++ b/source/blender/blenkernel/intern/seqmodifier.c
@@ -48,7 +48,9 @@
 static SequenceModifierTypeInfo *modifiersTypes[NUM_SEQUENCE_MODIFIER_TYPES];
 static bool modifierTypesInit = false;
 
-/*********************** Modifiers *************************/
+/* -------------------------------------------------------------------- */
+/** \name Modifier Multi-Threading Utilities
+ * \{ */
 
 typedef void (*modifier_apply_threaded_cb)(int width,
                                            int height,
@@ -163,7 +165,11 @@ static void modifier_apply_threaded(ImBuf *ibuf,
       ibuf->y, sizeof(ModifierThread), &init_data, modifier_init_handle, modifier_do_thread);
 }
 
-/* **** Color Balance Modifier **** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Color Balance Modifier
+ * \{ */
 
 static void colorBalance_init_data(SequenceModifierData *smd)
 {
@@ -196,7 +202,11 @@ static SequenceModifierTypeInfo seqModifier_ColorBalance = {
     colorBalance_apply,                                   /* apply */
 };
 
-/* **** White Balance Modifier **** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name White Balance Modifier
+ * \{ */
 
 static void whiteBalance_init_data(SequenceModifierData *smd)
 {
@@ -288,7 +298,11 @@ static SequenceModifierTypeInfo seqModifier_WhiteBalance = {
     whiteBalance_apply,                                   /* apply */
 };
 
-/* **** Curves Modifier **** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Curves Modifier
+ * \{ */
 
 static void curves_init_data(SequenceModifierData *smd)
 {
@@ -402,7 +416,11 @@ static SequenceModifierTypeInfo seqModifier_Curves = {
     curves_apply,                                  /* apply */
 };
 
-/* **** Hue Correct Modifier **** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Hue Correct Modifier
+ * \{ */
 
 static void hue_correct_init_data(SequenceModifierData *smd)
 {
@@ -522,7 +540,11 @@ static SequenceModifierTypeInfo seqModifier_HueCorrect = {
     hue_correct_apply,                                  /* apply */
 };
 
-/* **** Bright/Contrast Modifier **** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Bright/Contrast Modifier
+ * \{ */
 
 typedef struct BrightContrastThreadData {
   float bright;
@@ -625,7 +647,11 @@ static SequenceModifierTypeInfo seqModifier_BrightContrast = {
     brightcontrast_apply,                                   /* apply */
 };
 
-/* **** Mask Modifier **** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Mask Modifier
+ * \{ */
 
 static void maskmodifier_apply_threaded(int width,
                                         int height,
@@ -694,7 +720,11 @@ static SequenceModifierTypeInfo seqModifier_Mask = {
     maskmodifier_apply,                          /* apply */
 };
 
-/* **** Tonemap Modifier **** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Tonemap Modifier
+ * \{ */
 
 typedef struct AvgLogLum {
   SequencerTonemapModifierData *tmmd;
@@ -906,7 +936,11 @@ static SequenceModifierTypeInfo seqModifier_Tonemap = {
     tonemapmodifier_apply,                          /* apply */
 };
 
-/*********************** Modifier functions *************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Public Modifier Functions
+ * \{ */
 
 static void sequence_modifier_type_info_init(void)
 {
diff --git a/source/blender/blenkernel/intern/shrinkwrap.c b/source/blender/blenkernel/intern/shrinkwrap.c
index c59042bc045..29f4c7dc6c1 100644
--- a/source/blender/blenkernel/intern/shrinkwrap.c
+++ b/source/blender/blenkernel/intern/shrinkwrap.c
@@ -51,6 +51,7 @@
 #include "BKE_editmesh.h"
 #include "BKE_mesh.h" /* for OMP limits. */
 #include "BKE_mesh_runtime.h"
+#include "BKE_mesh_wrapper.h"
 #include "BKE_subsurf.h"
 
 #include "DEG_depsgraph_query.h"
@@ -115,7 +116,16 @@ bool BKE_shrinkwrap_init_tree(
 {
   memset(data, 0, sizeof(*data));
 
-  if (!mesh || mesh->totvert <= 0) {
+  if (mesh == NULL) {
+    return false;
+  }
+
+  /* We could create a BVH tree from the edit mesh,
+   * however accessing normals from the face/loop normals gets more involved.
+   * Convert mesh data since this isn't typically used in edit-mode. */
+  BKE_mesh_wrapper_ensure_mdata(mesh);
+
+  if (mesh->totvert <= 0) {
     return false;
   }
 
diff --git a/source/blender/blenkernel/intern/text.c b/source/blender/blenkernel/intern/text.c
index 527b54a1aa2..bce2266f3e9 100644
--- a/source/blender/blenkernel/intern/text.c
+++ b/source/blender/blenkernel/intern/text.c
@@ -87,9 +87,9 @@
  * be popped ... other st's retain their own top location.
  */
 
-/***/
-
-/****************************** Prototypes ************************/
+/* -------------------------------------------------------------------- */
+/** \name Prototypes
+ * \{ */
 
 static void txt_pop_first(Text *text);
 static void txt_pop_last(Text *text);
@@ -97,7 +97,11 @@ static void txt_delete_line(Text *text, TextLine *line);
 static void txt_delete_sel(Text *text);
 static void txt_make_dirty(Text *text);
 
-/****************************** Text Datablock ************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Text Data-Block
+ * \{ */
 
 static void text_init_data(ID *id)
 {
@@ -209,7 +213,11 @@ IDTypeInfo IDType_ID_TXT = {
     .foreach_id = NULL,
 };
 
-/***/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Text Add, Free, Validation
+ * \{ */
 
 /**
  * \note caller must handle `compiled` member.
@@ -549,9 +557,11 @@ void BKE_text_file_modified_ignore(Text *text)
   text->mtime = st.st_mtime;
 }
 
-/*****************************/
-/* Editing utility functions */
-/*****************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Editing Utility Functions
+ * \{ */
 
 static void make_new_line(TextLine *line, char *newline)
 {
@@ -696,9 +706,11 @@ static void txt_make_dirty(Text *text)
 #endif
 }
 
-/****************************/
-/* Cursor utility functions */
-/****************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Cursor Utility Functions
+ * \{ */
 
 static void txt_curs_cur(Text *text, TextLine ***linep, int **charp)
 {
@@ -722,9 +734,11 @@ bool txt_cursor_is_line_end(Text *text)
   return (text->selc == text->sell->len);
 }
 
-/*****************************/
-/* Cursor movement functions */
-/*****************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Cursor Movement Functions
+ * \{ */
 
 void txt_move_up(Text *text, const bool sel)
 {
@@ -1095,9 +1109,11 @@ void txt_move_to(Text *text, unsigned int line, unsigned int ch, const bool sel)
   }
 }
 
-/****************************/
-/* Text selection functions */
-/****************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Text Selection Functions
+ * \{ */
 
 static void txt_curs_swap(Text *text)
 {
@@ -1393,9 +1409,9 @@ void txt_from_buf_for_undo(Text *text, const char *buf, int buf_len)
 
 /** \} */
 
-/***************************/
-/* Cut and paste functions */
-/***************************/
+/* -------------------------------------------------------------------- */
+/** \name Cut and Paste Functions
+ * \{ */
 
 char *txt_to_buf(Text *text, int *r_buf_strlen)
 {
@@ -1474,59 +1490,6 @@ char *txt_to_buf(Text *text, int *r_buf_strlen)
   return buf;
 }
 
-int txt_find_string(Text *text, const char *findstr, int wrap, int match_case)
-{
-  TextLine *tl, *startl;
-  const char *s = NULL;
-
-  if (!text->curl || !text->sell) {
-    return 0;
-  }
-
-  txt_order_cursors(text, false);
-
-  tl = startl = text->sell;
-
-  if (match_case) {
-    s = strstr(&tl->line[text->selc], findstr);
-  }
-  else {
-    s = BLI_strcasestr(&tl->line[text->selc], findstr);
-  }
-  while (!s) {
-    tl = tl->next;
-    if (!tl) {
-      if (wrap) {
-        tl = text->lines.first;
-      }
-      else {
-        break;
-      }
-    }
-
-    if (match_case) {
-      s = strstr(tl->line, findstr);
-    }
-    else {
-      s = BLI_strcasestr(tl->line, findstr);
-    }
-    if (tl == startl) {
-      break;
-    }
-  }
-
-  if (s) {
-    int newl = txt_get_span(text->lines.first, tl);
-    int newc = (int)(s - tl->line);
-    txt_move_to(text, newl, newc, 0);
-    txt_move_to(text, newl, newc + strlen(findstr), 1);
-    return 1;
-  }
-  else {
-    return 0;
-  }
-}
-
 char *txt_sel_to_buf(Text *text, int *r_buf_strlen)
 {
   char *buf;
@@ -1670,9 +1633,70 @@ void txt_insert_buf(Text *text, const char *in_buffer)
   MEM_freeN(buffer);
 }
 
-/**************************/
-/* Line editing functions */
-/**************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Find String in Text
+ * \{ */
+
+int txt_find_string(Text *text, const char *findstr, int wrap, int match_case)
+{
+  TextLine *tl, *startl;
+  const char *s = NULL;
+
+  if (!text->curl || !text->sell) {
+    return 0;
+  }
+
+  txt_order_cursors(text, false);
+
+  tl = startl = text->sell;
+
+  if (match_case) {
+    s = strstr(&tl->line[text->selc], findstr);
+  }
+  else {
+    s = BLI_strcasestr(&tl->line[text->selc], findstr);
+  }
+  while (!s) {
+    tl = tl->next;
+    if (!tl) {
+      if (wrap) {
+        tl = text->lines.first;
+      }
+      else {
+        break;
+      }
+    }
+
+    if (match_case) {
+      s = strstr(tl->line, findstr);
+    }
+    else {
+      s = BLI_strcasestr(tl->line, findstr);
+    }
+    if (tl == startl) {
+      break;
+    }
+  }
+
+  if (s) {
+    int newl = txt_get_span(text->lines.first, tl);
+    int newc = (int)(s - tl->line);
+    txt_move_to(text, newl, newc, 0);
+    txt_move_to(text, newl, newc + strlen(findstr), 1);
+    return 1;
+  }
+  else {
+    return 0;
+  }
+}
+
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Line Editing Functions
+ * \{ */
 
 void txt_split_curline(Text *text)
 {
@@ -2294,9 +2318,11 @@ int txt_setcurr_tab_spaces(Text *text, int space)
   return i;
 }
 
-/*******************************/
-/* Character utility functions */
-/*******************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Character Queries
+ * \{ */
 
 int text_check_bracket(const char ch)
 {
@@ -2418,3 +2444,5 @@ int text_find_identifier_start(const char *str, int i)
   i++;
   return i;
 }
+
+/** \} */