Cleanup: use our own code style for doxy-gen comment blocks

intern/ghost/intern/GHOST_WindowCocoa.mm

@@ -1131,7 +1131,8 @@ GHOST_TSuccess GHOST_WindowCocoa::hasCursorShape(GHOST_TStandardCursor shape)
   return success;
 }
 
-/** Reverse the bits in a GHOST_TUns8
+/* Reverse the bits in a GHOST_TUns8 */
+#if 0
 static GHOST_TUns8 uns8ReverseBits(GHOST_TUns8 ch)
 {
   ch= ((ch >> 1) & 0x55) | ((ch << 1) & 0xAA);
@@ -1139,7 +1140,7 @@ static GHOST_TUns8 uns8ReverseBits(GHOST_TUns8 ch)
   ch= ((ch >> 4) & 0x0F) | ((ch << 4) & 0xF0);
   return ch;
 }
-*/
+#endif
 
 /** Reverse the bits in a GHOST_TUns16 */
 static GHOST_TUns16 uns16ReverseBits(GHOST_TUns16 shrt)

intern/guardedalloc/MEM_guardedalloc.h

@@ -57,9 +57,11 @@
 extern "C" {
 #endif
 
-/** Returns the length of the allocated memory segment pointed at
+/**
+ * Returns the length of the allocated memory segment pointed at
  * by vmemh. If the pointer was not previously allocated by this
- * module, the result is undefined.*/
+ * module, the result is undefined.
+ */
 extern size_t (*MEM_allocN_len)(const void *vmemh) ATTR_WARN_UNUSED_RESULT;
 
 /**
@@ -103,7 +105,8 @@ extern void *(*MEM_recallocN_id)(void *vmemh,
 /**
  * Allocate a block of memory of size len, with tag name str. The
  * memory is cleared. The name must be static, because only a
- * pointer to it is stored ! */
+ * pointer to it is stored!
+ */
 extern void *(*MEM_callocN)(size_t len, const char *str) /* ATTR_MALLOC */ ATTR_WARN_UNUSED_RESULT
     ATTR_ALLOC_SIZE(1) ATTR_NONNULL(2);
 
@@ -143,12 +146,15 @@ extern void *(*MEM_mallocN_aligned)(size_t len,
                                     const char *str) /* ATTR_MALLOC */ ATTR_WARN_UNUSED_RESULT
     ATTR_ALLOC_SIZE(1) ATTR_NONNULL(3);
 
-/** Print a list of the names and sizes of all allocated memory
+/**
- * blocks. as a python dict for easy investigation */
+ * Print a list of the names and sizes of all allocated memory
+ * blocks. as a python dict for easy investigation.
+ */
 extern void (*MEM_printmemlist_pydict)(void);
 
-/** Print a list of the names and sizes of all allocated memory
+/**
- * blocks. */
+ * Print a list of the names and sizes of all allocated memory blocks.
+ */
 extern void (*MEM_printmemlist)(void);
 
 /** calls the function on all allocated memory blocks. */
@@ -163,7 +169,8 @@ extern void (*MEM_set_error_callback)(void (*func)(const char *));
 /**
  * Are the start/end block markers still correct ?
  *
- * \retval true for correct memory, false for corrupted memory. */
+ * \retval true for correct memory, false for corrupted memory.
+ */
 extern bool (*MEM_consistency_check)(void);
 
 /** Attempt to enforce OSX (or other OS's) to have malloc and stack nonzero */
@@ -209,8 +216,10 @@ extern size_t (*MEM_get_peak_memory)(void) ATTR_WARN_UNUSED_RESULT;
 extern const char *(*MEM_name_ptr)(void *vmemh);
 #endif
 
-/** This should be called as early as possible in the program. When it has been called, information
+/**
- * about memory leaks will be printed on exit. */
+ * This should be called as early as possible in the program. When it has been called, information
+ * about memory leaks will be printed on exit.
+ */
 void MEM_init_memleak_detection(void);
 
 /**
@@ -219,9 +228,11 @@ void MEM_init_memleak_detection(void);
  */
 void MEM_use_memleak_detection(bool enabled);
 
-/** When this has been called and memory leaks have been detected, the process will have an exit
+/**
+ * When this has been called and memory leaks have been detected, the process will have an exit
  * code that indicates failure. This can be used for when checking for memory leaks with automated
- * tests. */
+ * tests.
+ */
 void MEM_enable_fail_on_memleak(void);
 
 /* Switch allocator to fast mode, with less tracking.

source/blender/blenkernel/BKE_curve.h

@@ -55,7 +55,7 @@ typedef struct CurveCache {
    * The first entry is the length between point 0 and 1 while the last is the
    * total length of the curve.
    *
-   * Used by 'BKE_where_on_path'. */
+   * Used by #BKE_where_on_path. */
   const float *anim_path_accum_length;
 } CurveCache;
 

source/blender/blenkernel/intern/anim_data.c

@@ -287,8 +287,10 @@ bool BKE_animdata_id_is_animated(const struct ID *id)
          !BLI_listbase_is_empty(&adt->overrides);
 }
 
-/** Callback used by lib_query to walk over all ID usages (mimics `foreach_id` callback of
+/**
- * `IDTypeInfo` structure). */
+ * Callback used by lib_query to walk over all ID usages (mimics `foreach_id` callback of
+ * `IDTypeInfo` structure).
+ */
 void BKE_animdata_foreach_id(AnimData *adt, LibraryForeachIDData *data)
 {
   LISTBASE_FOREACH (FCurve *, fcu, &adt->drivers) {

source/blender/blenkernel/intern/anim_sys.c

@@ -1605,8 +1605,9 @@ static bool nla_combine_get_inverted_strip_value(const int mix_mode,
   }
 }
 
-/** Accumulate quaternion channels for Combine mode according to influence.
+/**
- * \returns blended_value = lower_values @ strip_values^infl
+ * Accumulate quaternion channels for Combine mode according to influence.
+ * \returns `blended_value = lower_values @ strip_values^infl`
  */
 static void nla_combine_quaternion(const float lower_values[4],
                                    const float strip_values[4],
@@ -2094,8 +2095,10 @@ static void animsys_evaluate_nla_domain(PointerRNA *ptr, NlaEvalData *channels,
 
 /* ---------------------- */
 
-/** Tweaked strip is evaluated differently from other strips. Adjacent strips are ignored
+/**
- * and includes a workaround for when user is not editing in place. */
+ * Tweaked strip is evaluated differently from other strips. Adjacent strips are ignored
+ * and includes a workaround for when user is not editing in place.
+ */
 static void animsys_create_tweak_strip(const AnimData *adt,
                                        const bool keyframing_to_strip,
                                        NlaStrip *r_tweak_strip)
@@ -2210,8 +2213,10 @@ static bool is_nlatrack_evaluatable(const AnimData *adt, const NlaTrack *nlt)
   return true;
 }
 
-/** Check for special case of non-pushed action being evaluated with no NLA influence (off and no
+/**
- * strips evaluated) nor NLA interference (ensure NLA not soloing). */
+ * Check for special case of non-pushed action being evaluated with no NLA influence (off and no
+ * strips evaluated) nor NLA interference (ensure NLA not soloing).
+ */
 static bool is_action_track_evaluated_without_nla(const AnimData *adt,
                                                   const bool any_strip_evaluated)
 {
@@ -2491,7 +2496,8 @@ void nlasnapshot_ensure_channels(NlaEvalData *eval_data, NlaEvalSnapshot *snapsh
   }
 }
 
-/** Blends the \a lower_snapshot with the \a upper_snapshot into \a r_blended_snapshot according
+/**
+ * Blends the \a lower_snapshot with the \a upper_snapshot into \a r_blended_snapshot according
  * to the given \a upper_blendmode and \a upper_influence.
  *
  * For \a upper_snapshot, blending limited to values in the \a blend_domain. For Replace blendmode,

source/blender/blenkernel/intern/collection.c

@@ -2168,11 +2168,13 @@ void BKE_scene_objects_iterator_end(BLI_Iterator *iter)
   }
 }
 
-/** Generate a new GSet (or extend given `objects_gset` if not NULL) with all objects referenced by
+/**
+ * Generate a new GSet (or extend given `objects_gset` if not NULL) with all objects referenced by
  * all collections of given `scene`.
  *
  * \note: This will include objects without a base currently (because they would belong to excluded
- * collections only e.g.). */
+ * collections only e.g.).
+ */
 GSet *BKE_scene_objects_as_gset(Scene *scene, GSet *objects_gset)
 {
   BLI_Iterator iter;

source/blender/blenkernel/intern/fcurve.c

@@ -181,8 +181,10 @@ void BKE_fcurves_copy(ListBase *dst, ListBase *src)
   }
 }
 
-/** Callback used by lib_query to walk over all ID usages (mimics `foreach_id` callback of
+/**
- * `IDTypeInfo` structure). */
+ * Callback used by lib_query to walk over all ID usages (mimics `foreach_id` callback of
+ * `IDTypeInfo` structure).
+ */
 void BKE_fcurve_foreach_id(FCurve *fcu, LibraryForeachIDData *data)
 {
   ChannelDriver *driver = fcu->driver;
@@ -1508,7 +1510,8 @@ bool test_time_fcurve(FCurve *fcu)
 /** \name F-Curve Calculations
  * \{ */
 
-/* The length of each handle is not allowed to be more
+/**
+ * The length of each handle is not allowed to be more
  * than the horizontal distance between (v1-v4).
  * This is to prevent curve loops.
  *
@@ -1555,9 +1558,13 @@ void BKE_fcurve_correct_bezpart(const float v1[2], float v2[2], float v3[2], con
   }
 }
 
-/** Find roots of cubic equation (c0 x³ + c1 x² + c2 x + c3)
+/**
+   .
+ * Find roots of cubic equation (c0 x³ + c1 x² + c2 x + c3)
  * \return number of roots in `o`.
- * NOTE: it is up to the caller to allocate enough memory for `o`. */
+ *
+ * \note it is up to the caller to allocate enough memory for `o`.
+ */
 static int solve_cubic(double c0, double c1, double c2, double c3, float *o)
 {
   double a, b, c, p, q, d, t, phi;

source/blender/blenkernel/intern/gpencil.c

@@ -1293,7 +1293,8 @@ bGPDframe *BKE_gpencil_layer_frame_find(bGPDlayer *gpl, int cframe)
   return NULL;
 }
 
-/** Get the appropriate gp-frame from a given layer
+/**
+ * Get the appropriate gp-frame from a given layer
  * - this sets the layer's actframe var (if allowed to)
  * - extension beyond range (if first gp-frame is after all frame in interest and cannot add)
  *

source/blender/blenkernel/intern/gpencil_modifier.c

@@ -616,7 +616,8 @@ static int gpencil_remap_time_get(Depsgraph *depsgraph, Scene *scene, Object *ob
   return remap_cfra;
 }
 
-/** Get the current frame re-timed with time modifiers.
+/**
+ * Get the current frame re-timed with time modifiers.
  * \param depsgraph: Current depsgraph.
  * \param scene: Current scene
  * \param ob: Grease pencil object
@@ -746,7 +747,8 @@ void BKE_gpencil_prepare_eval_data(Depsgraph *depsgraph, Scene *scene, Object *o
   BKE_gpencil_update_orig_pointers(ob_orig, ob);
 }
 
-/** Calculate gpencil modifiers.
+/**
+ * Calculate gpencil modifiers.
  * \param depsgraph: Current depsgraph
  * \param scene: Current scene
  * \param ob: Grease pencil object

source/blender/blenkernel/intern/lib_override.c

@@ -218,10 +218,12 @@ static ID *lib_override_library_create_from(Main *bmain, ID *reference_id)
   return local_id;
 }
 
-/** Check if given ID has some override rules that actually indicate the user edited it.
+/**
+ * Check if given ID has some override rules that actually indicate the user edited it.
  *
- * TODO: This could be simplified by storing a flag in IDOverrideLibrary during the diffing
+ * TODO: This could be simplified by storing a flag in #IDOverrideLibrary during the diffing
- * process? */
+ * process?
+ */
 bool BKE_lib_override_library_is_user_edited(struct ID *id)
 {
   if (!ID_IS_OVERRIDE_LIBRARY(id)) {
@@ -2407,8 +2409,10 @@ ID *BKE_lib_override_library_operations_store_start(Main *bmain,
   return storage_id;
 }
 
-/** Restore given ID modified by \a BKE_lib_override_library_operations_store_start, to its
+/**
- * original state. */
+ * Restore given ID modified by #BKE_lib_override_library_operations_store_start, to its
+ * original state.
+ */
 void BKE_lib_override_library_operations_store_end(
     OverrideLibraryStorage *UNUSED(override_storage), ID *local)
 {

source/blender/blenkernel/intern/mesh_boolean_convert.cc

@@ -231,7 +231,8 @@ const MEdge *MeshesToIMeshInfo::input_medge_for_orig_index(int orig_index,
   return medge;
 }
 
-/** Convert all of the meshes in `meshes` to an `IMesh` and return that.
+/**
+ * Convert all of the meshes in `meshes` to an `IMesh` and return that.
  * All of the coordinates are transformed into the local space of the
  * first Mesh. To do this transformation, we also need the transformation
  * obmats corresponding to the Meshes, so they are in the `obmats` argument.
@@ -638,7 +639,8 @@ static void copy_or_interp_loop_attributes(Mesh *dest_mesh,
   }
 }
 
-/** Make sure that there are custom data layers in the target mesh
+/**
+ * Make sure that there are custom data layers in the target mesh
  * corresponding to all target layers in all of the operands after the first.
  * (The target should already have layers for those in the first operand mesh).
  * Edges done separately -- will have to be done later, after edges are made.
@@ -673,7 +675,8 @@ static void merge_edge_customdata_layers(Mesh *target, MeshesToIMeshInfo &mim)
   }
 }
 
-/** Convert the output IMesh im to a Blender Mesh,
+/**
+ * Convert the output IMesh im to a Blender Mesh,
  * using the information in mim to get all the attributes right.
  */
 static Mesh *imesh_to_mesh(IMesh *im, MeshesToIMeshInfo &mim)

source/blender/blenkernel/intern/nla.c

@@ -434,8 +434,10 @@ NlaStrip *BKE_nla_add_soundstrip(Main *bmain, Scene *scene, Speaker *speaker)
   return strip;
 }
 
-/** Callback used by lib_query to walk over all ID usages (mimics `foreach_id` callback of
+/**
- * `IDTypeInfo` structure). */
+ * Callback used by lib_query to walk over all ID usages (mimics `foreach_id` callback of
+ * `IDTypeInfo` structure).
+ */
 void BKE_nla_strip_foreach_id(NlaStrip *strip, LibraryForeachIDData *data)
 {
   BKE_LIB_FOREACHID_PROCESS(data, strip->act, IDWALK_CB_USER);
@@ -1380,8 +1382,10 @@ static void nlastrip_fix_resize_overlaps(NlaStrip *strip)
   }
 }
 
-/** Recalculate the start and end frames for the strip to match the bounds of its action such that
+/**
- * the overall NLA animation result is unchanged. */
+ * Recalculate the start and end frames for the strip to match the bounds of its action such that
+ * the overall NLA animation result is unchanged.
+ */
 void BKE_nlastrip_recalculate_bounds_sync_action(NlaStrip *strip)
 {
   float prev_actstart;

source/blender/blenkernel/intern/node.cc

@@ -3096,10 +3096,12 @@ void ntreeSetOutput(bNodeTree *ntree)
    * might be different for editor or for "real" use... */
 }
 
-/** Get address of potential nodetree pointer of given ID.
+/**
+ * Get address of potential node-tree pointer of given ID.
  *
  * \warning Using this function directly is potentially dangerous, if you don't know or are not
- * sure, please use `ntreeFromID()` instead. */
+ * sure, please use `ntreeFromID()` instead.
+ */
 bNodeTree **BKE_ntree_ptr_from_id(ID *id)
 {
   switch (GS(id->name)) {

source/blender/blenkernel/intern/object.c

@@ -1359,8 +1359,9 @@ static bool object_modifier_type_copy_check(ModifierType md_type)
   return !ELEM(md_type, eModifierType_Hook, eModifierType_Collision);
 }
 
-/** Find a `psys` matching given `psys_src` in `ob_dst` (i.e. sharing the same ParticleSettings
+/**
- * ID), or add one, and return valid `psys` from `ob_dst`.
+ * Find a `psys` matching given `psys_src` in `ob_dst` (i.e. sharing the same ParticleSettings ID),
+ * or add one, and return valid `psys` from `ob_dst`.
  *
  * \note Order handling is fairly weak here. This code assumes that it is called **before** the
  * modifier using the psys is actually copied, and that this copied modifier will be added at the
@@ -1392,7 +1393,8 @@ static ParticleSystem *object_copy_modifier_particle_system_ensure(Main *bmain,
   return psys_dst;
 }
 
-/** Copy a single modifier.
+/**
+ * Copy a single modifier.
  *
  * \note **Do not** use this function to copy a whole modifier stack (see note below too). Use
  * `BKE_object_modifier_stack_copy` instead.
@@ -1400,7 +1402,8 @@ static ParticleSystem *object_copy_modifier_particle_system_ensure(Main *bmain,
  * \note Complex modifiers relaying on other data (like e.g. dynamic paint or fluid using particle
  * systems) are not always 100% 'correctly' copied here, since we have to use heuristics to decide
  * which particle system to use or add in `ob_dst`, and it's placement in the stack, etc. If used
- * more than once, this function should preferably be called in stack order. */
+ * more than once, this function should preferably be called in stack order.
+ */
 bool BKE_object_copy_modifier(
     Main *bmain, Scene *scene, Object *ob_dst, const Object *ob_src, ModifierData *md_src)
 {
@@ -1500,10 +1503,12 @@ bool BKE_object_copy_modifier(
   return true;
 }
 
-/** Copy a single GPencil modifier.
+/**
+ * Copy a single GPencil modifier.
  *
  * \note **Do not** use this function to copy a whole modifier stack. Use
- * `BKE_object_modifier_stack_copy` instead. */
+ * `BKE_object_modifier_stack_copy` instead.
+ */
 bool BKE_object_copy_gpencil_modifier(struct Object *ob_dst, GpencilModifierData *gmd_src)
 {
   BLI_assert(ob_dst->type == OB_GPENCIL);

source/blender/blenkernel/intern/text.c

@@ -523,7 +523,8 @@ Text *BKE_text_load_ex(Main *bmain, const char *file, const char *relpath, const
   return ta;
 }
 
-/** Load a text file.
+/**
+ * Load a text file.
  *
  * \note Text data-blocks have no user by default, only the 'real user' flag.
  */

source/blender/bmesh/tools/bmesh_boolean.cc

@@ -38,7 +38,8 @@ namespace blender::meshintersect {
 
 #ifdef WITH_GMP
 
-/** Make a #blender::meshintersect::Mesh from #BMesh bm.
+/**
+ * Make a #blender::meshintersect::Mesh from #BMesh bm.
  * We are given a triangulation of it from the caller via #looptris,
  * which are looptris_tot triples of loops that together tessellate
  * the faces of bm.

source/blender/editors/animation/keyframing.c

@@ -483,7 +483,8 @@ int insert_bezt_fcurve(FCurve *fcu, const BezTriple *bezt, eInsertKeyFlags flag)
   return i;
 }
 
-/** Update the FCurve to allow insertion of `bezt` without modifying the curve shape.
+/**
+ * Update the FCurve to allow insertion of `bezt` without modifying the curve shape.
  *
  * Checks whether it is necessary to apply Bezier subdivision due to involvement of non-auto
  * handles. If necessary, changes `bezt` handles from Auto to Aligned.

source/blender/editors/space_nla/nla_draw.c

@@ -408,8 +408,10 @@ static uint nla_draw_use_dashed_outlines(const float color[4], bool muted)
   return shdr_pos;
 }
 
-/** This check only accounts for the track's disabled flag and whether the strip is being tweaked.
+/**
- * It does not account for muting or soloing. */
+ * This check only accounts for the track's disabled flag and whether the strip is being tweaked.
+ * It does not account for muting or soloing.
+ */
 static bool is_nlastrip_enabled(AnimData *adt, NlaTrack *nlt, NlaStrip *strip)
 {
   /** This shouldn't happen. If passed NULL, then just treat strip as enabled. */

source/blender/editors/undo/ed_undo.c

@@ -273,9 +273,11 @@ static void ed_undo_step_post(bContext *C,
   }
 }
 
-/** Undo or redo one step from current active one.
+/**
- *  May undo or redo several steps at once only if the target step is a 'skipped' one.
+ * Undo or redo one step from current active one.
- *  The target step will be the one immediately before or after the active one. */
+ * May undo or redo several steps at once only if the target step is a 'skipped' one.
+ * The target step will be the one immediately before or after the active one.
+ */
 static int ed_undo_step_direction(bContext *C, enum eUndoStepDir step, ReportList *reports)
 {
   BLI_assert(ELEM(step, STEP_UNDO, STEP_REDO));
@@ -308,9 +310,11 @@ static int ed_undo_step_direction(bContext *C, enum eUndoStepDir step, ReportLis
   return OPERATOR_FINISHED;
 }
 
-/** Undo the step matching given name.
+/**
- *  May undo several steps at once.
+ * Undo the step matching given name.
- *  The target step will be the one immediately before given named one. */
+ * May undo several steps at once.
+ * The target step will be the one immediately before given named one.
+ */
 static int ed_undo_step_by_name(bContext *C, const char *undo_name, ReportList *reports)
 {
   BLI_assert(undo_name != NULL);
@@ -354,9 +358,11 @@ static int ed_undo_step_by_name(bContext *C, const char *undo_name, ReportList *
   return OPERATOR_FINISHED;
 }
 
-/** Load the step matching given index in the stack.
+/**
- *  May undo or redo several steps at once.
+ * Load the step matching given index in the stack.
- *  The target step will be the one indicated by the given index. */
+ * May undo or redo several steps at once.
+ * The target step will be the one indicated by the given index.
+ */
 static int ed_undo_step_by_index(bContext *C, const int undo_index, ReportList *reports)
 {
   BLI_assert(undo_index >= 0);

source/blender/gpu/opengl/gl_texture.cc

@@ -290,7 +290,9 @@ void GLTexture::update_sub(
   }
 }
 
-/** This will create the mipmap images and populate them with filtered data from base level.
+/**
+ * This will create the mipmap images and populate them with filtered data from base level.
+ *
  * WARNING: Depth textures are not populated but they have their mips correctly defined.
  * WARNING: This resets the mipmap range.
  */