Cleanup: move documentation to headers, other minor corrections

intern/ghost/GHOST_C-api.h

@@ -146,7 +146,7 @@ extern void GHOST_GetAllDisplayDimensions(GHOST_SystemHandle systemhandle,
  * The new window is added to the list of windows managed.
  * Never explicitly delete the window, use disposeWindow() instead.
  * \param systemhandle: The handle to the system.
- * \param parentWindow: Handle of parent (or owner) window, or NULL
+ * \param parent_windowhandle: Handle of parent (or owner) window, or NULL
  * \param title: The name of the window.
  * (displayed in the title bar of the window if the OS supports it).
  * \param left: The coordinate of the left edge of the window.
@@ -175,7 +175,7 @@ extern GHOST_WindowHandle GHOST_CreateWindow(GHOST_SystemHandle systemhandle,
  * Create a new off-screen context.
  * Never explicitly delete the context, use #disposeContext() instead.
  * \param systemhandle: The handle to the system.
- * \param platform_support_callback: An optional callback to check platform support.
+ * \param glSettings: Misc OpenGL options.
  * \return A handle to the new context ( == NULL if creation failed).
  */
 extern GHOST_ContextHandle GHOST_CreateOpenGLContext(GHOST_SystemHandle systemhandle,

source/blender/blenkernel/intern/armature.c

@@ -2164,8 +2164,8 @@ void vec_roll_to_mat3_normalized(const float nor[3], const float roll, float r_m
   const float y = nor[1];
   const float z = nor[2];
 
-  float theta = 1.0f + y;                /* remapping Y from [-1,+1] to [0,2]. */
-  const float theta_alt = x * x + z * z; /* squared distance from origin in x,z plane. */
+  float theta = 1.0f + y;                /* Remapping Y from [-1,+1] to [0,2]. */
+  const float theta_alt = x * x + z * z; /* Squared distance from origin in x,z plane. */
   float rMatrix[3][3], bMatrix[3][3];
 
   BLI_ASSERT_UNIT_V3(nor);

source/blender/blenlib/BLI_math_geom.h

@@ -202,7 +202,7 @@ float dist_to_line_v3(const float p[3], const float l1[3], const float l2[3]);
  * \return the lowest squared distance to either of the planes.
  * where `(return < 0.0)` is outside.
  *
- * <pre>
+ * \code{.unparsed}
  *            v1
  *            +
  *           /
@@ -211,7 +211,7 @@ float dist_to_line_v3(const float p[3], const float l1[3], const float l2[3]);
  *        +----+
  *        v2   v3
  *           x - also outside
- * </pre>
+ * \endcode
  */
 float dist_signed_squared_to_corner_v3v3v3(const float p[3],
                                            const float v1[3],

source/blender/bmesh/intern/bmesh_query.c

@@ -1869,7 +1869,7 @@ bool BM_face_exists_overlap_subset(BMVert **varr, const int len)
   for (int i = 0; i < len; i++) {
     BM_ITER_ELEM (f, &viter, varr[i], BM_FACES_OF_VERT) {
       if ((f->len <= len) && (BM_ELEM_API_FLAG_TEST(f, _FLAG_OVERLAP) == 0)) {
-        /* Check if all vers in this face are flagged. */
+        /* Check if all verts in this face are flagged. */
         BMLoop *l_iter, *l_first;
 
         if (is_init == false) {

source/blender/draw/intern/shaders/common_gpencil_lib.glsl

@@ -119,7 +119,7 @@ float gpencil_clamp_small_stroke_thickness(float thickness, vec4 ndc_pos)
  *
  * WARNING: Max attribute count is actually 14 because OSX OpenGL implementation
  * considers gl_VertexID and gl_InstanceID as vertex attribute. (see T74536)
- **/
+ */
 vec4 gpencil_vertex(ivec4 ma,
                     ivec4 ma1,
                     ivec4 ma2,

source/blender/makesrna/RNA_types.h

@@ -179,7 +179,7 @@ typedef enum PropertySubType {
 
 /* Make sure enums are updated with these */
 /* HIGHEST FLAG IN USE: 1 << 31
- * FREE FLAGS: 2, 9, 11, 13, 14, 15, 30 */
+ * FREE FLAGS: 2, 9, 11, 13, 14, 15. */
 typedef enum PropertyFlag {
   /**
    * Editable means the property is editable in the user

source/blender/makesrna/intern/rna_internal.h

@@ -393,7 +393,15 @@ char *rna_TextureSlot_path(struct PointerRNA *ptr);
 char *rna_Node_ImageUser_path(struct PointerRNA *ptr);
 
 /* Set U.is_dirty and redraw. */
+
+/**
+ * Use single function so we can more easily break-point it.
+ */
 void rna_userdef_is_dirty_update_impl(void);
+/**
+ * Use as a fallback update handler to ensure #U.runtime.is_dirty is set.
+ * So the preferences are saved when modified.
+ */
 void rna_userdef_is_dirty_update(struct Main *bmain, struct Scene *scene, struct PointerRNA *ptr);
 
 /* API functions */

source/blender/makesrna/intern/rna_userdef.c

@@ -208,7 +208,6 @@ static void rna_userdef_version_get(PointerRNA *ptr, int *value)
 /** Mark the preferences as being changed so they are saved on exit. */
 #  define USERDEF_TAG_DIRTY rna_userdef_is_dirty_update_impl()
 
-/** Use single function so we can more easily break-point it. */
 void rna_userdef_is_dirty_update_impl(void)
 {
   /* We can't use 'ptr->data' because this update function
@@ -219,14 +218,11 @@ void rna_userdef_is_dirty_update_impl(void)
   }
 }
 
-/**
- * Use as a fallback update handler,
- * never use 'ptr' unless its type is checked.
- */
 void rna_userdef_is_dirty_update(Main *UNUSED(bmain),
                                  Scene *UNUSED(scene),
                                  PointerRNA *UNUSED(ptr))
 {
+  /* WARNING: never use 'ptr' unless its type is checked. */
   rna_userdef_is_dirty_update_impl();
 }
 

source/blender/render/RE_pipeline.h

@@ -338,8 +338,8 @@ void RE_RenderFrame(struct Render *re,
                     struct Scene *scene,
                     struct ViewLayer *single_layer,
                     struct Object *camera_override,
-                    const int frame,
-                    const float subframe,
+                    int frame,
+                    float subframe,
                     bool write_still);
 /**
  * A version of #RE_RenderFrame that saves images to disk.

source/blender/render/RE_texture_margin.h

@@ -23,7 +23,7 @@ struct Mesh;
  * \param mask: pixels with a mask value of 1 are not written to.
  * \param margin: the size of the margin in pixels.
  * \param me: the mesh to use the polygons of.
- * \param mloopuv: the uv data to use.
+ * \param uv_layer: The UV layer to use.
  */
 void RE_generate_texturemargin_adjacentfaces(
     struct ImBuf *ibuf, char *mask, const int margin, struct Mesh const *me, char const *uv_layer);

source/blender/sequencer/intern/strip_transform.c

@@ -298,7 +298,7 @@ static int shuffle_seq_time_offset_test(SeqCollection *strips_to_shuffle,
       }
       if (UNLIKELY(SEQ_collection_has_strip(seq_other, strips_to_shuffle))) {
         CLOG_WARN(&LOG,
-                  "Strip overlaps with itself or another strip, that is to be shuffled."
+                  "Strip overlaps with itself or another strip, that is to be shuffled. "
                   "This should never happen.");
         continue;
       }