Cleanup: consistent doxygen comment blocks

Also remove doxygen block for comments in a functions body.
2023-05-27 15:10:58 +10:00
parent 9249cec6f2
commit 823685db76
81 changed files with 292 additions and 193 deletions
@@ -104,9 +104,9 @@
 *   merged in docs.
 */

-/**
- * \defgroup gui GUI
- * \ingroup blender */
+/** \defgroup gui GUI
+ *  \ingroup blender
+ */

 /** \defgroup wm Window Manager
 *  \ingroup gui */
@@ -1171,9 +1171,10 @@ class Octree {
    return nleaf;
  }

-  /** Locate a leaf
-   * WARNING: assuming this leaf already exists! */
-
+  /**
+   * Locate a leaf
+   * WARNING: assuming this leaf already exists!
+   */
  LeafNode *locateLeaf(int st[3])
  {
    Node *node = (Node *)root;
@@ -36,8 +36,10 @@ class AssetStorage;
 */
 class AssetLibrary {
  eAssetLibraryType library_type_;
-  /** The name this asset library will be displayed in the UI as. Will also be used as a weak way
-   * to identify an asset library (e.g. by #AssetWeakReference). */
+  /**
+   * The name this asset library will be displayed in the UI as. Will also be used as a weak way
+   * to identify an asset library (e.g. by #AssetWeakReference).
+   */
  std::string name_;
  /** If this is an asset library on disk, the top-level directory path. Normalized using
   * #normalize_directory_path(). Shared pointer so assets can safely point to it, and don't have
@@ -45,7 +47,8 @@ class AssetLibrary {
   * optimization is used). With thousands of assets this might make a reasonable difference. */
  std::shared_ptr<std::string> root_path_;

-  /** Storage for assets (better said their representations) that are considered to be part of this
+  /**
+   * Storage for assets (better said their representations) that are considered to be part of this
   * library. Assets are not automatically loaded into this when loading an asset library. Assets
   * have to be loaded externally and added to this storage via #add_external_asset() or
   * #add_local_id_asset(). So this really is arbitrary storage as far as #AssetLibrary is
@@ -122,13 +125,15 @@ class AssetLibrary {
                                          std::unique_ptr<AssetMetaData> metadata);
  /** See #AssetLibrary::add_external_asset(). */
  AssetRepresentation &add_local_id_asset(StringRef relative_asset_path, ID &id);
-  /** Remove an asset from the library that was added using #add_external_asset() or
+  /**
+   * Remove an asset from the library that was added using #add_external_asset() or
   * #add_local_id_asset(). Can usually be expected to be constant time complexity (worst case may
   * differ).
   * \note This is save to call if \a asset is freed (dangling reference), will not perform any
   *       change then.
   * \return True on success, false if the asset couldn't be found inside the library (also the
-   *         case when the reference is dangling). */
+   *         case when the reference is dangling).
+   */
  bool remove_asset(AssetRepresentation &asset);

  /**
@@ -143,7 +148,8 @@ class AssetLibrary {
   *
   * No-op if the catalog cannot be found. This could be the kind of "the
   * catalog definition file is corrupt/lost" scenario that the simple name is
-   * meant to help recover from. */
+   * meant to help recover from.
+   */
  void refresh_catalog_simplename(AssetMetaData *asset_data);

  void on_blend_save_handler_register();
@@ -30,8 +30,10 @@ class AssetLibrary;

 class AssetRepresentation {
  AssetIdentifier identifier_;
-  /** Indicate if this is a local or external asset, and as such, which of the union members below
-   * should be used. */
+  /**
+   * Indicate if this is a local or external asset, and as such, which of the union members below
+   * should be used.
+   */
  const bool is_local_id_ = false;
  /** Asset library that owns this asset representation. */
  const AssetLibrary *owner_asset_library_;
@@ -53,8 +55,10 @@ class AssetRepresentation {
                      StringRef name,
                      std::unique_ptr<AssetMetaData> metadata,
                      const AssetLibrary &owner_asset_library);
-  /** Constructs an asset representation for an ID stored in the current file. This makes the asset
-   * local and fully editable. */
+  /**
+   * Constructs an asset representation for an ID stored in the current file. This makes the asset
+   * local and fully editable.
+   */
  AssetRepresentation(AssetIdentifier &&identifier,
                      ID &id,
                      const AssetLibrary &owner_asset_library);
@@ -71,7 +75,8 @@ class AssetRepresentation {

  const AssetIdentifier &get_identifier() const;

-  /** Create a weak reference for this asset that can be written to files, but can break under a
+  /**
+   * Create a weak reference for this asset that can be written to files, but can break under a
   * number of conditions.
   * A weak reference can only be created if an asset representation is owned by an asset library.
   */
@@ -79,18 +84,23 @@ class AssetRepresentation {

  StringRefNull get_name() const;
  AssetMetaData &get_metadata() const;
-  /** Get the import method to use for this asset. A different one may be used if
+  /**
+   * Get the import method to use for this asset. A different one may be used if
   * #may_override_import_method() returns true, otherwise, the returned value must be used. If
   * there is no import method predefined for this asset no value is returned.
   */
  std::optional<eAssetImportMethod> get_import_method() const;
-  /** Returns if this asset may be imported with an import method other than the one returned by
+  /**
+   * Returns if this asset may be imported with an import method other than the one returned by
   * #get_import_method(). Also returns true if there is no predefined import method
-   * (when #get_import_method() returns no value). */
+   * (when #get_import_method() returns no value).
+   */
  bool may_override_import_method() const;
  bool get_use_relative_path() const;
-  /** If this asset is stored inside this current file (#is_local_id() is true), this returns the
-   * ID's pointer, otherwise null. */
+  /**
+   * If this asset is stored inside this current file (#is_local_id() is true), this returns the
+   * ID's pointer, otherwise null.
+   */
  ID *local_id() const;
  /** Returns if this asset is stored inside this current file, and as such fully editable. */
  bool is_local_id() const;
@@ -103,9 +113,11 @@ class AssetRepresentation {
 struct AssetRepresentation;

 std::string AS_asset_representation_full_path_get(const ::AssetRepresentation *asset);
-/** Get the absolute path to the .blend file containing the given asset. String will be empty if
+/**
+ * Get the absolute path to the .blend file containing the given asset. String will be empty if
 * the asset could not be mapped to a valid .blend file path. Valid in this case also means that
- * the file needs to exist on disk. */
+ * the file needs to exist on disk.
+ */
 std::string AS_asset_representation_full_library_path_get(const ::AssetRepresentation *asset);
 std::optional<eAssetImportMethod> AS_asset_representation_import_method_get(
    const ::AssetRepresentation *asset_handle);
@@ -142,9 +142,9 @@ struct DerivedMesh {
  DMFlagMat *(*getGridFlagMats)(DerivedMesh *dm);
  unsigned int **(*getGridHidden)(DerivedMesh *dm);

-  /** Direct Access Operations
+  /* Direct Access Operations
   * - Can be undefined
-   * - Must be defined for modifiers that only deform however */
+   * - Must be defined for modifiers that only deform however. */

  /** Release reference to the DerivedMesh. This function decides internally
   * if the DerivedMesh will be freed, or cached for later use. */
@@ -93,7 +93,8 @@ typedef struct BPathForeachPathData {
  /** ID owning the path being processed. */
  struct ID *owner_id;

-  /** IDTypeInfo callbacks are responsible to set this boolean if they modified one or more  paths.
+  /**
+   * IDTypeInfo callbacks are responsible to set this boolean if they modified one or more paths.
   */
  bool is_path_modified;
 } BPathForeachPathData;
@@ -647,7 +647,8 @@ bool BKE_id_can_be_asset(const struct ID *id);
 */
 struct ID *BKE_id_owner_get(struct ID *id);

-/** Check if that ID can be considered as editable from a high-level (editor) perspective.
+/**
+ * Check if that ID can be considered as editable from a high-level (editor) perspective.
 *
 * NOTE: This used to be done with a check on whether ID was linked or not, but now with system
 * overrides this is not enough anymore.
@@ -311,7 +311,8 @@ void BKE_lib_override_library_property_delete(struct IDOverrideLibrary *override
 bool BKE_lib_override_library_property_search_and_delete(struct IDOverrideLibrary *override,
                                                         const char *rna_path);

-/** Change the RNA path of a library override on a property.
+/**
+ * Change the RNA path of a library override on a property.
 *
 * No-op if the property override cannot be found.
 *
@@ -131,11 +131,14 @@ typedef int (*LibraryIDLinkCallback)(LibraryIDLinkCallbackData *cb_data);
 /* Flags for the foreach function itself. */
 enum {
  IDWALK_NOP = 0,
-  /** The callback will never modify the ID pointers it processes.
+  /**
+   * The callback will never modify the ID pointers it processes.
   * WARNING: It is very important to pass this flag when valid, as it can lead to important
-   * optimizations and debug/assert code. */
+   * optimizations and debug/assert code.
+   */
  IDWALK_READONLY = (1 << 0),
-  /** Recurse into 'descendant' IDs.
+  /**
+   * Recurse into 'descendant' IDs.
   * Each ID is only processed once. Order of ID processing is not guaranteed.
   *
   * Also implies IDWALK_READONLY, and excludes IDWALK_DO_INTERNAL_RUNTIME_POINTERS.
@@ -73,20 +73,27 @@ enum {
   */
  ID_REMAP_FORCE_OBDATA_IN_EDITMODE = 1 << 7,

-  /** Don't touch the special user counts (use when the 'old' remapped ID remains in use):
+  /**
+   * Don't touch the special user counts (use when the 'old' remapped ID remains in use):
   * - Do not transfer 'fake user' status from old to new ID.
-   * - Do not clear 'extra user' from old ID. */
+   * - Do not clear 'extra user' from old ID.
+   */
  ID_REMAP_SKIP_USER_CLEAR = 1 << 16,
-  /** Force handling user count even for IDs that are outside of Main (used in some cases when
+  /**
+   * Force handling user count even for IDs that are outside of Main (used in some cases when
   * dealing with IDs temporarily out of Main, but which will be put in it ultimately).
   */
  ID_REMAP_FORCE_USER_REFCOUNT = 1 << 17,
-  /** Do NOT handle user count for IDs (used in some cases when dealing with IDs from different
+  /**
+   * Do NOT handle user count for IDs (used in some cases when dealing with IDs from different
   * BMains, if usercount will be recomputed anyway afterwards, like e.g. in memfile reading during
-   * undo step decoding). */
+   * undo step decoding).
+   */
  ID_REMAP_SKIP_USER_REFCOUNT = 1 << 18,
-  /** Do NOT tag IDs which had some of their ID pointers updated for update in the depsgraph, or ID
-   * type specific updates, like e.g. with node trees. */
+  /**
+   * Do NOT tag IDs which had some of their ID pointers updated for update in the depsgraph, or ID
+   * type specific updates, like e.g. with node trees.
+   */
  ID_REMAP_SKIP_UPDATE_TAGGING = 1 << 19,
  /**
   * Do not attempt to access original ID pointers (triggers usages of
@@ -63,7 +63,8 @@ void BKE_main_namemap_remove_name(struct Main *bmain, struct ID *id, const char
 */
 bool BKE_main_namemap_validate(struct Main *bmain) ATTR_NONNULL();

-/** Same as #BKE_main_namemap_validate, but also fixes any issue by re-generating all name maps,
+/**
+ * Same as #BKE_main_namemap_validate, but also fixes any issue by re-generating all name maps,
 * and ensuring again all ID names are unique.
 *
 * This is typically only used in `do_versions` code to fix broken files.
@@ -52,7 +52,8 @@ typedef struct UvElement {
  unsigned int island;
 } UvElement;

-/** UvElementMap is a container for UvElements of a BMesh.
+/**
+ * UvElementMap is a container for UvElements of a BMesh.
 *
 * It simplifies access to UV information and ensures the
 * different UV selection modes are respected.
@@ -316,7 +316,8 @@ typedef struct bNodeType {
  bool (*poll)(const struct bNodeType *ntype,
               const struct bNodeTree *nodetree,
               const char **r_disabled_hint);
-  /** Can this node be added to a node tree?
+  /**
+   * Can this node be added to a node tree?
   * \param r_disabled_hint: See `poll()`.
   */
  bool (*poll_instance)(const struct bNode *node,
@@ -96,7 +96,8 @@ class bNodeTreeRuntime : NonCopyable, NonMovable {
   */
  NodeIDVectorSet nodes_by_id;

-  /** Execution data.
+  /**
+   * Execution data.
   *
   * XXX It would be preferable to completely move this data out of the underlying node tree,
   * so node tree execution could finally run independent of the tree itself.
@@ -726,7 +726,8 @@ void BKE_pbvh_face_iter_step(PBVHFaceIter *fd);
 bool BKE_pbvh_face_iter_done(PBVHFaceIter *fd);
 void BKE_pbvh_face_iter_finish(PBVHFaceIter *fd);

-/** Iterate over faces inside a PBVHNode.  These are either base mesh faces
+/**
+ * Iterate over faces inside a #PBVHNode. These are either base mesh faces
 * (for PBVH_FACES and PBVH_GRIDS) or BMesh faces (for PBVH_BMESH).
 */
 #define BKE_pbvh_face_iter_begin(pbvh, node, fd) \
@@ -2490,7 +2490,8 @@ static void nlaevalchan_combine_quaternion_get_inverted_lower_evalchan(
  BLI_bitmap_set_all(r_lower_necs->remap_domain.ptr, true, 4);
 }

-/** Based on blendmode and mix mode, solve for the lower values such that when lower blended or
+/**
+ * Based on blendmode and mix mode, solve for the lower values such that when lower blended or
 * combined with upper then we get blended values as a result.
 *
 * Only processes blended values in the remap domain. Successfully remapped lower values are placed
@@ -3496,10 +3497,9 @@ static void animsys_evaluate_nla_for_keyframing(PointerRNA *ptr,
    }
  }

-  /** NOTE: Although we early out, we can still keyframe to the non-pushed action since the
+  /* NOTE: Although we early out, we can still keyframe to the non-pushed action since the
   * keyframe remap function detects (r_context->strip.act == NULL) and will keyframe without
-   * remapping.
-   */
+   * remapping. */
  if (is_action_track_evaluated_without_nla(adt, has_strips)) {
    BLI_freelistN(&lower_estrips);
    return;
@@ -765,7 +765,8 @@ CustomDataLayer *BKE_id_attribute_from_index(ID *id,
  return nullptr;
 }

-/** Get list of domain types but with ATTR_DOMAIN_FACE and
+/**
+ * Get list of domain types but with ATTR_DOMAIN_FACE and
 * ATTR_DOMAIN_CORNER swapped.
 */
 static void get_domains_types(eAttrDomain domains[ATTR_DOMAIN_NUM])
@@ -251,7 +251,8 @@ void BKE_bpath_missing_files_check(Main *bmain, ReportList *reports)
 #define MAX_DIR_RECURSE 16
 #define FILESIZE_INVALID_DIRECTORY -1

-/** Find the given filename recursively in the given search directory and its sub-directories.
+/**
+ * Find the given filename recursively in the given search directory and its sub-directories.
 *
 * \note Use the biggest matching file found, so that thumbnails don't get used by mistake.
 *
@@ -1864,9 +1864,8 @@ KeyBlock *BKE_keyblock_add(Key *key, const char *name)
  kb->slidermin = 0.0f;
  kb->slidermax = 1.0f;

-  /**
-   * \note caller may want to set this to current time, but don't do it here since we need to sort
-   * which could cause problems in some cases, see #BKE_keyblock_add_ctime */
+  /* \note caller may want to set this to current time, but don't do it here since we need to sort
+   * which could cause problems in some cases, see #BKE_keyblock_add_ctime. */
  kb->pos = curpos + 0.1f; /* only used for absolute shape keys */

  return kb;
@@ -152,8 +152,10 @@ static bool lib_id_library_local_paths_callback(BPathForeachPathData *bpath_data
 /**
 * This has to be called from each make_local_* func, we could call from BKE_lib_id_make_local()
 * but then the make local functions would not be self contained.
- * Also note that the id _must_ have a library - campbell */
-/* TODO: This can probably be replaced by an ID-level version of #BKE_bpath_relative_rebase. */
+ *
+ * NOTE(@ideasman42): that the id _must_ have a library.
+ * TODO: This can probably be replaced by an ID-level version of #BKE_bpath_relative_rebase.
+ */
 static void lib_id_library_local_paths(Main *bmain, Library *lib, ID *id)
 {
  const char *bpath_user_data[2] = {BKE_main_blendfile_path(bmain), lib->filepath_abs};
@@ -1754,19 +1756,19 @@ static void library_make_local_copying_check(ID *id,
  BLI_gset_remove(loop_tags, id, NULL);
 }

-/* NOTE: Old (2.77) version was simply making (tagging) data-blocks as local,
- * without actually making any check whether they were also indirectly used or not...
- *
- * Current version uses regular id_make_local callback, with advanced pre-processing step to
- * detect all cases of IDs currently indirectly used, but which will be used by local data only
- * once this function is finished.  This allows to avoid any unneeded duplication of IDs, and
- * hence all time lost afterwards to remove orphaned linked data-blocks. */
 void BKE_library_make_local(Main *bmain,
                            const Library *lib,
                            GHash *old_to_new_ids,
                            const bool untagged_only,
                            const bool set_fake)
 {
+  /* NOTE: Old (2.77) version was simply making (tagging) data-blocks as local,
+   * without actually making any check whether they were also indirectly used or not...
+   *
+   * Current version uses regular id_make_local callback, with advanced pre-processing step to
+   * detect all cases of IDs currently indirectly used, but which will be used by local data only
+   * once this function is finished.  This allows to avoid any unneeded duplication of IDs, and
+   * hence all time lost afterwards to remove orphaned linked data-blocks. */

  ListBase *lbarray[INDEX_ID_MAX];

@@ -2351,9 +2351,10 @@ int BKE_sculptsession_vertex_count(const SculptSession *ss)
  return 0;
 }

-/** Returns pointer to a CustomData associated with a given domain, if
+/**
+ * Returns pointer to a CustomData associated with a given domain, if
 * one exists.  If not nullptr is returned (this may happen with e.g.
- * multires and ATTR_DOMAIN_POINT).
+ * multires and #ATTR_DOMAIN_POINT).
 */
 static CustomData *sculpt_get_cdata(Object *ob, eAttrDomain domain)
 {
@@ -285,8 +285,9 @@ BLI_INLINE void BLI_listbase_clear(struct ListBase *lb)
  lb->first = lb->last = (void *)0;
 }

-/** Validate the integrity of a given ListBase, returns `true` if everything is OK, false
- * otherwise.
+/**
+ * Validate the integrity of a given ListBase.
+ * \return true if everything is OK, false otherwise.
 */
 bool BLI_listbase_validate(struct ListBase *lb);

@@ -97,7 +97,8 @@ typedef struct BLI_mempool_iter {
 /** #BLI_mempool.flag */
 enum {
  BLI_MEMPOOL_NOP = 0,
-  /** allow iterating on this mempool.
+  /**
+   * Allow iterating on this mempool.
   *
   * \note this requires that the first four bytes of the elements
   * never begin with 'free' (#FREEWORD).
@@ -66,8 +66,9 @@
 namespace blender {

 template<
-    /** Type of the elements that are stored in this set. It has to be movable. Furthermore, the
-     * hash and is-equal functions have to support it.
+    /**
+     * Type of the elements that are stored in this set. It has to be movable.
+     * Furthermore, the hash and is-equal functions have to support it.
     */
    typename Key,
    /**
@@ -302,7 +302,8 @@ static BVHNode *bvh_medianof3(BVHNode **a, int lo, int mid, int hi, int axis)
 /**
 * \note after a call to this function you can expect one of:
 * - every node to left of a[n] are smaller or equal to it
- * - every node to the right of a[n] are greater or equal to it */
+ * - every node to the right of a[n] are greater or equal to it.
+ */
 static void partition_nth_element(BVHNode **a, int begin, int end, const int n, const int axis)
 {
  while (end - begin > 3) {
@@ -400,8 +401,9 @@ static void refit_kdop_hull(const BVHTree *tree, BVHNode *node, int start, int e
 }

 /**
- * only supports x,y,z axis in the moment
- * but we should use a plain and simple function here for speed sake */
+ * Only supports x,y,z axis in the moment
+ * but we should use a plain and simple function here for speed sake.
+ */
 static char get_largest_axis(const float *bv)
 {
  float middle_point[3];
@@ -423,7 +425,8 @@ static char get_largest_axis(const float *bv)

 /**
 * bottom-up update of bvh node BV
- * join the children on the parent BV */
+ * join the children on the parent BV.
+ */
 static void node_join(BVHTree *tree, BVHNode *node)
 {
  int i;
@@ -122,10 +122,8 @@ struct SortInfo {
  void *thunk;
 #endif

-  /**
-   * Invariant: `ranks[i] == NULL || length(ranks[i]) >= 2**(i+1)`.
-   *
-   * ~ 128 bytes on 32bit, ~ 512 bytes on 64bit */
+  /* Invariant: `ranks[i] == NULL || length(ranks[i]) >= 2**(i+1)`.
+   * ~ 128 bytes on 32bit, ~ 512 bytes on 64bit. */
  list_node *ranks[MAX_RANKS];
 };

@@ -222,7 +222,8 @@ MatBase<T, Size, Size> pseudo_invert(const MatBase<T, Size, Size> &mat, T epsilo
    using VectorT = Eigen::Matrix<T, Size, 1>;
    /* Blender and Eigen matrices are both column-major by default.
     * Since our matrix is squared, we can use thinU/V. */
-    /** WORKAROUND:
+    /**
+     * WORKAROUND:
     * (ComputeThinU | ComputeThinV) must be set as runtime parameters in Eigen < 3.4.0.
     * But this requires the matrix type to be dynamic to avoid an assert.
     */
@@ -282,9 +283,9 @@ static void polar_decompose(const MatBase<T, 3, 3> &mat3,
    using VectorT = Eigen::Matrix<T, 3, 1>;
    /* Blender and Eigen matrices are both column-major by default.
     * Since our matrix is squared, we can use thinU/V. */
-    /** WORKAROUND:
-     * (ComputeThinU | ComputeThinV) must be set as runtime parameters in Eigen < 3.4.0.
-     * But this requires the matrix type to be dynamic to avoid an assert.
+    /**
+     * WORKAROUND: (ComputeThinU | ComputeThinV) must be set as runtime parameters in
+     * Eigen < 3.4.0. But this requires the matrix type to be dynamic to avoid an assert.
     */
    using MatrixDynamicT = Eigen::Matrix<T, Dynamic, Dynamic>;
    JacobiSVD<MatrixDynamicT, NoQRPreconditioner> svd(
@@ -1583,7 +1583,8 @@ struct CDT_data {
  Vector<bool> is_reversed;
  /** Result of running CDT on input with (vert, edge, face). */
  CDT_result<mpq_class> cdt_out;
-  /** To speed up get_cdt_edge_orig, sometimes populate this map from vertex pair to output edge.
+  /**
+   * To speed up get_cdt_edge_orig, sometimes populate this map from vertex pair to output edge.
   */
  Map<std::pair<int, int>, int> verts_to_edge;
  int proj_axis;
@@ -476,9 +476,7 @@ enum {
  BM_ELEM_SELECT = (1 << 0),
  BM_ELEM_HIDDEN = (1 << 1),
  BM_ELEM_SEAM = (1 << 2),
-  /**
-   * used for faces and edges, note from the user POV,
-   * this is a sharp edge when disabled */
+  /** Used for faces and edges, note from the user POV, this is a sharp edge when disabled. */
  BM_ELEM_SMOOTH = (1 << 3),
  /**
   * Internal flag, used for ensuring correct normals
@@ -652,14 +650,15 @@ typedef bool (*BMLoopPairFilterFunc)(const BMLoop *, const BMLoop *, void *user_
   (((&e->v1_disk_link)[v == e->v2]).prev))

 /**
- * size to use for stack arrays when dealing with NGons,
- * alloc after this limit is reached.
- * this value is rather arbitrary */
+ * Size to use for stack arrays when dealing with NGons, allocate after this limit is reached.
+ * this value is rather arbitrary.
+ */
 #define BM_DEFAULT_NGON_STACK_SIZE 32
 /**
- * size to use for stack arrays dealing with connected mesh data
+ * Size to use for stack arrays dealing with connected mesh data
 * verts of faces, edges of vert - etc.
- * often used with #BM_iter_as_arrayN() */
+ * often used with #BM_iter_as_arrayN().
+ */
 #define BM_DEFAULT_ITER_STACK_SIZE 16

 /* avoid inf loop, this value is arbitrary
@@ -197,7 +197,8 @@ const float *BM_log_original_vert_co(BMLog *log, BMVert *v);
 */
 const float *BM_log_original_vert_no(BMLog *log, BMVert *v);

-/** Get the logged mask of a vertex
+/**
+ * Get the logged mask of a vertex
 *
 * Does not modify the log or the vertex.
 */
@@ -30,9 +30,8 @@ static void bm_rotate_edges_simple(BMesh *bm,
  BMEdge *e;

  BMO_ITER (e, &siter, op->slots_in, "edges", BM_EDGE) {
-    /**
-     * this ends up being called twice, could add option to not to call check in
-     * #BM_edge_rotate to get some extra speed */
+    /* This ends up being called twice, could add option to not to call check in
+     * #BM_edge_rotate to get some extra speed. */
    if (BM_edge_rotate_check(e)) {
      BMEdge *e_rotate = BM_edge_rotate(bm, e, use_ccw, check_flag);
      if (e_rotate != NULL) {
@@ -29,7 +29,8 @@ void BM_mesh_decimate_collapse(BMesh *bm,
                               float symmetry_eps);

 /**
- * \param tag_only: so we can call this from an operator */
+ * \param tag_only: so we can call this from an operator.
+ */
 void BM_mesh_decimate_unsubdivide_ex(BMesh *bm, int iterations, bool tag_only);
 void BM_mesh_decimate_unsubdivide(BMesh *bm, int iterations);

@@ -72,7 +72,8 @@ class NodeOperationInput {
 private:
  NodeOperation *operation_;

-  /** Datatype of this socket. Is used for automatically data transformation.
+  /**
+   * Datatype of this socket. Is used for automatically data transformation.
   * \section data-conversion
   */
  DataType datatype_;
@@ -135,7 +136,8 @@ class NodeOperationOutput {
 private:
  NodeOperation *operation_;

-  /** Datatype of this socket. Is used for automatically data transformation.
+  /**
+   * Datatype of this socket. Is used for automatically data transformation.
   * \section data-conversion
   */
  DataType datatype_;
@@ -63,9 +63,9 @@ class NodeOperationBuilder {

  Node *current_node_;

-  /** Operation that will be writing to the viewer image
-   *  Only one operation can occupy this place at a time,
-   *  to avoid race conditions
+  /**
+   * Operation that will be writing to the viewer image
+   * Only one operation can occupy this place at a time, to avoid race conditions.
   */
  ViewerOperation *active_viewer_;

@@ -24,7 +24,8 @@ class ChannelMatteOperation : public MultiThreadedOperation {

  float limit_range_;

-  /** ids to use for the operations (max and simple)
+  /**
+   * ids to use for the operations (max and simple)
   * alpha = in[ids[0]] - MAX2(in[ids[1]], in[ids[2]])
   * the simple operation is using:
   * alpha = in[ids[0]] - in[ids[1]]
@@ -53,7 +53,8 @@ class FastGaussianBlurValueOperation : public MultiThreadedOperation {
  /**
   * -1: re-mix with darker
   *  0: do nothing
-   *  1 re-mix with lighter */
+   *  1 re-mix with lighter.
+   */
  int overlay_;

 public:
@@ -124,7 +124,8 @@ void EEVEE_screen_raytrace_cache_init(EEVEE_ViewLayerData *sldata, EEVEE_Data *v
    int hitbuf_size[3];
    GPU_texture_get_mipmap_size(effects->ssr_hit_output, 0, hitbuf_size);

-    /** Screen space ray-tracing overview
+    /**
+     * Screen space ray-tracing overview.
     *
     * Following Frostbite stochastic SSR.
     *
@@ -151,9 +151,8 @@ void EEVEE_subsurface_cache_init(EEVEE_ViewLayerData *sldata, EEVEE_Data *vedata
  effects->sss_surface_count = 0;
  common_data->sss_jitter_threshold = scene_eval->eevee.sss_jitter_threshold;

-  /** Screen Space SubSurface Scattering overview
-   * TODO
-   */
+  /* Screen Space SubSurface Scattering overview.
+   * TODO */
  DRWState state = DRW_STATE_WRITE_COLOR | DRW_STATE_STENCIL_EQUAL;
  DRW_PASS_CREATE(psl->sss_blur_ps, state);
  DRW_PASS_CREATE(psl->sss_resolve_ps, state | DRW_STATE_BLEND_ADD);
@@ -217,7 +217,8 @@ struct FilmData {
  int2 offset;
  /** Extent used by the render buffers when rendering the main views. */
  int2 render_extent;
-  /** Sub-pixel offset applied to the window matrix.
+  /**
+   * Sub-pixel offset applied to the window matrix.
   * NOTE: In final film pixel unit.
   * NOTE: Positive values makes the view translate in the negative axes direction.
   * NOTE: The origin is the center of the lower left film pixel of the area covered by a render
@@ -293,8 +293,7 @@ void draw_subdiv_build_edituv_stretch_angle_buffer(const DRWSubdivCache *cache,
                                                   int uvs_offset,
                                                   struct GPUVertBuf *stretch_angles);

-/** Return the format used for the positions and normals VBO.
- */
+/** Return the format used for the positions and normals VBO. */
 struct GPUVertFormat *draw_subdiv_get_pos_nor_format(void);

 #ifdef __cplusplus
@@ -86,8 +86,9 @@ typedef struct PoseBlendData {
  char headerstr[UI_MAX_DRAW_STR];
 } PoseBlendData;

-/** Return the bAction that should be blended.
- * This is either pbd->act or pbd->act_flipped, depending on is_flipped.
+/**
+ * Return the bAction that should be blended.
+ * This is either `pbd->act` or `pbd->act_flipped`, depending on `is_flipped`.
 */
 static bAction *poselib_action_to_blend(PoseBlendData *pbd)
 {
@@ -81,7 +81,8 @@ typedef struct FileIndexerType {
   * Is called at the end of the file listing process. An indexer can free the data that it created
   * during the file listing process.
   *
-   * This is an optional callback */
+   * This is an optional callback.
+   */
  FileIndexerFreeUserDataFunc free_user_data;

  /**
@@ -588,8 +588,7 @@ void ANIM_copy_as_driver(struct ID *target_id, const char *target_path, const ch

 /* Auto-Keying macros for use by various tools. */

-/** Check if auto-key-framing is enabled (per scene takes precedence).
- */
+/** Check if auto-key-framing is enabled (per scene takes precedence). */
 #define IS_AUTOKEY_ON(scene) \
  ((scene) ? ((scene)->toolsettings->autokey_mode & AUTOKEY_ON) : (U.autokey_mode & AUTOKEY_ON))
 /** Check the mode for auto-keyframing (per scene takes precedence). */
@@ -607,7 +607,8 @@ bool ED_operator_camera_poll(struct bContext *C);
 bUserMenu **ED_screen_user_menus_find(const struct bContext *C, uint *r_len);
 struct bUserMenu *ED_screen_user_menu_ensure(struct bContext *C);

-/** Finds a menu item associated with an operator in user menus (aka Quick Favorites)
+/**
+ * Finds a menu item associated with an operator in user menus (aka Quick Favorites)
 *
 * \param op_prop_enum: name of an operator property when the operator is called with an enum (to
 * be an empty string otherwise)
@@ -45,7 +45,8 @@ class AbstractViewItem;
 class AbstractViewItemDropTarget;
 class AbstractViewItemDragController;

-/** The view drop target can share logic with the view item drop target for now, so just an alias.
+/**
+ * The view drop target can share logic with the view item drop target for now, so just an alias.
 */
 using AbstractViewDropTarget = AbstractViewItemDropTarget;

@@ -530,9 +530,10 @@ typedef struct View2DEdgePanData {
  float max_speed;
  /** Delay in seconds before maximum speed is reached. */
  float delay;
-  /** Influence factor for view zoom:
-   *    0 = Constant speed in UI units
-   *    1 = Constant speed in view space, UI speed slows down when zooming out
+  /**
+   * Influence factor for view zoom:
+   * - 0 = Constant speed in UI units.
+   * - 1 = Constant speed in view space, UI speed slows down when zooming out.
   */
  float zoom_influence;

@@ -324,7 +324,8 @@ struct uiButSearch : public uiBut {
  bool results_are_suggestions = false;
 };

-/** Derived struct for #UI_BTYPE_DECORATOR
+/**
+ * Derived struct for #UI_BTYPE_DECORATOR
 * Decorators have own RNA data, using the normal #uiBut RNA members has many side-effects.
 */
 struct uiButDecorator : public uiBut {
@@ -49,7 +49,8 @@ bool EDBM_op_call_silentf(struct BMEditMesh *em, const char *fmt, ...);
 * These next two functions are the split version of EDBM_op_callf, so you can
 * do stuff with a bmesh operator, after initializing it but before executing it.
 *
- * execute the operator with BM_Exec_Op */
+ * execute the operator with #BMO_op_exec.
+ */
 bool EDBM_op_init(
    struct BMEditMesh *em, struct BMOperator *bmop, struct wmOperator *op, const char *fmt, ...);

@@ -756,17 +756,19 @@ static void multipaint_apply_change(MDeformVert *dvert,
 * Variables stored both for 'active' and 'mirror' sides.
 */
 struct WeightPaintGroupData {
-  /** index of active group or its mirror
+  /**
+   * Index of active group or its mirror:
   *
   * - 'active' is always `ob->actdef`.
   * - 'mirror' is -1 when 'ME_EDIT_MIRROR_X' flag id disabled,
   *   otherwise this will be set to the mirror or the active group (if the group isn't mirrored).
   */
  int index;
-  /** lock that includes the 'index' as locked too
+  /**
+   * Lock that includes the 'index' as locked too:
   *
-   * - 'active' is set of locked or active/selected groups
-   * - 'mirror' is set of locked or mirror groups
+   * - 'active' is set of locked or active/selected groups.
+   * - 'mirror' is set of locked or mirror groups.
   */
  const bool *lock;
 };
@@ -1384,8 +1384,9 @@ struct AutomaskingNodeData {
  bool have_orig_data;
 };

-/** Call before PBVH vertex iteration.
- * \param automask_data: pointer to an uninitialized AutomaskingNodeData struct.
+/**
+ * Call before PBVH vertex iteration.
+ * \param automask_data: pointer to an uninitialized #AutomaskingNodeData struct.
 */
 void SCULPT_automasking_node_begin(Object *ob,
                                   const SculptSession *ss,
@@ -131,8 +131,9 @@ static void fileselect_ensure_updated_asset_params(SpaceFile *sfile)
 }

 /**
- * \note RNA_struct_property_is_set_ex is used here because we want
- *       the previously used settings to be used here rather than overriding them */
+ * \note #RNA_struct_property_is_set_ex is used here because we want
+ * the previously used settings to be used here rather than overriding them.
+ */
 static FileSelectParams *fileselect_ensure_updated_file_params(SpaceFile *sfile)
 {
  BLI_assert(sfile->browse_mode == FILE_BROWSE_MODE_FILES);
@@ -580,7 +580,8 @@ struct UndoImageHandle {
  /** Each undo handle refers to a single image which may have multiple buffers. */
  UndoRefID_Image image_ref;

-  /** Each tile of a tiled image has its own UndoImageHandle.
+  /**
+   * Each tile of a tiled image has its own UndoImageHandle.
   * The tile number of this IUser is used to distinguish them.
   */
  ImageUser iuser;
@@ -77,8 +77,9 @@ static bool nlastrip_is_overlap(const NlaStrip *strip_a,
                    strip_b->end + offset_b);
 }

-/** Assumes strips to horizontally translate (shuffle) are tagged with
- * NLASTRIP_FLAG_INVALID_LOCATION.
+/**
+ * Assumes strips to horizontally translate (shuffle) are tagged with
+ * #NLASTRIP_FLAG_INVALID_LOCATION.
 *
 * \returns The total sided offset that results in no overlaps between tagged strips and non-tagged
 * strips.
@@ -122,8 +123,9 @@ static float transdata_get_time_shuffle_offset_side(ListBase *trans_datas, const
  return total_offset;
 }

-/** Assumes strips to horizontally translate (shuffle) are tagged with
- * NLASTRIP_FLAG_INVALID_LOCATION.
+/**
+ * Assumes strips to horizontally translate (shuffle) are tagged with
+ * #NLASTRIP_FLAG_INVALID_LOCATION.
 *
 * \returns The minimal total signed offset that results in no overlaps between tagged strips and
 * non-tagged strips.
@@ -5420,7 +5420,8 @@ finally:
 /** \name Select Mode UV Vert/Edge/Face/Island Operator
 * \{ */

-/** Deselects UVs that are not part of a complete island selection.
+/**
+ * Deselects UVs that are not part of a complete island selection.
 *
 * Use only when sync select disabled.
 */
@@ -3340,7 +3340,8 @@ struct UV_FaceBranch {
  float branch;
 };

-/** Compute the sphere projection for a BMFace using #map_to_sphere and store on BMLoops.
+/**
+ * Compute the sphere projection for a BMFace using #map_to_sphere and store on BMLoops.
 *
 * Heuristics are used in #uv_map_mirror to improve winding.
 *
@@ -14,11 +14,11 @@ namespace Freestyle {

 namespace CurveInternal {

-/** iterator on a curve. Allows an iterating outside
- *  initial vertices. A CurvePoint is instantiated an returned
- *  when the iterator is dereferenced.
+/**
+ * Iterator on a curve. Allows an iterating outside
+ * initial vertices. A CurvePoint is instantiated an returned
+ * when the iterator is dereferenced.
 */
-
 class CurvePointIterator : public Interface0DIteratorNested {
 public:
  friend class Freestyle::Curve;
@@ -73,7 +73,8 @@ class SphericalGrid {
  };

 public:
-  /** Iterator needs to allow the user to avoid full 3D comparison in two cases:
+  /**
+   * Iterator needs to allow the user to avoid full 3D comparison in two cases:
   *
   *  (1) Where (*current)->deepest < target[2], where the occluder is unambiguously in front of
   * the target point.
@@ -1547,7 +1547,8 @@ static float pack_islands_scale_margin(const Span<PackIsland *> islands,
  return get_aspect_scaled_extent(final_extent, params);
 }

-/** Find the optimal scale to pack islands into the unit square.
+/**
+ * Find the optimal scale to pack islands into the unit square.
 * returns largest scale that will pack `islands` into the unit square.
 */
 static float pack_islands_margin_fraction(const Span<PackIsland *> &islands,
@@ -169,7 +169,8 @@ typedef struct LineartEdge {
  uint16_t flags;
  uint8_t intersection_mask;

-  /** Matches the shadow result, used to determine whether a line is in the shadow or not.
+  /**
+   * Matches the shadow result, used to determine whether a line is in the shadow or not.
   * #edge_identifier usages:
   * - Intersection lines:
   *    ((e->t1->target_reference << 32) | e->t2->target_reference);
@@ -178,8 +179,10 @@ typedef struct LineartEdge {
   */
  uint64_t edge_identifier;

-  /** - Light contour: original_e->t1->target_reference | original_e->t2->target_reference.
-   *  - Cast shadow: triangle_projected_onto->target_reference. */
+  /**
+   * - Light contour: original_e->t1->target_reference | original_e->t2->target_reference.
+   * - Cast shadow: triangle_projected_onto->target_reference.
+   */
  uint64_t target_reference;

  /**
@@ -1744,7 +1744,7 @@ void MSLGeneratorInterface::prepare_from_createinfo(const shader::ShaderCreateIn
    uniforms.append(uniform);
  }

-  /** Prepare textures and uniform blocks.
+  /* Prepare textures and uniform blocks.
   * Perform across both resource categories and extract both
   * texture samplers and image types. */

@@ -37,7 +37,8 @@ class GLStateManager : public StateManager {
  /** Limits. */
  float line_width_range_[2];

-  /** Texture state:
+  /**
+   * Texture state:
   * We keep the full stack of textures and sampler bounds to use multi bind, and to be able to
   * edit and restore texture binds on the fly without querying the context.
   * Also this allows us to keep track of textures bounds to many texture units.
@@ -602,7 +602,7 @@ void GLTexture::samplers_init()
        glSamplerParameteri(sampler, GL_TEXTURE_MIN_FILTER, min_filter);
        glSamplerParameteri(sampler, GL_TEXTURE_MAG_FILTER, mag_filter);

-        /** Other states are left to default:
+        /* Other states are left to default:
         * - GL_TEXTURE_BORDER_COLOR is {0, 0, 0, 0}.
         * - GL_TEXTURE_MIN_LOD is -1000.
         * - GL_TEXTURE_MAX_LOD is 1000.
@@ -223,13 +223,15 @@ typedef struct ImBuf {

  /* pixels */

-  /** Image pixel buffer (8bit representation):
+  /**
+   * Image pixel buffer (8bit representation):
   * - color space defaults to `sRGB`.
   * - alpha defaults to 'straight'.
   */
  ImBufByteBuffer byte_buffer;

-  /** Image pixel buffer (float representation):
+  /**
+   * Image pixel buffer (float representation):
   * - color space defaults to 'linear' (`rec709`).
   * - alpha defaults to 'premul'.
   * \note May need gamma correction to `sRGB` when generating 8bit representations.
@@ -26,12 +26,15 @@ class PlyReadBuffer {
  /** After header is parsed, indicate whether the rest of reading will be ascii or binary. */
  void after_header(bool is_binary);

-  /** Gets the next line from the file as a Span. The line does not include any newline characters.
+  /**
+   * Gets the next line from the file as a Span. The line does not include any newline characters.
   */
  Span<char> read_line();

-  /** Reads a number of bytes into provided destination pointer. Returns false if this amount of
-   * bytes can not be read. */
+  /**
+   * Reads a number of bytes into provided destination pointer. Returns false if this amount of
+   * bytes can not be read.
+   */
  bool read_bytes(void *dst, size_t size);

 private:
@@ -352,7 +352,8 @@ typedef struct IDOverrideLibrary {
  /** List of IDOverrideLibraryProperty structs. */
  ListBase properties;

-  /** Override hierarchy root ID. Usually the actual root of the hierarchy, but not always
+  /**
+   * Override hierarchy root ID. Usually the actual root of the hierarchy, but not always
   * in degenerated cases.
   *
   * All liboverrides of a same hierarchy (e.g. a character collection) share the same root.
@@ -93,7 +93,8 @@ typedef struct CacheFile {
  /* eCacheFileType enum. */
  char type;

-  /** Do not load data from the cache file and display objects in the scene as boxes, Cycles will
+  /**
+   * Do not load data from the cache file and display objects in the scene as boxes, Cycles will
   * load objects directly from the CacheFile. Other render engines which can load Alembic data
   * directly can take care of rendering it themselves.
   */
@@ -720,7 +720,8 @@ typedef struct bGPdata {
   * active frame and the one before it (0 = only the ghost itself).
   */
  short gstep;
-  /** Ghosts After: max number of ghost frames to show after
+  /**
+   * Ghosts After: max number of ghost frames to show after
   * active frame and the following it (0 = only the ghost itself).
   */
  short gstep_next;
@@ -1245,8 +1245,9 @@ typedef struct ShrinkwrapGpencilModifierData {
  /** Axis to project over. */
  char proj_axis;

-  /** If using projection over vertex normal this controls the level of subsurface that must be
-   * done before getting the vertex coordinates and normal
+  /**
+   * If using projection over vertex normal this controls the level of subsurface that must be
+   * done before getting the vertex coordinates and normal.
   */
  char subsurf_levels;
  char _pad[6];
@@ -213,12 +213,14 @@ typedef struct MVertSkin {
 } MVertSkin;

 typedef enum eMVertSkinFlag {
-  /** Marks a vertex as the edge-graph root, used for calculating rotations for all connected
+  /**
+   * Marks a vertex as the edge-graph root, used for calculating rotations for all connected
   * edges (recursively). Also used to choose a root when generating an armature.
   */
  MVERT_SKIN_ROOT = 1,

-  /** Marks a branch vertex (vertex with more than two connected edges), so that its neighbors
+  /**
+   * Marks a branch vertex (vertex with more than two connected edges), so that its neighbors
   * are directly hulled together, rather than the default of generating intermediate frames.
   */
  MVERT_SKIN_LOOSE = 2,
@@ -1171,8 +1171,9 @@ typedef struct ShrinkwrapModifierData {
  /** Axis to project over. */
  char projAxis;

-  /** If using projection over vertex normal this controls the level of subsurface that must be
-   * done before getting the vertex coordinates and normal
+  /**
+   * If using projection over vertex normal this controls the level of subsurface that must be
+   * done before getting the vertex coordinates and normal.
   */
  char subsurfLevels;

@@ -205,10 +205,9 @@ typedef struct SoftBody {
  /** Softbody mass of *vertex*. */
  float nodemass;
  /**
-   * Along with it introduce mass painting
-   * starting to fix old bug .. nastiness that VG are indexes
-   * rather find them by name tag to find it -> jow20090613.
-   * MAX_VGROUP_NAME */
+   * Along with it introduce mass painting starting to fix old bug .. nastiness that VG are indexes
+   * rather find them by name tag to find it -> jow20090613. #MAX_VGROUP_NAME size.
+   */
  char namedVG_Mass[64];
  /** Softbody amount of gravitation to apply. */
  float grav;
@@ -233,8 +232,8 @@ typedef struct SoftBody {
  short vertgroup;
  /**
   * Starting to fix old bug .. nastiness that VG are indexes
-   * rather find them by name tag to find it -> jow20090613.
-   * MAX_VGROUP_NAME */
+   * rather find them by name tag to find it -> jow20090613. #MAX_VGROUP_NAME size.
+   */
  char namedVG_Softgoal[64];

  short fuzzyness;
@@ -344,7 +344,8 @@ typedef enum PropertyOverrideFlag {
  /** The property supports insertion (collections only). */
  PROPOVERRIDE_LIBRARY_INSERTION = (1 << 10),

-  /** Only use indices to compare items in the property, never names (collections only).
+  /**
+   * Only use indices to compare items in the property, never names (collections only).
   *
   * Useful when nameprop of the items is generated from other data
   * (e.g. name of material slots is actually name of assigned material).
@@ -528,7 +528,8 @@ static int rna_validate_identifier(const char *identifier, char *error, bool pro
 {
  int a = 0;

-  /** List is from:
+  /**
+   * List is from:
   * \code{.py}
   * ", ".join([
   *     '"%s"' % kw for kw in __import__("keyword").kwlist
@@ -536,7 +536,7 @@ static void rna_FKeyframe_ctrlpoint_ui_set(PointerRNA *ptr, const float *values)
  const float frame_delta = values[0] - bezt->vec[1][0];
  const float value_delta = values[1] - bezt->vec[1][1];

-  /** To match the behavior of transforming the keyframe Co using the Graph Editor
+  /* To match the behavior of transforming the keyframe Co using the Graph Editor
   * (transform_convert_graph.c) flushTransGraphData(), we will also move the handles by
   * the same amount as the Co delta. */

@@ -156,20 +156,23 @@ typedef void (*PropEnumSetFuncEx)(struct PointerRNA *ptr, struct PropertyRNA *pr
 typedef struct PropertyRNAOrID {
  PointerRNA ptr;

-  /** The PropertyRNA passed as parameter, used to generate that structure's content:
+  /**
+   * The PropertyRNA passed as parameter, used to generate that structure's content:
   * - Static RNA: The RNA property (same as `rnaprop`), never NULL.
   * - Runtime RNA: The RNA property (same as `rnaprop`), never NULL.
   * - IDProperty: The IDProperty, never NULL.
   */
  PropertyRNA *rawprop;
-  /** The real RNA property of this property, never NULL:
+  /**
+   * The real RNA property of this property, never NULL:
   * - Static RNA: The rna property, also gives direct access to the data (from any matching
   *               PointerRNA).
   * - Runtime RNA: The rna property, does not directly gives access to the data.
   * - IDProperty: The generic PropertyRNA matching its type.
   */
  PropertyRNA *rnaprop;
-  /** The IDProperty storing the data of this property, may be NULL:
+  /**
+   * The IDProperty storing the data of this property, may be NULL:
   * - Static RNA: Always NULL.
   * - Runtime RNA: The IDProperty storing the data of that property, may be NULL if never set yet.
   * - IDProperty: The IDProperty, never NULL.
@@ -180,7 +183,8 @@ typedef struct PropertyRNAOrID {

  /** Whether this property is a 'pure' IDProperty or not. */
  bool is_idprop;
-  /** For runtime RNA properties, whether it is set, defined, or not.
+  /**
+   * For runtime RNA properties, whether it is set, defined, or not.
   * WARNING: This DOES take into account the `IDP_FLAG_GHOST` flag, i.e. it matches result of
   *          `RNA_property_is_set`. */
  bool is_set;
@@ -24,7 +24,7 @@ NODE_STORAGE_FUNCS(NodeShaderMix)
 static void sh_node_mix_declare(NodeDeclarationBuilder &b)
 {
  b.is_function_node();
-  /** WARNING:
+  /* WARNING:
   * Input socket indices must be kept in sync with ntree_shader_disconnect_inactive_mix_branches
   */
  b.add_input<decl::Float>("Factor", "Factor_Float")
@@ -13,7 +13,8 @@ namespace Eigen {

 namespace internal {

-/** \internal Low-level conjugate gradient algorithm
+/**
+ * \internal Low-level conjugate gradient algorithm
 * \param mat: The matrix A
 * \param rhs: The right hand side vector b
 * \param x: On input and initial solution, on output the computed solution.
@@ -219,7 +220,8 @@ class ConstrainedConjugateGradient
  /** Default constructor. */
  ConstrainedConjugateGradient() : Base() {}

-  /** Initialize the solver with matrix \a A for further \c Ax=b solving.
+  /**
+   * Initialize the solver with matrix \a A for further \c Ax=b solving.
   *
   * This constructor is a shortcut for the default constructor followed
   * by a call to compute().
@@ -242,7 +244,8 @@ class ConstrainedConjugateGradient
    return m_filter;
  }

-  /** \returns the solution x of \f$ A x = b \f$ using the current decomposition of A
+  /**
+   * \returns the solution x of \f$ A x = b \f$ using the current decomposition of A
   * \a x0 as an initial solution.
   *
   * \sa compute()
@@ -387,9 +387,6 @@ void WM_cursor_grab_enable(struct wmWindow *win,
                           eWM_CursorWrapAxis wrap,
                           const struct rcti *wrap_region,
                           bool hide);
-/**
- *
- */
 void WM_cursor_grab_disable(struct wmWindow *win, const int mouse_ungrab_xy[2]);
 /**
 * After this you can call restore too.
@@ -1148,26 +1148,35 @@ typedef char *(*WMDropboxTooltipFunc)(struct bContext *,
                                      struct wmDropBox *drop);

 typedef struct wmDragActiveDropState {
-  /** Informs which dropbox is activated with the drag item.
+  /**
+   * Informs which dropbox is activated with the drag item.
   * When this value changes, the #draw_activate and #draw_deactivate dropbox callbacks are
   * triggered.
   */
  struct wmDropBox *active_dropbox;

-  /** If `active_dropbox` is set, the area it successfully polled in. To restore the context of it
-   * as needed. */
+  /**
+   * If `active_dropbox` is set, the area it successfully polled in.
+   * To restore the context of it as needed.
+   */
  struct ScrArea *area_from;
-  /** If `active_dropbox` is set, the region it successfully polled in. To restore the context of
-   * it as needed. */
+  /**
+   * If `active_dropbox` is set, the region it successfully polled in.
+   * To restore the context of it as needed.
+   */
  struct ARegion *region_from;

-  /** If `active_dropbox` is set, additional context provided by the active (i.e. hovered) button.
-   * Activated before context sensitive operations (polling, drawing, dropping). */
+  /**
+   * If `active_dropbox` is set, additional context provided by the active (i.e. hovered) button.
+   * Activated before context sensitive operations (polling, drawing, dropping).
+   */
  struct bContextStore *ui_context;

-  /** Text to show when a dropbox poll succeeds (so the dropbox itself is available) but the
+  /**
+   * Text to show when a dropbox poll succeeds (so the dropbox itself is available) but the
   * operator poll fails. Typically the message the operator set with
-   * CTX_wm_operator_poll_msg_set(). */
+   * #CTX_wm_operator_poll_msg_set().
+   */
  const char *disabled_info;
  bool free_disabled_info;
 } wmDragActiveDropState;
@@ -657,7 +657,7 @@ static void wm_keymap_patch(wmKeyMap *km, wmKeyMap *diff_km)
      /* We seek only for exact copy here! See #42137. */
      wmKeyMapItem *kmi_add = wm_keymap_find_item_equals(km, kmdi->add_item);

-      /** If kmi_add is same as kmi_remove (can happen in some cases,
+      /* If kmi_add is same as kmi_remove (can happen in some cases,
       * typically when we got kmi_remove from #wm_keymap_find_item_equals_result()),
       * no need to add or remove anything, see #45579. */

@@ -1561,7 +1561,8 @@ int WM_operator_ui_popup(bContext *C, wmOperator *op, int width)
 /**
 * For use by #WM_operator_props_popup_call, #WM_operator_props_popup only.
 *
- * \note operator menu needs undo flag enabled, for redo callback */
+ * \note operator menu needs undo flag enabled, for redo callback.
+ */
 static int wm_operator_props_popup_ex(bContext *C,
                                      wmOperator *op,
                                      const bool do_call,