Cleanup: spelling in comments & some minor clarifications

31 files changed, 120 insertions, 115 deletions

diff --git a/intern/cycles/scene/mesh.cpp b/intern/cycles/scene/mesh.cpp
index ebf1c3999b6..a459195efee 100644
--- a/intern/cycles/scene/mesh.cpp
+++ b/intern/cycles/scene/mesh.cpp
@@ -68,7 +68,7 @@ void Mesh::Triangle::verts_for_step(const float3 *verts,
     r_verts[2] = verts[v[2]];
   }
   else {
-    /* Center step not stored in the attribute array array. */
+    /* Center step not stored in the attribute array. */
     if (step > center_step) {
       step--;
     }
diff --git a/source/blender/blenkernel/BKE_geometry_set.hh b/source/blender/blenkernel/BKE_geometry_set.hh
index 169554b4453..0e121068cbc 100644
--- a/source/blender/blenkernel/BKE_geometry_set.hh
+++ b/source/blender/blenkernel/BKE_geometry_set.hh
@@ -678,7 +678,7 @@ class CurveComponentLegacy : public GeometryComponent {
 };
 
 /**
- * A geometry component that stores a group of curves, corresponding the the #Curves and
+ * A geometry component that stores a group of curves, corresponding the #Curves and
  * #CurvesGeometry types.
  */
 class CurveComponent : public GeometryComponent {
diff --git a/source/blender/blenkernel/BKE_lib_id.h b/source/blender/blenkernel/BKE_lib_id.h
index c56cb616a9a..040be8d1280 100644
--- a/source/blender/blenkernel/BKE_lib_id.h
+++ b/source/blender/blenkernel/BKE_lib_id.h
@@ -150,11 +150,11 @@ enum {
   LIB_ID_COPY_NO_PREVIEW = 1 << 17,
   /** Copy runtime data caches. */
   LIB_ID_COPY_CACHES = 1 << 18,
-  /** Don't copy id->adt, used by ID datablock localization routines. */
+  /** Don't copy id->adt, used by ID data-block localization routines. */
   LIB_ID_COPY_NO_ANIMDATA = 1 << 19,
   /** Mesh: Reference CD data layers instead of doing real copy - USE WITH CAUTION! */
   LIB_ID_COPY_CD_REFERENCE = 1 << 20,
-  /** Do not copy id->override_library, used by ID datablock override routines. */
+  /** Do not copy id->override_library, used by ID data-block override routines. */
   LIB_ID_COPY_NO_LIB_OVERRIDE = 1 << 21,
   /** When copying local sub-data (like constraints or modifiers), do not set their "library
    * override local data" flag. */
@@ -162,11 +162,11 @@ enum {
 
   /* *** XXX Hackish/not-so-nice specific behaviors needed for some corner cases. *** */
   /* *** Ideally we should not have those, but we need them for now... *** */
-  /** EXCEPTION! Deep-copy actions used by animdata of copied ID. */
+  /** EXCEPTION! Deep-copy actions used by animation-data of copied ID. */
   LIB_ID_COPY_ACTIONS = 1 << 24,
-  /** Keep the library pointer when copying datablock outside of bmain. */
+  /** Keep the library pointer when copying data-block outside of bmain. */
   LIB_ID_COPY_KEEP_LIB = 1 << 25,
-  /** EXCEPTION! Deep-copy shapekeys used by copied obdata ID. */
+  /** EXCEPTION! Deep-copy shape-keys used by copied obdata ID. */
   LIB_ID_COPY_SHAPEKEY = 1 << 26,
   /** EXCEPTION! Specific deep-copy of node trees used e.g. for rendering purposes. */
   LIB_ID_COPY_NODETREE_LOCALIZE = 1 << 27,
@@ -177,7 +177,7 @@ enum {
   LIB_ID_COPY_RIGID_BODY_NO_COLLECTION_HANDLING = 1 << 28,
 
   /* *** Helper 'defines' gathering most common flag sets. *** */
-  /** Shapekeys are not real ID's, more like local data to geometry IDs... */
+  /** Shape-keys are not real ID's, more like local data to geometry IDs. */
   LIB_ID_COPY_DEFAULT = LIB_ID_COPY_SHAPEKEY,
 
   /** Create a local, outside of bmain, data-block to work on. */
@@ -412,7 +412,7 @@ struct ID *BKE_id_copy(struct Main *bmain, const struct ID *id);
  *
  * There are exceptions though:
  * - Embedded IDs (root node trees and master collections) are always copied with their owner.
- * - If #LIB_ID_COPY_ACTIONS is defined, actions used by animdata will be duplicated.
+ * - If #LIB_ID_COPY_ACTIONS is defined, actions used by anim-data will be duplicated.
  * - If #LIB_ID_COPY_SHAPEKEY is defined, shape-keys will be duplicated.
  * - If #LIB_ID_CREATE_LOCAL is defined, root node trees will be deep-duplicated recursively.
  *
diff --git a/source/blender/blenkernel/intern/blendfile_link_append.c b/source/blender/blenkernel/intern/blendfile_link_append.c
index ce36bfe81be..294fe57c923 100644
--- a/source/blender/blenkernel/intern/blendfile_link_append.c
+++ b/source/blender/blenkernel/intern/blendfile_link_append.c
@@ -926,7 +926,7 @@ static int foreach_libblock_link_append_callback(LibraryIDLinkCallbackData *cb_d
      * unfortunately they can use fully linkable valid IDs too, like actions. Those need to be
      * processed, so we need to recursively deal with them here. */
     /* NOTE: Since we are by-passing checks in `BKE_library_foreach_ID_link` by manually calling it
-     * recursively, we need to take care of potential recursion cases ourselves (e.g.animdata of
+     * recursively, we need to take care of potential recursion cases ourselves (e.g.anim-data of
      * shape-key referencing the shape-key itself).
      * NOTE: in case both IDs (owner and 'used' ones) are non-linkable, we can assume we can break
      * the dependency here. Indeed, either they are both linked in another way (through their own
diff --git a/source/blender/blenkernel/intern/data_transfer.c b/source/blender/blenkernel/intern/data_transfer.c
index 1818e5a9490..5be993ca1f7 100644
--- a/source/blender/blenkernel/intern/data_transfer.c
+++ b/source/blender/blenkernel/intern/data_transfer.c
@@ -973,8 +973,8 @@ static bool data_transfer_layersmapping_generate(ListBase *r_map,
       return ret;
     }
     if (cddata_type == CD_FAKE_SHAPEKEY) {
-      /* TODO: leaving shapekeys aside for now, quite specific case,
-       * since we can't access them from MVert :/ */
+      /* TODO: leaving shape-keys aside for now, quite specific case,
+       * since we can't access them from #MVert :/ */
       return false;
     }
   }
diff --git a/source/blender/blenkernel/intern/image.cc b/source/blender/blenkernel/intern/image.cc
index 967f0f61e07..ff10f36cc22 100644
--- a/source/blender/blenkernel/intern/image.cc
+++ b/source/blender/blenkernel/intern/image.cc
@@ -198,7 +198,7 @@ static void image_free_data(ID *id)
 {
   Image *image = (Image *)id;
 
-  /* Also frees animdata. */
+  /* Also frees animations (#Image.anims list). */
   BKE_image_free_buffers(image);
 
   image_free_packedfiles(image);
diff --git a/source/blender/blenkernel/intern/key.c b/source/blender/blenkernel/intern/key.c
index e28094c0abc..bd6ffa2bc55 100644
--- a/source/blender/blenkernel/intern/key.c
+++ b/source/blender/blenkernel/intern/key.c
@@ -206,7 +206,7 @@ IDTypeInfo IDType_ID_KE = {
     .foreach_id = shapekey_foreach_id,
     .foreach_cache = NULL,
     .foreach_path = NULL,
-    /* A bit weird, due to shapekeys not being strictly speaking embedded data... But they also
+    /* A bit weird, due to shape-keys not being strictly speaking embedded data... But they also
      * share a lot with those (non linkable, only ever used by one owner ID, etc.). */
     .owner_get = shapekey_owner_get,
 
diff --git a/source/blender/blenkernel/intern/lib_id.c b/source/blender/blenkernel/intern/lib_id.c
index 7cd3204f3f1..28745f1d2c7 100644
--- a/source/blender/blenkernel/intern/lib_id.c
+++ b/source/blender/blenkernel/intern/lib_id.c
@@ -1875,7 +1875,7 @@ void BKE_library_make_local(Main *bmain,
   for (int a = set_listbasepointers(bmain, lbarray); a--;) {
     ID *id = lbarray[a]->first;
 
-    /* Do not explicitly make local non-linkable IDs (shapekeys, in fact),
+    /* Do not explicitly make local non-linkable IDs (shape-keys, in fact),
      * they are assumed to be handled by real data-blocks responsible of them. */
     const bool do_skip = (id && !BKE_idtype_idcode_is_linkable(GS(id->name)));
 
@@ -1902,8 +1902,8 @@ void BKE_library_make_local(Main *bmain,
        * to discover all your links are lost after appending).
        * Also, never ever make proxified objects local, would not make any sense. */
       /* Some more notes:
-       *   - Shapekeys are never tagged here (since they are not linkable).
-       *   - Nodetrees used in materials etc. have to be tagged manually,
+       *   - Shape-keys are never tagged here (since they are not linkable).
+       *   - Node-trees used in materials etc. have to be tagged manually,
        *     since they do not exist in Main (!).
        * This is ok-ish on 'make local' side of things
        * (since those are handled by their 'owner' IDs),
diff --git a/source/blender/blenkernel/intern/lib_override.c b/source/blender/blenkernel/intern/lib_override.c
index 9b7f9d4f36d..7f34ccfc36f 100644
--- a/source/blender/blenkernel/intern/lib_override.c
+++ b/source/blender/blenkernel/intern/lib_override.c
@@ -3420,7 +3420,7 @@ ID *BKE_lib_override_library_operations_store_start(Main *bmain,
 {
   if (ID_IS_OVERRIDE_LIBRARY_TEMPLATE(local) || ID_IS_OVERRIDE_LIBRARY_VIRTUAL(local)) {
     /* This is actually purely local data with an override template, or one of those embedded IDs
-     * (root node trees, master collections or shapekeys) that cannot have their own override.
+     * (root node trees, master collections or shape-keys) that cannot have their own override.
      * Nothing to do here! */
     return NULL;
   }
diff --git a/source/blender/blenkernel/intern/screen.c b/source/blender/blenkernel/intern/screen.c
index b1b9a24ebaa..ebc87c6ccc0 100644
--- a/source/blender/blenkernel/intern/screen.c
+++ b/source/blender/blenkernel/intern/screen.c
@@ -58,7 +58,7 @@ static void screen_free_data(ID *id)
 {
   bScreen *screen = (bScreen *)id;
 
-  /* No animdata here. */
+  /* No animation-data here. */
 
   LISTBASE_FOREACH (ARegion *, region, &screen->regionbase) {
     BKE_area_region_free(NULL, region);
diff --git a/source/blender/blenkernel/intern/sound.c b/source/blender/blenkernel/intern/sound.c
index 8b72fd05057..b991805fae8 100644
--- a/source/blender/blenkernel/intern/sound.c
+++ b/source/blender/blenkernel/intern/sound.c
@@ -87,7 +87,7 @@ static void sound_free_data(ID *id)
 {
   bSound *sound = (bSound *)id;
 
-  /* No animdata here. */
+  /* No animation-data here. */
 
   if (sound->packedfile) {
     BKE_packedfile_free(sound->packedfile);
diff --git a/source/blender/depsgraph/intern/builder/deg_builder_nodes.cc b/source/blender/depsgraph/intern/builder/deg_builder_nodes.cc
index 77597e0db06..49e850b1979 100644
--- a/source/blender/depsgraph/intern/builder/deg_builder_nodes.cc
+++ b/source/blender/depsgraph/intern/builder/deg_builder_nodes.cc
@@ -1408,7 +1408,7 @@ void DepsgraphNodeBuilder::build_particle_settings(ParticleSettings *particle_se
   }
 }
 
-/* Shapekeys */
+/* Shape-keys. */
 void DepsgraphNodeBuilder::build_shapekeys(Key *key)
 {
   if (built_map_.checkIsBuiltAndTag(key)) {
diff --git a/source/blender/depsgraph/intern/depsgraph_tag.cc b/source/blender/depsgraph/intern/depsgraph_tag.cc
index 9551a00cf95..f945e9b6fbc 100644
--- a/source/blender/depsgraph/intern/depsgraph_tag.cc
+++ b/source/blender/depsgraph/intern/depsgraph_tag.cc
@@ -865,7 +865,7 @@ void DEG_ids_clear_recalc(Depsgraph *depsgraph, const bool backup)
   if (!DEG_id_type_any_updated(depsgraph)) {
     return;
   }
-  /* Go over all ID nodes nodes, clearing tags. */
+  /* Go over all ID nodes, clearing tags. */
   for (deg::IDNode *id_node : deg_graph->id_nodes) {
     if (backup) {
       id_node->id_cow_recalc_backup |= id_node->id_cow->recalc;
diff --git a/source/blender/draw/intern/draw_common.c b/source/blender/draw/intern/draw_common.c
index 2897234f4dc..c7edf003346 100644
--- a/source/blender/draw/intern/draw_common.c
+++ b/source/blender/draw/intern/draw_common.c
@@ -135,7 +135,7 @@ void DRW_globals_update(void)
 
   UI_GetThemeColor4fv(TH_CFRAME, gb->colorCurrentFrame);
 
-  /* Metaball */
+  /* Meta-ball. */
   UI_COLOR_RGBA_FROM_U8(0xA0, 0x30, 0x30, 0xFF, gb->colorMballRadius);
   UI_COLOR_RGBA_FROM_U8(0xF0, 0xA0, 0xA0, 0xFF, gb->colorMballRadiusSelect);
   UI_COLOR_RGBA_FROM_U8(0x30, 0xA0, 0x30, 0xFF, gb->colorMballStiffness);
diff --git a/source/blender/editors/animation/anim_channels_defines.c b/source/blender/editors/animation/anim_channels_defines.c
index f4412ea837d..445d3715658 100644
--- a/source/blender/editors/animation/anim_channels_defines.c
+++ b/source/blender/editors/animation/anim_channels_defines.c
@@ -525,7 +525,7 @@ static void *acf_summary_setting_ptr(bAnimListElem *ale,
   return NULL;
 }
 
-/* all animation summary (DopeSheet only) type define */
+/** All animation summary (dope-sheet only) type define. */
 static bAnimChannelType ACF_SUMMARY = {
     "Summary",              /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -634,7 +634,7 @@ static void *acf_scene_setting_ptr(bAnimListElem *ale, eAnimChannel_Settings set
   }
 }
 
-/* scene type define */
+/** Scene type define. */
 static bAnimChannelType ACF_SCENE = {
     "Scene",                /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -810,7 +810,7 @@ static void *acf_object_setting_ptr(bAnimListElem *ale, eAnimChannel_Settings se
   }
 }
 
-/* object type define */
+/** Object type define. */
 static bAnimChannelType ACF_OBJECT = {
     "Object",               /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -987,7 +987,7 @@ static void *acf_group_setting_ptr(bAnimListElem *ale,
   return GET_ACF_FLAG_PTR(agrp->flag, type);
 }
 
-/* group type define */
+/** Group type define. */
 static bAnimChannelType ACF_GROUP = {
     "Group",               /* type name */
     ACHANNEL_ROLE_CHANNEL, /* role */
@@ -1111,7 +1111,7 @@ static void *acf_fcurve_setting_ptr(bAnimListElem *ale,
   return GET_ACF_FLAG_PTR(fcu->flag, type);
 }
 
-/* fcurve type define */
+/** F-Curve type define. */
 static bAnimChannelType ACF_FCURVE = {
     "F-Curve",             /* type name */
     ACHANNEL_ROLE_CHANNEL, /* role */
@@ -1231,7 +1231,7 @@ static int acf_nla_controls_icon(bAnimListElem *UNUSED(ale))
   return ICON_NLA;
 }
 
-/* NLA Control FCurves Expander type define */
+/** NLA Control F-Curves expander type define. */
 static bAnimChannelType ACF_NLACONTROLS = {
     "NLA Controls Expander", /* type name */
     ACHANNEL_ROLE_EXPANDER,  /* role */
@@ -1271,7 +1271,7 @@ static void acf_nla_curve_name(bAnimListElem *ale, char *name)
   }
 }
 
-/* NLA Control F-Curve type define */
+/** NLA Control F-Curve type define. */
 static bAnimChannelType ACF_NLACURVE = {
     "NLA Control F-Curve", /* type name */
     ACHANNEL_ROLE_CHANNEL, /* role */
@@ -1361,7 +1361,7 @@ static void *acf_fillactd_setting_ptr(bAnimListElem *ale,
   }
 }
 
-/* object action expander type define */
+/** Object action expander type define. */
 static bAnimChannelType ACF_FILLACTD = {
     "Ob-Action Filler",     /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -1446,7 +1446,7 @@ static void *acf_filldrivers_setting_ptr(bAnimListElem *ale,
   }
 }
 
-/* drivers expander type define */
+/** Drivers expander type define. */
 static bAnimChannelType ACF_FILLDRIVERS = {
     "Drivers Filler",       /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -1525,7 +1525,7 @@ static void *acf_dsmat_setting_ptr(bAnimListElem *ale, eAnimChannel_Settings set
   }
 }
 
-/* material expander type define */
+/** Material expander type define. */
 static bAnimChannelType ACF_DSMAT = {
     "Material Data Expander", /* type name */
     ACHANNEL_ROLE_EXPANDER,   /* role */
@@ -1606,7 +1606,7 @@ static void *acf_dslight_setting_ptr(bAnimListElem *ale,
   }
 }
 
-/* light expander type define */
+/** Light expander type define. */
 static bAnimChannelType ACF_DSLIGHT = {
     "Light Expander",       /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -1692,7 +1692,7 @@ static void *acf_dstex_setting_ptr(bAnimListElem *ale, eAnimChannel_Settings set
   }
 }
 
-/* texture expander type define */
+/** Texture expander type define. */
 static bAnimChannelType ACF_DSTEX = {
     "Texture Data Expander", /* type name */
     ACHANNEL_ROLE_EXPANDER,  /* role */
@@ -1775,7 +1775,7 @@ static void *acf_dscachefile_setting_ptr(bAnimListElem *ale,
   }
 }
 
-/* CacheFile expander type define. */
+/** CacheFile expander type define.. */
 static bAnimChannelType ACF_DSCACHEFILE = {
     "Cache File Expander",  /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -1858,7 +1858,7 @@ static void *acf_dscam_setting_ptr(bAnimListElem *ale, eAnimChannel_Settings set
   }
 }
 
-/* camera expander type define */
+/** Camera expander type define. */
 static bAnimChannelType ACF_DSCAM = {
     "Camera Expander",      /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -1947,7 +1947,7 @@ static void *acf_dscur_setting_ptr(bAnimListElem *ale, eAnimChannel_Settings set
   }
 }
 
-/* curve expander type define */
+/** Curve expander type define. */
 static bAnimChannelType ACF_DSCUR = {
     "Curve Expander",       /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -2045,7 +2045,7 @@ static void *acf_dsskey_setting_ptr(bAnimListElem *ale, eAnimChannel_Settings se
   }
 }
 
-/* shapekey expander type define */
+/** Shape-key expander type define. */
 static bAnimChannelType ACF_DSSKEY = {
     "Shape Key Expander",   /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -2124,7 +2124,7 @@ static void *acf_dswor_setting_ptr(bAnimListElem *ale, eAnimChannel_Settings set
   }
 }
 
-/* world expander type define */
+/** World expander type define. */
 static bAnimChannelType ACF_DSWOR = {
     "World Expander",       /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -2203,7 +2203,7 @@ static void *acf_dspart_setting_ptr(bAnimListElem *ale, eAnimChannel_Settings se
   }
 }
 
-/* particle expander type define */
+/** Particle expander type define. */
 static bAnimChannelType ACF_DSPART = {
     "Particle Data Expander", /* type name */
     ACHANNEL_ROLE_EXPANDER,   /* role */
@@ -2284,7 +2284,7 @@ static void *acf_dsmball_setting_ptr(bAnimListElem *ale,
   }
 }
 
-/* metaball expander type define */
+/** Meta-ball expander type define. */
 static bAnimChannelType ACF_DSMBALL = {
     "Metaball Expander",    /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -2363,7 +2363,7 @@ static void *acf_dsarm_setting_ptr(bAnimListElem *ale, eAnimChannel_Settings set
   }
 }
 
-/* metaball expander type define */
+/** Armature expander type define. */
 static bAnimChannelType ACF_DSARM = {
     "Armature Expander",    /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -2455,7 +2455,7 @@ static void *acf_dsntree_setting_ptr(bAnimListElem *ale,
   }
 }
 
-/* node tree expander type define */
+/** Node tree expander type define. */
 static bAnimChannelType ACF_DSNTREE = {
     "Node Tree Expander",   /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -2536,7 +2536,7 @@ static void *acf_dslinestyle_setting_ptr(bAnimListElem *ale,
   }
 }
 
-/* node tree expander type define */
+/** Line Style expander type define. */
 static bAnimChannelType ACF_DSLINESTYLE = {
     "Line Style Expander",  /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -2615,7 +2615,7 @@ static void *acf_dsmesh_setting_ptr(bAnimListElem *ale, eAnimChannel_Settings se
   }
 }
 
-/* node tree expander type define */
+/** Mesh expander type define. */
 static bAnimChannelType ACF_DSMESH = {
     "Mesh Expander",        /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -2695,7 +2695,7 @@ static void *acf_dslat_setting_ptr(bAnimListElem *ale, eAnimChannel_Settings set
   }
 }
 
-/* node tree expander type define */
+/** Lattice expander type define. */
 static bAnimChannelType ACF_DSLAT = {
     "Lattice Expander",     /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -2775,7 +2775,7 @@ static void *acf_dsspk_setting_ptr(bAnimListElem *ale, eAnimChannel_Settings set
   }
 }
 
-/* speaker expander type define */
+/** Speaker expander type define. */
 static bAnimChannelType ACF_DSSPK = {
     "Speaker Expander",     /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -2856,7 +2856,7 @@ static void *acf_dscurves_setting_ptr(bAnimListElem *ale,
   }
 }
 
-/* Curves expander type define */
+/** Curves expander type define. */
 static bAnimChannelType ACF_DSHAIR = {
     "Curves Expander",      /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -2937,7 +2937,7 @@ static void *acf_dspointcloud_setting_ptr(bAnimListElem *ale,
   }
 }
 
-/* pointcloud expander type define */
+/** Point-cloud expander type define. */
 static bAnimChannelType ACF_DSPOINTCLOUD = {
     "PointCloud Expander",  /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -3018,7 +3018,7 @@ static void *acf_dsvolume_setting_ptr(bAnimListElem *ale,
   }
 }
 
-/* volume expander type define */
+/** Volume expander type define. */
 static bAnimChannelType ACF_DSVOLUME = {
     "Volume Expander",      /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -3097,6 +3097,7 @@ static void *acf_dssimulation_setting_ptr(bAnimListElem *ale,
   }
 }
 
+/** Simulation expander type define. */
 static bAnimChannelType ACF_DSSIMULATION = {
     "Simulation Expander",  /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -3177,7 +3178,7 @@ static void *acf_dsgpencil_setting_ptr(bAnimListElem *ale,
   }
 }
 
-/* grease pencil expander type define */
+/** Grease-pencil expander type define. */
 static bAnimChannelType ACF_DSGPENCIL = {
     "GPencil DS Expander",  /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -3258,7 +3259,7 @@ static void *acf_dsmclip_setting_ptr(bAnimListElem *ale,
   }
 }
 
-/* world expander type define */
+/** Movie-clip expander type define. */
 static bAnimChannelType ACF_DSMCLIP = {
     "Movieclip Expander",   /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -3373,7 +3374,7 @@ static void *acf_shapekey_setting_ptr(bAnimListElem *ale,
   }
 }
 
-/* shapekey expander type define */
+/** Shape-key expander type define. */
 static bAnimChannelType ACF_SHAPEKEY = {
     "Shape Key",           /* type name */
     ACHANNEL_ROLE_CHANNEL, /* role */
@@ -3453,7 +3454,7 @@ static void *acf_gpd_setting_ptr(bAnimListElem *ale,
   return GET_ACF_FLAG_PTR(gpd->flag, type);
 }
 
-/* gpencil datablock type define */
+/** Grease-pencil data-block type define. */
 static bAnimChannelType ACF_GPD = {
     "GPencil Datablock",    /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -3552,7 +3553,7 @@ static void *acf_gpl_setting_ptr(bAnimListElem *ale,
   return GET_ACF_FLAG_PTR(gpl->flag, type);
 }
 
-/* grease pencil layer type define */
+/** Grease-pencil layer type define. */
 static bAnimChannelType ACF_GPL = {
     "GPencil Layer",       /* type name */
     ACHANNEL_ROLE_CHANNEL, /* role */
@@ -3634,7 +3635,7 @@ static void *acf_mask_setting_ptr(bAnimListElem *ale,
   return GET_ACF_FLAG_PTR(mask->flag, type);
 }
 
-/* mask datablock type define */
+/** Mask data-block type define. */
 static bAnimChannelType ACF_MASKDATA = {
     "Mask Datablock",       /* type name */
     ACHANNEL_ROLE_EXPANDER, /* role */
@@ -3730,7 +3731,7 @@ static void *acf_masklay_setting_ptr(bAnimListElem *ale,
   return GET_ACF_FLAG_PTR(masklay->flag, type);
 }
 
-/* grease pencil layer type define */
+/** Mask layer type define. */
 static bAnimChannelType ACF_MASKLAYER = {
     "Mask Layer",          /* type name */
     ACHANNEL_ROLE_CHANNEL, /* role */
@@ -3870,7 +3871,7 @@ static void *acf_nlatrack_setting_ptr(bAnimListElem *ale,
   return GET_ACF_FLAG_PTR(nlt->flag, type);
 }
 
-/* nla track type define */
+/** NLA track type define. */
 static bAnimChannelType ACF_NLATRACK = {
     "NLA Track",           /* type name */
     ACHANNEL_ROLE_CHANNEL, /* role */
diff --git a/source/blender/editors/animation/keyframing.c b/source/blender/editors/animation/keyframing.c
index 90c127b620b..0f93d728c8c 100644
--- a/source/blender/editors/animation/keyframing.c
+++ b/source/blender/editors/animation/keyframing.c
@@ -2848,13 +2848,12 @@ static bool object_frame_has_keyframe(Object *ob, float frame, short filter)
     }
   }
 
-  /* try shapekey keyframes (if available, and allowed by filter) */
+  /* Try shape-key keyframes (if available, and allowed by filter). */
   if (!(filter & ANIMFILTER_KEYS_LOCAL) && !(filter & ANIMFILTER_KEYS_NOSKEY)) {
     Key *key = BKE_key_from_object(ob);
 
-    /* shapekeys can have keyframes ('Relative Shape Keys')
-     * or depend on time (old 'Absolute Shape Keys')
-     */
+    /* Shape-keys can have keyframes ('Relative Shape Keys')
+     * or depend on time (old 'Absolute Shape Keys'). */
 
     /* 1. test for relative (with keyframes) */
     if (id_frame_has_keyframe((ID *)key, frame, filter)) {
diff --git a/source/blender/editors/include/ED_screen_types.h b/source/blender/editors/include/ED_screen_types.h
index 86fb5251ff3..21bb412d072 100644
--- a/source/blender/editors/include/ED_screen_types.h
+++ b/source/blender/editors/include/ED_screen_types.h
@@ -13,7 +13,9 @@ extern "C" {
 
 /* ----------------------------------------------------- */
 
-/* for animplayer */
+/**
+ * For animation playback operator, stored in #bScreen.animtimer.customdata.
+ */
 typedef struct ScreenAnimData {
   ARegion *region; /* do not read from this, only for comparing if region exists */
   short redraws;
@@ -24,7 +26,7 @@ typedef struct ScreenAnimData {
   bool from_anim_edit;        /* playback was invoked from animation editor */
 } ScreenAnimData;
 
-/* for animplayer */
+/** #ScreenAnimData.flag */
 enum {
   /* user-setting - frame range is played backwards */
   ANIMPLAY_FLAG_REVERSE = (1 << 0),
diff --git a/source/blender/editors/include/ED_view3d.h b/source/blender/editors/include/ED_view3d.h
index b1435e76eb2..d2ff5637a13 100644
--- a/source/blender/editors/include/ED_view3d.h
+++ b/source/blender/editors/include/ED_view3d.h
@@ -646,7 +646,7 @@ bool ED_view3d_win_to_3d_on_plane_int(const struct ARegion *region,
  *
  * \param region: The region (used for the window width and height).
  * \param xy_delta: 2D difference (in pixels) such as `event->mval[0] - other_x`.
- * \param zfac: The depth result typically calculated by by #ED_view3d_calc_zfac
+ * \param zfac: The depth result typically calculated by #ED_view3d_calc_zfac
  * (see it's doc-string for details).
  * \param r_out: The resulting world-space delta.
  */
@@ -661,7 +661,7 @@ void ED_view3d_win_to_delta(const struct ARegion *region,
  * the origin in this case is close to zero coordinate.
  *
  * \param region: The region (used for the window width and height).
- * \param mval: The area relative 2d location (such as event->mval converted to floats).
+ * \param mval: The area relative 2d location (such as `event->mval` converted to float).
  * \param r_out: The resulting normalized world-space direction vector.
  */
 void ED_view3d_win_to_origin(const struct ARegion *region, const float mval[2], float r_out[3]);
@@ -675,7 +675,7 @@ void ED_view3d_win_to_origin(const struct ARegion *region, const float mval[2],
  * the mouse cursor as a normalized vector.
  *
  * \param region: The region (used for the window width and height).
- * \param mval: The area relative 2d location (such as event->mval converted to floats).
+ * \param mval: The area relative 2d location (such as `event->mval` converted to float).
  * \param r_out: The resulting normalized world-space direction vector.
  */
 void ED_view3d_win_to_vector(const struct ARegion *region, const float mval[2], float r_out[3]);
diff --git a/source/blender/editors/mask/mask_edit.c b/source/blender/editors/mask/mask_edit.c
index 819ffd96b1c..b2d49bcc642 100644
--- a/source/blender/editors/mask/mask_edit.c
+++ b/source/blender/editors/mask/mask_edit.c
@@ -111,7 +111,7 @@ void ED_operatortypes_mask(void)
   WM_operatortype_append(MASK_OT_parent_set);
   WM_operatortype_append(MASK_OT_parent_clear);
 
-  /* shapekeys */
+  /* Shape-keys. */
   WM_operatortype_append(MASK_OT_shape_key_insert);
   WM_operatortype_append(MASK_OT_shape_key_clear);
   WM_operatortype_append(MASK_OT_shape_key_feather_reset);
diff --git a/source/blender/editors/mask/mask_editaction.c b/source/blender/editors/mask/mask_editaction.c
index 8bb6e8a71db..8a23a53a5d2 100644
--- a/source/blender/editors/mask/mask_editaction.c
+++ b/source/blender/editors/mask/mask_editaction.c
@@ -30,8 +30,8 @@
 /* ***************************************** */
 /* NOTE ABOUT THIS FILE:
  * This file contains code for editing Mask data in the Action Editor
- * as a 'keyframes', so that a user can adjust the timing of Mask shapekeys.
- * Therefore, this file mostly contains functions for selecting Mask frames (shapekeys).
+ * as a 'keyframes', so that a user can adjust the timing of Mask shape-keys.
+ * Therefore, this file mostly contains functions for selecting Mask frames (shape-keys).
  */
 /* ***************************************** */
 /* Generics - Loopers */
diff --git a/source/blender/editors/mesh/meshtools.c b/source/blender/editors/mesh/meshtools.c
index f3782c17845..d57471b658c 100644
--- a/source/blender/editors/mesh/meshtools.c
+++ b/source/blender/editors/mesh/meshtools.c
@@ -137,22 +137,22 @@ static void join_mesh_single(Depsgraph *depsgraph,
         mul_m4_v3(cmat, mvert->co);
       }
 
-      /* For each shapekey in destination mesh:
+      /* For each shape-key in destination mesh:
        * - if there's a matching one, copy it across
        *   (will need to transform vertices into new space...).
        * - otherwise, just copy own coordinates of mesh
        *   (no need to transform vertex coordinates into new space).
        */
       if (key) {
-        /* if this mesh has any shapekeys, check first, otherwise just copy coordinates */
+        /* if this mesh has any shape-keys, check first, otherwise just copy coordinates */
         LISTBASE_FOREACH (KeyBlock *, kb, &key->block) {
-          /* get pointer to where to write data for this mesh in shapekey's data array */
+          /* get pointer to where to write data for this mesh in shape-key's data array */
           float(*cos)[3] = ((float(*)[3])kb->data) + *vertofs;
 
-          /* check if this mesh has such a shapekey */
+          /* Check if this mesh has such a shape-key. */
           KeyBlock *okb = me->key ? BKE_keyblock_find_name(me->key, kb->name) : NULL;
           if (okb) {
-            /* copy this mesh's shapekey to the destination shapekey
+            /* copy this mesh's shape-key to the destination shape-key
              * (need to transform first) */
             float(*ocos)[3] = okb->data;
             for (a = 0; a < me->totvert; a++, cos++, ocos++) {
@@ -161,7 +161,7 @@ static void join_mesh_single(Depsgraph *depsgraph,
             }
           }
           else {
-            /* copy this mesh's vertex coordinates to the destination shapekey */
+            /* Copy this mesh's vertex coordinates to the destination shape-key. */
             for (a = 0, mvert = *mvert_pp; a < me->totvert; a++, cos++, mvert++) {
               copy_v3_v3(*cos, mvert->co);
             }
@@ -170,26 +170,26 @@ static void join_mesh_single(Depsgraph *depsgraph,
       }
     }
     else {
-      /* for each shapekey in destination mesh:
+      /* for each shape-key in destination mesh:
        * - if it was an 'original', copy the appropriate data from nkey
        * - otherwise, copy across plain coordinates (no need to transform coordinates)
        */
       if (key) {
         LISTBASE_FOREACH (KeyBlock *, kb, &key->block) {
-          /* get pointer to where to write data for this mesh in shapekey's data array */
+          /* get pointer to where to write data for this mesh in shape-key's data array */
           float(*cos)[3] = ((float(*)[3])kb->data) + *vertofs;
 
-          /* check if this was one of the original shapekeys */
+          /* Check if this was one of the original shape-keys. */
           KeyBlock *okb = nkey ? BKE_keyblock_find_name(nkey, kb->name) : NULL;
           if (okb) {
-            /* copy this mesh's shapekey to the destination shapekey */
+            /* copy this mesh's shape-key to the destination shape-key */
             float(*ocos)[3] = okb->data;
             for (a = 0; a < me->totvert; a++, cos++, ocos++) {
               copy_v3_v3(*cos, *ocos);
             }
           }
           else {
-            /* copy base-coordinates to the destination shapekey */
+            /* Copy base-coordinates to the destination shape-key. */
             for (a = 0, mvert = *mvert_pp; a < me->totvert; a++, cos++, mvert++) {
               copy_v3_v3(*cos, mvert->co);
             }
@@ -365,7 +365,7 @@ int ED_mesh_join_objects_exec(bContext *C, wmOperator *op)
         join_parent = true;
       }
 
-      /* check for shapekeys */
+      /* Check for shape-keys. */
       if (me->key) {
         haskey++;
       }
@@ -428,10 +428,10 @@ int ED_mesh_join_objects_exec(bContext *C, wmOperator *op)
     /* increase id->us : will be lowered later */
   }
 
-  /* - if destination mesh had shapekeys, move them somewhere safe, and set up placeholders
-   *   with arrays that are large enough to hold shapekey data for all meshes
-   * - if destination mesh didn't have shapekeys, but we encountered some in the meshes we're
-   *   joining, set up a new keyblock and assign to the mesh
+  /* - If destination mesh had shape-keys, move them somewhere safe, and set up placeholders
+   *   with arrays that are large enough to hold shape-key data for all meshes.
+   * - If destination mesh didn't have shape-keys, but we encountered some in the meshes we're
+   *   joining, set up a new key-block and assign to the mesh.
    */
   if (key) {
     /* make a duplicate copy that will only be used here... (must remember to free it!) */
@@ -518,8 +518,8 @@ int ED_mesh_join_objects_exec(bContext *C, wmOperator *op)
           }
         }
 
-        /* if this mesh has shapekeys,
-         * check if destination mesh already has matching entries too */
+        /* If this mesh has shape-keys,
+         * check if destination mesh already has matching entries too. */
         if (me->key && key) {
           /* for remapping KeyBlock.relative */
           int *index_map = MEM_mallocN(sizeof(int) * me->key->totkey, __func__);
@@ -713,7 +713,7 @@ int ED_mesh_join_objects_exec(bContext *C, wmOperator *op)
   /* other mesh users */
   BKE_objects_materials_test_all(bmain, (ID *)me);
 
-  /* free temp copy of destination shapekeys (if applicable) */
+  /* Free temporary copy of destination shape-keys (if applicable). */
   if (nkey) {
     /* We can assume nobody is using that ID currently. */
     BKE_id_free_ex(bmain, nkey, LIB_ID_FREE_NO_UI_USER, false);
diff --git a/source/blender/editors/space_node/node_draw.cc b/source/blender/editors/space_node/node_draw.cc
index 1286f6a818c..410572159bf 100644
--- a/source/blender/editors/space_node/node_draw.cc
+++ b/source/blender/editors/space_node/node_draw.cc
@@ -720,7 +720,7 @@ static void node_socket_draw_multi_input(const float color[4],
 {
   /* The other sockets are drawn with the keyframe shader. There, the outline has a base thickness
    * that can be varied but always scales with the size the socket is drawn at. Using `U.dpi_fac`
-   * has the the same effect here. It scales the outline correctly across different screen DPIs
+   * has the same effect here. It scales the outline correctly across different screen DPI's
    * and UI scales without being affected by the 'line-width'. */
   const float outline_width = NODE_SOCK_OUTLINE_SCALE * U.dpi_fac;
 
diff --git a/source/blender/gpencil_modifiers/intern/MOD_gpencil_ui_common.h b/source/blender/gpencil_modifiers/intern/MOD_gpencil_ui_common.h
index bbc0a3d26b6..57eac4d77bf 100644
--- a/source/blender/gpencil_modifiers/intern/MOD_gpencil_ui_common.h
+++ b/source/blender/gpencil_modifiers/intern/MOD_gpencil_ui_common.h
@@ -41,8 +41,8 @@ PanelType *gpencil_modifier_panel_register(struct ARegionType *region_type,
 /**
  * Add a child panel to the parent.
  *
- * \note To create the panel type's idname, it appends the \a name argument to the \a parent's
- * idname.
+ * \note To create the panel type's #PanelType.idname,
+ * it appends the \a name argument to the \a parent's `idname`.
  */
 struct PanelType *gpencil_modifier_subpanel_register(struct ARegionType *region_type,
                                                      const char *name,
diff --git a/source/blender/ikplugin/intern/iksolver_plugin.c b/source/blender/ikplugin/intern/iksolver_plugin.c
index d0cb7f00df8..6d99fde9df6 100644
--- a/source/blender/ikplugin/intern/iksolver_plugin.c
+++ b/source/blender/ikplugin/intern/iksolver_plugin.c
@@ -255,8 +255,10 @@ static void where_is_ik_bone(bPoseChannel *pchan,
   pchan->flag |= POSE_DONE;
 }
 
-/* called from within the core BKE_pose_where_is loop, all animsystems and constraints
- * were executed & assigned. Now as last we do an IK pass */
+/**
+ * Called from within the core #BKE_pose_where_is loop, all animation-systems and constraints
+ * were executed & assigned. Now as last we do an IK pass.
+ */
 static void execute_posetree(struct Depsgraph *depsgraph,
                              struct Scene *scene,
                              Object *ob,
diff --git a/source/blender/io/collada/AnimationImporter.cpp b/source/blender/io/collada/AnimationImporter.cpp
index b14de8be7df..8f5d2742b0e 100644
--- a/source/blender/io/collada/AnimationImporter.cpp
+++ b/source/blender/io/collada/AnimationImporter.cpp
@@ -719,7 +719,7 @@ void AnimationImporter::Assign_float_animations(const COLLADAFW::UniqueId &listi
           fcurve_deg_to_rad(fcu);
         }
       }
-      /** XXX What About animtype "rotation" ? */
+      /** XXX What About animation-type "rotation" ? */
 
       BLI_addtail(AnimCurves, fcu);
       fcurve_is_used(fcu);
@@ -1938,7 +1938,7 @@ bool AnimationImporter::evaluate_animation(COLLADAFW::Transformation *tm,
           return false;
         }
 
-        /* TODO: support other animclasses. */
+        /* TODO: support other animation-classes. */
         if (animclass != COLLADAFW::AnimationList::ANGLE) {
           report_class_type_unsupported(path, animclass, type);
           return false;
diff --git a/source/blender/makesdna/DNA_ID.h b/source/blender/makesdna/DNA_ID.h
index e3be31d3afe..c3132eeab3d 100644
--- a/source/blender/makesdna/DNA_ID.h
+++ b/source/blender/makesdna/DNA_ID.h
@@ -609,7 +609,7 @@ typedef struct PreviewImage {
 
 /** id->flag (persistent). */
 enum {
-  /** Don't delete the datablock even if unused. */
+  /** Don't delete the data-block even if unused. */
   LIB_FAKEUSER = 1 << 9,
   /**
    * The data-block is a sub-data of another one.
@@ -617,14 +617,14 @@ enum {
    */
   LIB_EMBEDDED_DATA = 1 << 10,
   /**
-   * Datablock is from a library and linked indirectly, with LIB_TAG_INDIRECT
+   * Data-block is from a library and linked indirectly, with LIB_TAG_INDIRECT
    * tag set. But the current .blend file also has a weak pointer to it that
    * we want to restore if possible, and silently drop if it's missing.
    */
   LIB_INDIRECT_WEAK_LINK = 1 << 11,
   /**
    * The data-block is a sub-data of another one, which is an override.
-   * Note that this also applies to shapekeys, even though they are not 100% embedded data...
+   * Note that this also applies to shape-keys, even though they are not 100% embedded data.
    */
   LIB_EMBEDDED_DATA_LIB_OVERRIDE = 1 << 12,
   /**
diff --git a/source/blender/makesdna/DNA_action_types.h b/source/blender/makesdna/DNA_action_types.h
index fa0898e6ea5..516d3ce94f9 100644
--- a/source/blender/makesdna/DNA_action_types.h
+++ b/source/blender/makesdna/DNA_action_types.h
@@ -875,27 +875,27 @@ typedef enum eSAction_Flag {
   SACTION_SHOW_MARKERS = (1 << 14),
 } eSAction_Flag;
 
-/* SpaceAction_Runtime.flag */
+/** #SpaceAction_Runtime.flag */
 typedef enum eSAction_Runtime_Flag {
   /** Temporary flag to force channel selections to be synced with main */
   SACTION_RUNTIME_FLAG_NEED_CHAN_SYNC = (1 << 0),
 } eSAction_Runtime_Flag;
 
-/* SpaceAction Mode Settings */
+/** #SpaceAction.mode */
 typedef enum eAnimEdit_Context {
-  /* action on the active object */
+  /** Action on the active object. */
   SACTCONT_ACTION = 0,
-  /* list of all shapekeys on the active object, linked with their F-Curves */
+  /** List of all shape-keys on the active object, linked with their F-Curves. */
   SACTCONT_SHAPEKEY = 1,
-  /* editing of gpencil data */
+  /** Editing of grease-pencil data. */
   SACTCONT_GPENCIL = 2,
-  /* dopesheet (default) */
+  /** Dope-sheet (default). */
   SACTCONT_DOPESHEET = 3,
-  /* mask */
+  /** Mask. */
   SACTCONT_MASK = 4,
-  /* cache file */
+  /** Cache file */
   SACTCONT_CACHEFILE = 5,
-  /* timeline - replacement for the standalone "timeline editor" */
+  /** Timeline - replacement for the standalone "timeline editor". */
   SACTCONT_TIMELINE = 6,
 } eAnimEdit_Context;
 
diff --git a/source/blender/makesrna/intern/rna_key.c b/source/blender/makesrna/intern/rna_key.c
index 7687dcbb11f..50b25157989 100644
--- a/source/blender/makesrna/intern/rna_key.c
+++ b/source/blender/makesrna/intern/rna_key.c
@@ -153,10 +153,10 @@ static void rna_ShapeKey_slider_max_set(PointerRNA *ptr, float value)
 
 #  undef SHAPEKEY_SLIDER_TOL
 
-/* ***** Normals accessors for shapekeys. ***** */
+/* ***** Normals accessors for shape-keys. ***** */
 /* NOTE: with this we may recompute several times the same data, should we want to access verts,
  *       then polys, then loops normals... However,
- *       such case looks rather unlikely - and not worth adding some kind of caching in KeyBlocks.
+ *       such case looks rather unlikely - and not worth adding some kind of caching in key-blocks.
  */
 
 static Mesh *rna_KeyBlock_normals_get_mesh(PointerRNA *ptr, ID *id)
diff --git a/source/blender/modifiers/intern/MOD_ui_common.h b/source/blender/modifiers/intern/MOD_ui_common.h
index 16e9dd25253..6548a897be9 100644
--- a/source/blender/modifiers/intern/MOD_ui_common.h
+++ b/source/blender/modifiers/intern/MOD_ui_common.h
@@ -51,8 +51,8 @@ struct PanelType *modifier_panel_register(struct ARegionType *region_type,
 /**
  * Add a child panel to the parent.
  *
- * \note To create the panel type's idname, it appends the \a name argument to the \a parent's
- * idname.
+ * \note To create the panel type's #PanelType.idname,
+ * it appends the \a name argument to the \a parent's `idname`.
  */
 struct PanelType *modifier_subpanel_register(struct ARegionType *region_type,
                                              const char *name,
diff --git a/source/blender/python/intern/bpy_rna.c b/source/blender/python/intern/bpy_rna.c
index 316cfe4d8b1..ab119377e7e 100644
--- a/source/blender/python/intern/bpy_rna.c
+++ b/source/blender/python/intern/bpy_rna.c
@@ -6229,7 +6229,7 @@ static PyObject *pyrna_func_call(BPy_FunctionRNA *self, PyObject *args, PyObject
       arg_name = PyUnicode_AsUTF8(key);
       found = false;
 
-      if (arg_name == NULL) { /* Unlikely the argname is not a string, but ignore if it is. */
+      if (arg_name == NULL) { /* Unlikely the `arg_name` is not a string, but ignore if it is. */
         PyErr_Clear();
       }
       else {
diff --git a/source/blender/windowmanager/WM_api.h b/source/blender/windowmanager/WM_api.h
index bc51f7d065a..6f8233c153e 100644
--- a/source/blender/windowmanager/WM_api.h
+++ b/source/blender/windowmanager/WM_api.h
@@ -615,7 +615,8 @@ bool WM_operator_poll_context(struct bContext *C, struct wmOperatorType *ot, sho
 /**
  * For running operators with frozen context (modal handlers, menus).
  *
- * \param store: Store settings for re-use.
+ * \param store: Store properties for re-use when an operator has finished
+ * (unless #PROP_SKIP_SAVE is set).
  *
  * \warning do not use this within an operator to call itself! T29537.
  */