Cleanup: doxy sections for camera, collections, text & seqmodifier

4 files changed, 268 insertions, 109 deletions

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 ec9d3cac5a1..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,11 @@ 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)
@@ -1281,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,
@@ -1367,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,
@@ -1460,7 +1519,11 @@ bool BKE_collection_move(Main *bmain,
   return true;
 }
 
-/**************************** Iterators ******************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Iterators
+ * \{ */
 
 /* scene collection iteractor */
 
@@ -1646,3 +1709,5 @@ void BKE_scene_objects_iterator_end(BLI_Iterator *iter)
     MEM_freeN(data);
   }
 }
+
+/** \} */
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/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;
 }
+
+/** \} */