Cleanup: move public doc-strings into headers for 'render'

Ref T92709

15 files changed, 228 insertions, 120 deletions

diff --git a/source/blender/render/RE_bake.h b/source/blender/render/RE_bake.h
index 47a15199701..b2c44e051d1 100644
--- a/source/blender/render/RE_bake.h
+++ b/source/blender/render/RE_bake.h
@@ -120,6 +120,10 @@ void RE_bake_normal_world_to_object(const BakePixel pixel_array[],
                                     float result[],
                                     struct Object *ob,
                                     const eBakeNormalSwizzle normal_swizzle[3]);
+/**
+ * This function converts an object space normal map
+ * to a tangent space normal map for a given low poly mesh.
+ */
 void RE_bake_normal_world_to_tangent(const BakePixel pixel_array[],
                                      const size_t num_pixels,
                                      const int depth,
diff --git a/source/blender/render/RE_engine.h b/source/blender/render/RE_engine.h
index 2a3a5964262..b22d263490c 100644
--- a/source/blender/render/RE_engine.h
+++ b/source/blender/render/RE_engine.h
@@ -180,6 +180,10 @@ typedef struct RenderEngine {
 RenderEngine *RE_engine_create(RenderEngineType *type);
 void RE_engine_free(RenderEngine *engine);
 
+/**
+ * Loads in image into a result, size must match
+ * x/y offsets are only used on a partial copy when dimensions don't match.
+ */
 void RE_layer_load_from_file(
     struct RenderLayer *layer, struct ReportList *reports, const char *filename, int x, int y);
 void RE_result_load_from_file(struct RenderResult *result,
diff --git a/source/blender/render/RE_pipeline.h b/source/blender/render/RE_pipeline.h
index 0d2d93ae026..073bb0a3697 100644
--- a/source/blender/render/RE_pipeline.h
+++ b/source/blender/render/RE_pipeline.h
@@ -167,8 +167,10 @@ typedef struct RenderStats {
 
 /* *********************** API ******************** */
 
-/* the name is used as identifier, so elsewhere in blender the result can retrieved */
-/* calling a new render with same name, frees automatic existing render */
+/**
+ * The name is used as identifier, so elsewhere in blender the result can retrieved.
+ * Calling a new render with same name, frees automatic existing render.
+ */
 struct Render *RE_NewRender(const char *name);
 struct Render *RE_GetRender(const char *name);
 
@@ -176,36 +178,80 @@ struct Scene;
 struct Render *RE_NewSceneRender(const struct Scene *scene);
 struct Render *RE_GetSceneRender(const struct Scene *scene);
 
-/* assign default dummy callbacks */
+/* Assign default dummy callbacks. */
+
+/**
+ * Called for new renders and when finishing rendering
+ * so we always have valid callbacks on a render.
+ */
 void RE_InitRenderCB(struct Render *re);
 
-/* use free render as signal to do everything over (previews) */
+/**
+ * Use free render as signal to do everything over (previews).
+ *
+ * Only call this while you know it will remove the link too.
+ */
 void RE_FreeRender(struct Render *re);
-/* only called on exit */
+/**
+ * Only called on exit.
+ */
 void RE_FreeAllRender(void);
 
-/* On file load, free render results. */
+/**
+ * On file load, free render results.
+ */
 void RE_FreeAllRenderResults(void);
-/* On file load or changes engines, free persistent render data.
- * Assumes no engines are currently rendering. */
+/**
+ * On file load or changes engines, free persistent render data.
+ * Assumes no engines are currently rendering.
+ */
 void RE_FreeAllPersistentData(void);
-/* Free persistent render data, optionally only for the given scene. */
+/**
+ * Free persistent render data, optionally only for the given scene.
+ */
 void RE_FreePersistentData(const Scene *scene);
 
-/* get results and statistics */
+/**
+ * Get results and statistics.
+ */
 void RE_FreeRenderResult(struct RenderResult *rr);
+/**
+ * If you want to know exactly what has been done.
+ */
 struct RenderResult *RE_AcquireResultRead(struct Render *re);
 struct RenderResult *RE_AcquireResultWrite(struct Render *re);
 void RE_ReleaseResult(struct Render *re);
+/**
+ * Same as #RE_AcquireResultImage but creating the necessary views to store the result
+ * fill provided result struct with a copy of thew views of what is done so far the
+ * #RenderResult.views #ListBase needs to be freed after with #RE_ReleaseResultImageViews
+ */
 void RE_AcquireResultImageViews(struct Render *re, struct RenderResult *rr);
+/**
+ * Clear temporary #RenderResult struct.
+ */
 void RE_ReleaseResultImageViews(struct Render *re, struct RenderResult *rr);
+
+/**
+ * Fill provided result struct with what's currently active or done.
+ * This #RenderResult struct is the only exception to the rule of a #RenderResult
+ * always having at least one #RenderView.
+ */
 void RE_AcquireResultImage(struct Render *re, struct RenderResult *rr, const int view_id);
 void RE_ReleaseResultImage(struct Render *re);
 void RE_SwapResult(struct Render *re, struct RenderResult **rr);
 void RE_ClearResult(struct Render *re);
 struct RenderStats *RE_GetStats(struct Render *re);
 
+/**
+ * Caller is responsible for allocating `rect` in correct size!
+ */
 void RE_ResultGet32(struct Render *re, unsigned int *rect);
+/**
+ * Only for acquired results, for lock.
+ *
+ * \note The caller is responsible for allocating `rect` in correct size!
+ */
 void RE_AcquiredResultGet32(struct Render *re,
                             struct RenderResult *result,
                             unsigned int *rect,
@@ -223,7 +269,10 @@ float *RE_RenderLayerGetPass(volatile struct RenderLayer *rl,
 
 bool RE_HasSingleLayer(struct Render *re);
 
-/* add passes for grease pencil */
+/**
+ * Add passes for grease pencil.
+ * Create a render-layer and render-pass for grease-pencil layer.
+ */
 struct RenderPass *RE_create_gp_pass(struct RenderResult *rr,
                                      const char *layername,
                                      const char *viewname);
@@ -236,7 +285,10 @@ void RE_create_render_pass(struct RenderResult *rr,
                            const char *viewname,
                            const bool allocate);
 
-/* obligatory initialize call, disprect is optional */
+/**
+ * Obligatory initialize call, doesn't change during entire render sequence.
+ * \param disprect: is optional. if NULL it assumes full window render.
+ */
 void RE_InitState(struct Render *re,
                   struct Render *source,
                   struct RenderData *rd,
@@ -246,15 +298,28 @@ void RE_InitState(struct Render *re,
                   int winy,
                   rcti *disprect);
 
-/* set up the viewplane/perspective matrix, three choices */
-struct Object *RE_GetCamera(struct Render *re); /* return camera override if set */
+/**
+ * Set up the view-plane/perspective matrix, three choices.
+ *
+ * \return camera override if set.
+ */
+struct Object *RE_GetCamera(struct Render *re);
 void RE_SetOverrideCamera(struct Render *re, struct Object *cam_ob);
+/**
+ * Per render, there's one persistent view-plane. Parts will set their own view-planes.
+ *
+ * \note call this after #RE_InitState().
+ */
 void RE_SetCamera(struct Render *re, struct Object *cam_ob);
 
-/* get current view and window transform */
+/**
+ * Get current view and window transform.
+ */
 void RE_GetViewPlane(struct Render *re, rctf *r_viewplane, rcti *r_disprect);
 
-/* Set the render threads based on the command-line and auto-threads setting. */
+/**
+ * Set the render threads based on the command-line and auto-threads setting.
+ */
 void RE_init_threadcount(Render *re);
 
 bool RE_WriteRenderViewsImage(struct ReportList *reports,
@@ -271,7 +336,11 @@ bool RE_WriteRenderViewsMovie(struct ReportList *reports,
                               const int totvideos,
                               bool preview);
 
-/* only RE_NewRender() needed, main Blender render calls */
+/**
+ * Only #RE_NewRender() needed, main Blender render calls.
+ *
+ * General Blender frame render call.
+ */
 void RE_RenderFrame(struct Render *re,
                     struct Main *bmain,
                     struct Scene *scene,
@@ -279,6 +348,9 @@ void RE_RenderFrame(struct Render *re,
                     struct Object *camera_override,
                     int frame,
                     const bool write_still);
+/**
+ * Saves images to disk.
+ */
 void RE_RenderAnim(struct Render *re,
                    struct Main *bmain,
                    struct Scene *scene,
@@ -298,13 +370,24 @@ void RE_RenderFreestyleExternal(struct Render *re);
 void RE_SetActiveRenderView(struct Render *re, const char *viewname);
 const char *RE_GetActiveRenderView(struct Render *re);
 
-/* error reporting */
+/**
+ * Error reporting.
+ */
 void RE_SetReports(struct Render *re, struct ReportList *reports);
 
-/* main preview render call */
+/**
+ * Main preview render call.
+ */
 void RE_PreviewRender(struct Render *re, struct Main *bmain, struct Scene *scene);
 
+/**
+ * Only the temp file!
+ */
 bool RE_ReadRenderResult(struct Scene *scene, struct Scene *scenode);
+/**
+ * Called from the UI and render pipeline, to save multi-layer and multi-view
+ * images, optionally isolating a specific, view, layer or RGBA/Z pass.
+ */
 bool RE_WriteRenderResult(struct ReportList *reports,
                           RenderResult *rr,
                           const char *filename,
@@ -314,7 +397,11 @@ bool RE_WriteRenderResult(struct ReportList *reports,
 struct RenderResult *RE_MultilayerConvert(
     void *exrhandle, const char *colorspace, bool predivide, int rectx, int recty);
 
-/* display and event callbacks */
+/* Display and event callbacks. */
+
+/**
+ * Image and movie output has to move to either imbuf or kernel.
+ */
 void RE_display_init_cb(struct Render *re,
                         void *handle,
                         void (*f)(void *handle, RenderResult *rr));
@@ -337,17 +424,27 @@ void RE_gl_context_destroy(Render *re);
 void *RE_gl_context_get(Render *re);
 void *RE_gpu_context_get(Render *re);
 
-/* should move to kernel once... still unsure on how/where */
+/**
+ * \param x: ranges from -1 to 1.
+ *
+ * TODO: Should move to kernel once... still unsure on how/where.
+ */
 float RE_filter_value(int type, float x);
 
 int RE_seq_render_active(struct Scene *scene, struct RenderData *rd);
 
+/**
+ * Used in the interface to decide whether to show layers or passes.
+ */
 bool RE_layers_have_name(struct RenderResult *result);
 bool RE_passes_have_name(struct RenderLayer *rl);
 
 struct RenderPass *RE_pass_find_by_name(volatile struct RenderLayer *rl,
                                         const char *name,
                                         const char *viewname);
+/**
+ * Only provided for API compatibility, don't use this in new code!
+ */
 struct RenderPass *RE_pass_find_by_type(volatile struct RenderLayer *rl,
                                         int passtype,
                                         const char *viewname);
@@ -358,8 +455,14 @@ struct RenderPass *RE_pass_find_by_type(volatile struct RenderLayer *rl,
 #define RE_BAKE_AO 2
 
 void RE_GetCameraWindow(struct Render *re, struct Object *camera, float mat[4][4]);
+/**
+ * Must be called after #RE_GetCameraWindow(), does not change `re->winmat`.
+ */
 void RE_GetCameraWindowWithOverscan(struct Render *re, float overscan, float r_winmat[4][4]);
 void RE_GetCameraModelMatrix(struct Render *re, struct Object *camera, float r_modelmat[4][4]);
+
+/* displist.c utility. */
+
 struct Scene *RE_GetScene(struct Render *re);
 void RE_SetScene(struct Render *re, struct Scene *sce);
 
diff --git a/source/blender/render/RE_texture.h b/source/blender/render/RE_texture.h
index 6b499c9d230..a2596096d4c 100644
--- a/source/blender/render/RE_texture.h
+++ b/source/blender/render/RE_texture.h
@@ -18,16 +18,14 @@
  */
 /** \file
  * \ingroup render
+ *
+ * This include is for non-render pipeline exports (still old cruft here).
  */
 
 #pragma once
 
 #include "BLI_compiler_attrs.h"
 
-/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */
-/* this include is for non-render pipeline exports (still old cruft here) */
-/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */
-
 /* called by meshtools */
 struct Depsgraph;
 struct ImagePool;
@@ -39,6 +37,12 @@ extern "C" {
 #endif
 
 /* texture_procedural.c */
+
+/**
+ * \param pool: Thread pool, may be NULL.
+ *
+ * \return True if the texture has color, otherwise false.
+ */
 bool RE_texture_evaluate(const struct MTex *mtex,
                          const float vec[3],
                          const int thread,
@@ -49,6 +53,13 @@ bool RE_texture_evaluate(const struct MTex *mtex,
                          float *r_intensity,
                          float r_rgba[4]) ATTR_NONNULL(1, 2, 7, 8);
 
+/**
+ * \param in: Destination
+ * \param tex: Texture.
+ * \param out: Previous color.
+ * \param fact Texture strength.
+ * \param facg: Button strength value.
+ */
 void texture_rgb_blend(
     float in[3], const float tex[3], const float out[3], float fact, float facg, int blendtype);
 float texture_value_blend(float tex, float out, float fact, float facg, int blendtype);
@@ -57,9 +68,11 @@ void RE_texture_rng_init(void);
 void RE_texture_rng_exit(void);
 
 /* texture_image.c */
+
 void ibuf_sample(struct ImBuf *ibuf, float fx, float fy, float dx, float dy, float result[4]);
 
 /* texture_pointdensity.c */
+
 struct PointDensity;
 
 void RE_point_density_cache(struct Depsgraph *depsgraph, struct PointDensity *pd);
@@ -69,6 +82,10 @@ void RE_point_density_minmax(struct Depsgraph *depsgraph,
                              float r_min[3],
                              float r_max[3]);
 
+/**
+ * \note Requires #RE_point_density_cache() to be called first.
+ * \note Frees point density structure after sampling.
+ */
 void RE_point_density_sample(struct Depsgraph *depsgraph,
                              struct PointDensity *pd,
                              const int resolution,
@@ -80,8 +97,10 @@ void RE_point_density_fix_linking(void);
 
 /* texture_procedural.c */
 
-/* Texture evaluation result.
- * NOTE: tr tg tb ta has to remain in this order for array access. */
+/**
+ * Texture evaluation result.
+ * \note `tr tg tb ta` have to remain in this order for array access.
+ */
 typedef struct TexResult {
   float tin, tr, tg, tb, ta;
   int talpha;
@@ -89,6 +108,14 @@ typedef struct TexResult {
 } TexResult;
 
 /* This one uses nodes. */
+
+/**
+ * \warning if the texres's values are not declared zero,
+ * check the return value to be sure the color values are set before using the r/g/b values,
+ * otherwise you may use uninitialized values - Campbell
+ *
+ * Use it for stuff which is out of render pipeline.
+ */
 int multitex_ext(struct Tex *tex,
                  float texvec[3],
                  float dxt[3],
@@ -99,14 +126,26 @@ int multitex_ext(struct Tex *tex,
                  struct ImagePool *pool,
                  bool scene_color_manage,
                  const bool skip_load_image);
-/* Nodes disabled. */
+
+/**
+ * Nodes disabled.
+ * extern-tex doesn't support nodes (#ntreeBeginExec() can't be called when rendering is going on).
+ *
+ * Use it for stuff which is out of render pipeline.
+ */
 int multitex_ext_safe(struct Tex *tex,
                       const float texvec[3],
                       struct TexResult *texres,
                       struct ImagePool *pool,
                       bool scene_color_manage,
                       const bool skip_load_image);
-/* Only for internal node usage. */
+
+/**
+ * Only for internal node usage.
+ *
+ * this is called from the shader and texture nodes
+ * Use it from render pipeline only!
+ */
 int multitex_nodes(struct Tex *tex,
                    const float texvec[3],
                    float dxt[3],
diff --git a/source/blender/render/intern/bake.c b/source/blender/render/intern/bake.c
index 0f893ce8cd5..6794a9cd1ad 100644
--- a/source/blender/render/intern/bake.c
+++ b/source/blender/render/intern/bake.c
@@ -814,10 +814,6 @@ static void normal_compress(float out[3],
   }
 }
 
-/**
- * This function converts an object space normal map
- * to a tangent space normal map for a given low poly mesh.
- */
 void RE_bake_normal_world_to_tangent(const BakePixel pixel_array[],
                                      const size_t num_pixels,
                                      const int depth,
diff --git a/source/blender/render/intern/engine.c b/source/blender/render/intern/engine.c
index cb92b15f873..e1778897777 100644
--- a/source/blender/render/intern/engine.c
+++ b/source/blender/render/intern/engine.c
@@ -784,6 +784,7 @@ void RE_engine_frame_set(RenderEngine *engine, int frame, float subframe)
 }
 
 /* Bake */
+
 void RE_bake_engine_set_engine_parameters(Render *re, Main *bmain, Scene *scene)
 {
   re->scene = scene;
diff --git a/source/blender/render/intern/initrender.c b/source/blender/render/intern/initrender.c
index 2370d8e893b..f696b81cffb 100644
--- a/source/blender/render/intern/initrender.c
+++ b/source/blender/render/intern/initrender.c
@@ -121,7 +121,6 @@ static float filt_mitchell(float x) /* Mitchell & Netravali's two-param cubic */
   return 0.0f;
 }
 
-/* x ranges from -1 to 1 */
 float RE_filter_value(int type, float x)
 {
   float gaussfac = 1.6f;
@@ -163,6 +162,7 @@ float RE_filter_value(int type, float x)
 }
 
 /* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */
+
 struct Object *RE_GetCamera(Render *re)
 {
   Object *camera = re->camera_override ? re->camera_override : re->scene->camera;
@@ -174,11 +174,6 @@ void RE_SetOverrideCamera(Render *re, Object *cam_ob)
   re->camera_override = cam_ob;
 }
 
-/**
- * Per render, there's one persistent view-plane. Parts will set their own view-planes.
- *
- * \note call this after #RE_InitState().
- */
 void RE_SetCamera(Render *re, Object *cam_ob)
 {
   CameraParams params;
@@ -205,7 +200,6 @@ void RE_GetCameraWindow(struct Render *re, struct Object *camera, float r_winmat
   copy_m4_m4(r_winmat, re->winmat);
 }
 
-/* Must be called after RE_GetCameraWindow(), does not change re->winmat. */
 void RE_GetCameraWindowWithOverscan(struct Render *re, float overscan, float r_winmat[4][4])
 {
   CameraParams params;
diff --git a/source/blender/render/intern/pipeline.c b/source/blender/render/intern/pipeline.c
index 1bf0dfe079c..a800361a41f 100644
--- a/source/blender/render/intern/pipeline.c
+++ b/source/blender/render/intern/pipeline.c
@@ -338,7 +338,6 @@ Render *RE_GetRender(const char *name)
   return re;
 }
 
-/* if you want to know exactly what has been done */
 RenderResult *RE_AcquireResultRead(Render *re)
 {
   if (re) {
@@ -383,7 +382,6 @@ void RE_ReleaseResult(Render *re)
   }
 }
 
-/* displist.c util.... */
 Scene *RE_GetScene(Render *re)
 {
   if (re) {
@@ -399,11 +397,6 @@ void RE_SetScene(Render *re, Scene *sce)
   }
 }
 
-/**
- * Same as #RE_AcquireResultImage but creating the necessary views to store the result
- * fill provided result struct with a copy of thew views of what is done so far the
- * #RenderResult.views #ListBase needs to be freed after with #RE_ReleaseResultImageViews
- */
 void RE_AcquireResultImageViews(Render *re, RenderResult *rr)
 {
   memset(rr, 0, sizeof(RenderResult));
@@ -449,7 +442,6 @@ void RE_AcquireResultImageViews(Render *re, RenderResult *rr)
   }
 }
 
-/* clear temporary renderresult struct */
 void RE_ReleaseResultImageViews(Render *re, RenderResult *rr)
 {
   if (re) {
@@ -460,9 +452,6 @@ void RE_ReleaseResultImageViews(Render *re, RenderResult *rr)
   }
 }
 
-/* fill provided result struct with what's currently active or done */
-/* this RenderResult struct is the only exception to the rule of a RenderResult */
-/* always having at least one RenderView */
 void RE_AcquireResultImage(Render *re, RenderResult *rr, const int view_id)
 {
   memset(rr, 0, sizeof(RenderResult));
@@ -516,7 +505,6 @@ void RE_ReleaseResultImage(Render *re)
   }
 }
 
-/* caller is responsible for allocating rect in correct size! */
 void RE_ResultGet32(Render *re, unsigned int *rect)
 {
   RenderResult rres;
@@ -533,8 +521,6 @@ void RE_ResultGet32(Render *re, unsigned int *rect)
   RE_ReleaseResultImageViews(re, &rres);
 }
 
-/* caller is responsible for allocating rect in correct size! */
-/* Only for acquired results, for lock */
 void RE_AcquiredResultGet32(Render *re,
                             RenderResult *result,
                             unsigned int *rect,
@@ -603,8 +589,6 @@ Render *RE_NewSceneRender(const Scene *scene)
   return RE_NewRender(render_name);
 }
 
-/* called for new renders and when finishing rendering so
- * we always have valid callbacks on a render */
 void RE_InitRenderCB(Render *re)
 {
   /* set default empty callbacks */
@@ -624,7 +608,6 @@ void RE_InitRenderCB(Render *re)
   re->dih = re->dch = re->duh = re->sdh = re->prh = re->tbh = NULL;
 }
 
-/* only call this while you know it will remove the link too */
 void RE_FreeRender(Render *re)
 {
   if (re->engine) {
@@ -655,7 +638,6 @@ void RE_FreeRender(Render *re)
   MEM_freeN(re);
 }
 
-/* exit blender */
 void RE_FreeAllRender(void)
 {
   while (RenderGlobal.renderlist.first) {
@@ -668,7 +650,6 @@ void RE_FreeAllRender(void)
 #endif
 }
 
-/* on file load, free all re */
 void RE_FreeAllRenderResults(void)
 {
   Render *re;
@@ -769,8 +750,6 @@ void render_copy_renderdata(RenderData *to, RenderData *from)
   BKE_curvemapping_copy_data(&to->mblur_shutter_curve, &from->mblur_shutter_curve);
 }
 
-/* what doesn't change during entire render sequence */
-/* disprect is optional, if NULL it assumes full window render */
 void RE_InitState(Render *re,
                   Render *source,
                   RenderData *rd,
@@ -874,8 +853,6 @@ void RE_InitState(Render *re,
   RE_point_density_fix_linking();
 }
 
-/* update some variables that can be animated, and otherwise wouldn't be due to
- * RenderData getting copied once at the start of animation render */
 void render_update_anim_renderdata(Render *re, RenderData *rd, ListBase *render_layers)
 {
   /* filter */
@@ -897,7 +874,6 @@ void render_update_anim_renderdata(Render *re, RenderData *rd, ListBase *render_
   BLI_duplicatelist(&re->r.views, &rd->views);
 }
 
-/* image and movie output has to move to either imbuf or kernel */
 void RE_display_init_cb(Render *re, void *handle, void (*f)(void *handle, RenderResult *rr))
 {
   re->display_init = f;
@@ -1834,7 +1810,6 @@ static void render_pipeline_free(Render *re)
   }
 }
 
-/* general Blender frame render call */
 void RE_RenderFrame(Render *re,
                     Main *bmain,
                     Scene *scene,
@@ -2280,7 +2255,6 @@ static void re_movie_free_all(Render *re, bMovieHandle *mh, int totvideos)
   MEM_SAFE_FREE(re->movie_ctx_arr);
 }
 
-/* saves images to disk */
 void RE_RenderAnim(Render *re,
                    Main *bmain,
                    Scene *scene,
@@ -2583,7 +2557,6 @@ void RE_PreviewRender(Render *re, Main *bmain, Scene *sce)
 
 /* NOTE: repeated win/disprect calc... solve that nicer, also in compo. */
 
-/* only the temp file! */
 bool RE_ReadRenderResult(Scene *scene, Scene *scenode)
 {
   Render *re;
@@ -2635,8 +2608,6 @@ void RE_init_threadcount(Render *re)
   re->r.threads = BKE_render_num_threads(&re->r);
 }
 
-/* loads in image into a result, size must match
- * x/y offsets are only used on a partial copy when dimensions don't match */
 void RE_layer_load_from_file(
     RenderLayer *layer, ReportList *reports, const char *filename, int x, int y)
 {
@@ -2712,7 +2683,6 @@ void RE_result_load_from_file(RenderResult *result, ReportList *reports, const c
   }
 }
 
-/* Used in the interface to decide whether to show layers or passes. */
 bool RE_layers_have_name(struct RenderResult *rr)
 {
   switch (BLI_listbase_count_at_most(&rr->layers, 2)) {
@@ -2754,7 +2724,6 @@ RenderPass *RE_pass_find_by_name(volatile RenderLayer *rl, const char *name, con
   return rp;
 }
 
-/* Only provided for API compatibility, don't use this in new code! */
 RenderPass *RE_pass_find_by_type(volatile RenderLayer *rl, int passtype, const char *viewname)
 {
 #define CHECK_PASS(NAME) \
@@ -2793,7 +2762,6 @@ RenderPass *RE_pass_find_by_type(volatile RenderLayer *rl, int passtype, const c
   return NULL;
 }
 
-/* create a renderlayer and renderpass for grease pencil layer */
 RenderPass *RE_create_gp_pass(RenderResult *rr, const char *layername, const char *viewname)
 {
   RenderLayer *rl = BLI_findstring(&rr->layers, layername, offsetof(RenderLayer, name));
diff --git a/source/blender/render/intern/pipeline.h b/source/blender/render/intern/pipeline.h
index 062df59bfd3..ba2e382619d 100644
--- a/source/blender/render/intern/pipeline.h
+++ b/source/blender/render/intern/pipeline.h
@@ -34,6 +34,10 @@ extern "C" {
 #endif
 
 struct RenderLayer *render_get_active_layer(struct Render *re, struct RenderResult *rr);
+/**
+ * Update some variables that can be animated, and otherwise wouldn't be due to
+ * #RenderData getting copied once at the start of animation render.
+ */
 void render_update_anim_renderdata(struct Render *re,
                                    struct RenderData *rd,
                                    struct ListBase *render_layers);
diff --git a/source/blender/render/intern/render_result.c b/source/blender/render/intern/render_result.c
index 0681bcd9aa5..a21351539f6 100644
--- a/source/blender/render/intern/render_result.c
+++ b/source/blender/render/intern/render_result.c
@@ -126,7 +126,6 @@ void render_result_free(RenderResult *rr)
   MEM_freeN(rr);
 }
 
-/** Version that's compatible with full-sample buffers. */
 void render_result_free_list(ListBase *lb, RenderResult *rr)
 {
   RenderResult *rrnext;
@@ -144,7 +143,6 @@ void render_result_free_list(ListBase *lb, RenderResult *rr)
 
 /********************************* multiview *************************************/
 
-/* create a new views Listbase in rr without duplicating the memory pointers */
 void render_result_views_shallowcopy(RenderResult *dst, RenderResult *src)
 {
   RenderView *rview;
@@ -166,7 +164,6 @@ void render_result_views_shallowcopy(RenderResult *dst, RenderResult *src)
   }
 }
 
-/* free the views created temporarily */
 void render_result_views_shallowdelete(RenderResult *rr)
 {
   if (rr == NULL) {
@@ -286,10 +283,6 @@ RenderPass *render_layer_add_pass(RenderResult *rr,
   return rpass;
 }
 
-/* called by main render as well for parts */
-/* will read info from Render *re to define layers */
-/* called in threads */
-/* re->winx,winy is coordinate space of entire image, partrct the part within */
 RenderResult *render_result_new(Render *re,
                                 rcti *partrct,
                                 const char *layername,
@@ -733,10 +726,6 @@ static int order_render_passes(const void *a, const void *b)
   return (rpa->view_id < rpb->view_id);
 }
 
-/**
- * From imbuf, if a handle was returned and
- * it's not a single-layer multi-view we convert this to render result.
- */
 RenderResult *render_result_new_from_exr(
     void *exrhandle, const char *colorspace, bool predivide, int rectx, int recty)
 {
@@ -837,9 +826,6 @@ static void do_merge_tile(
   }
 }
 
-/* used when rendering to a full buffer, or when reading the exr part-layer-pass file */
-/* no test happens here if it fits... we also assume layers are in sync */
-/* is used within threads */
 void render_result_merge(RenderResult *rr, RenderResult *rrpart)
 {
   RenderLayer *rl, *rlp;
@@ -869,8 +855,6 @@ void render_result_merge(RenderResult *rr, RenderResult *rrpart)
   }
 }
 
-/* Called from the UI and render pipeline, to save multilayer and multiview
- * images, optionally isolating a specific, view, layer or RGBA/Z pass. */
 bool RE_WriteRenderResult(ReportList *reports,
                           RenderResult *rr,
                           const char *filename,
@@ -1040,7 +1024,6 @@ void render_result_single_layer_begin(Render *re)
   re->result = NULL;
 }
 
-/* if scemode is R_SINGLE_LAYER, at end of rendering, merge the both render results */
 void render_result_single_layer_end(Render *re)
 {
   ViewLayer *view_layer;
@@ -1085,7 +1068,6 @@ void render_result_single_layer_end(Render *re)
   re->pushedresult = NULL;
 }
 
-/* called for reading temp files, and for external engines */
 int render_result_exr_file_read_path(RenderResult *rr,
                                      RenderLayer *rl_single,
                                      const char *filepath)
@@ -1184,7 +1166,6 @@ void render_result_exr_file_cache_write(Render *re)
   RE_WriteRenderResult(NULL, rr, str, NULL, NULL, -1);
 }
 
-/* For cache, makes exact copy of render result */
 bool render_result_exr_file_cache_read(Render *re)
 {
   /* File path to cache. */
diff --git a/source/blender/render/intern/render_result.h b/source/blender/render/intern/render_result.h
index 34b8143869c..ede0a0d21ea 100644
--- a/source/blender/render/intern/render_result.h
+++ b/source/blender/render/intern/render_result.h
@@ -46,6 +46,12 @@ extern "C" {
 
 /* New */
 
+/**
+ * Called by main render as well for parts will read info from Render *re to define layers.
+ * \note Called in threads.
+ *
+ * `re->winx`, `re->winy` is coordinate space of entire image, `partrct` the part within.
+ */
 struct RenderResult *render_result_new(struct Render *re,
                                        struct rcti *partrct,
                                        const char *layername,
@@ -53,6 +59,10 @@ struct RenderResult *render_result_new(struct Render *re,
 
 void render_result_passes_allocated_ensure(struct RenderResult *rr);
 
+/**
+ * From imbuf, if a handle was returned and
+ * it's not a single-layer multi-view we convert this to render result.
+ */
 struct RenderResult *render_result_new_from_exr(
     void *exrhandle, const char *colorspace, bool predivide, int rectx, int recty);
 
@@ -61,6 +71,11 @@ void render_result_views_new(struct RenderResult *rr, const struct RenderData *r
 
 /* Merge */
 
+/**
+ * Used when rendering to a full buffer, or when reading the EXR part-layer-pass file.
+ * no test happens here if it fits... we also assume layers are in sync.
+ * \note Is used within threads.
+ */
 void render_result_merge(struct RenderResult *rr, struct RenderResult *rrpart);
 
 /* Add Passes */
@@ -70,14 +85,22 @@ void render_result_clone_passes(struct Render *re, struct RenderResult *rr, cons
 /* Free */
 
 void render_result_free(struct RenderResult *rr);
+/**
+ * Version that's compatible with full-sample buffers.
+ */
 void render_result_free_list(struct ListBase *lb, struct RenderResult *rr);
 
 /* Single Layer Render */
 
 void render_result_single_layer_begin(struct Render *re);
+/**
+ * If #RenderData.scemode is #R_SINGLE_LAYER, at end of rendering, merge the both render results.
+ */
 void render_result_single_layer_end(struct Render *re);
 
-/* render pass wrapper for gpencil */
+/**
+ * Render pass wrapper for grease-pencil.
+ */
 struct RenderPass *render_layer_add_pass(struct RenderResult *rr,
                                          struct RenderLayer *rl,
                                          int channels,
@@ -86,6 +109,9 @@ struct RenderPass *render_layer_add_pass(struct RenderResult *rr,
                                          const char *chan_id,
                                          const bool allocate);
 
+/**
+ * Called for reading temp files, and for external engines.
+ */
 int render_result_exr_file_read_path(struct RenderResult *rr,
                                      struct RenderLayer *rl_single,
                                      const char *filepath);
@@ -93,6 +119,9 @@ int render_result_exr_file_read_path(struct RenderResult *rr,
 /* EXR cache */
 
 void render_result_exr_file_cache_write(struct Render *re);
+/**
+ * For cache, makes exact copy of render result.
+ */
 bool render_result_exr_file_cache_read(struct Render *re);
 
 /* Combined Pixel Rect */
@@ -110,7 +139,13 @@ void render_result_rect_get_pixels(struct RenderResult *rr,
                                    const struct ColorManagedDisplaySettings *display_settings,
                                    const int view_id);
 
+/**
+ * Create a new views #ListBase in rr without duplicating the memory pointers.
+ */
 void render_result_views_shallowcopy(struct RenderResult *dst, struct RenderResult *src);
+/**
+ * Free the views created temporarily.
+ */
 void render_result_views_shallowdelete(struct RenderResult *rr);
 bool render_result_has_views(const struct RenderResult *rr);
 
diff --git a/source/blender/render/intern/texture_pointdensity.c b/source/blender/render/intern/texture_pointdensity.c
index 06dd570ce2c..8ca1decdea7 100644
--- a/source/blender/render/intern/texture_pointdensity.c
+++ b/source/blender/render/intern/texture_pointdensity.c
@@ -928,9 +928,6 @@ static void point_density_sample_func(void *__restrict data_v,
   }
 }
 
-/* NOTE 1: Requires RE_point_density_cache() to be called first.
- * NOTE 2: Frees point density structure after sampling.
- */
 void RE_point_density_sample(Depsgraph *depsgraph,
                              PointDensity *pd,
                              const int resolution,
diff --git a/source/blender/render/intern/texture_procedural.c b/source/blender/render/intern/texture_procedural.c
index 5a94bc09b93..f563cb9f84a 100644
--- a/source/blender/render/intern/texture_procedural.c
+++ b/source/blender/render/intern/texture_procedural.c
@@ -1399,9 +1399,6 @@ static int multitex_nodes_intern(Tex *tex,
                   use_nodes);
 }
 
-/* this is called from the shader and texture nodes
- * Use it from render pipeline only!
- */
 int multitex_nodes(Tex *tex,
                    const float texvec[3],
                    float dxt[3],
@@ -1429,13 +1426,6 @@ int multitex_nodes(Tex *tex,
                                true);
 }
 
-/**
- * \warning if the texres's values are not declared zero,
- * check the return value to be sure the color values are set before using the r/g/b values,
- * otherwise you may use uninitialized values - Campbell
- *
- * Use it for stuff which is out of render pipeline.
- */
 int multitex_ext(Tex *tex,
                  float texvec[3],
                  float dxt[3],
@@ -1463,10 +1453,6 @@ int multitex_ext(Tex *tex,
                                true);
 }
 
-/* extern-tex doesn't support nodes (ntreeBeginExec() can't be called when rendering is going on)\
- *
- * Use it for stuff which is out of render pipeline.
- */
 int multitex_ext_safe(Tex *tex,
                       const float texvec[3],
                       TexResult *texres,
@@ -1492,8 +1478,6 @@ int multitex_ext_safe(Tex *tex,
 
 /* ------------------------------------------------------------------------- */
 
-/* in = destination, tex = texture, out = previous color */
-/* fact = texture strength, facg = button strength value */
 void texture_rgb_blend(
     float in[3], const float tex[3], const float out[3], float fact, float facg, int blendtype)
 {
@@ -1722,11 +1706,6 @@ float texture_value_blend(float tex, float out, float fact, float facg, int blen
 
 /* ------------------------------------------------------------------------- */
 
-/**
- * \param pool: Thread pool, may be NULL.
- *
- * \return True if the texture has color, otherwise false.
- */
 bool RE_texture_evaluate(const MTex *mtex,
                          const float vec[3],
                          const int thread,
diff --git a/source/blender/render/intern/zbuf.c b/source/blender/render/intern/zbuf.c
index 726124871ee..1812a492ac0 100644
--- a/source/blender/render/intern/zbuf.c
+++ b/source/blender/render/intern/zbuf.c
@@ -41,7 +41,6 @@
 
 /* ****************** Spans ******************************* */
 
-/* each zbuffer has coordinates transformed to local rect coordinates, so we can simply clip */
 void zbuf_alloc_span(ZSpan *zspan, int rectx, int recty)
 {
   memset(zspan, 0, sizeof(ZSpan));
@@ -170,9 +169,6 @@ static void zbuf_add_to_span(ZSpan *zspan, const float v1[2], const float v2[2])
 /* Functions                                                 */
 /*-----------------------------------------------------------*/
 
-/* Scan-convert for strand triangles, calls function for each x, y coordinate
- * and gives UV barycentrics and z. */
-
 void zspan_scanconvert(ZSpan *zspan,
                        void *handle,
                        float *v1,
diff --git a/source/blender/render/intern/zbuf.h b/source/blender/render/intern/zbuf.h
index 41fa15c594f..c5108a9d6a7 100644
--- a/source/blender/render/intern/zbuf.h
+++ b/source/blender/render/intern/zbuf.h
@@ -33,9 +33,16 @@ typedef struct ZSpan {
   float *span1, *span2;
 } ZSpan;
 
+/**
+ * Each Z-buffer has coordinates transformed to local rect coordinates, so we can simply clip.
+ */
 void zbuf_alloc_span(struct ZSpan *zspan, int rectx, int recty);
 void zbuf_free_span(struct ZSpan *zspan);
 
+/**
+ * Scan-convert for strand triangles, calls function for each x, y coordinate
+ * and gives UV barycentrics and z.
+ */
 void zspan_scanconvert(struct ZSpan *zspan,
                        void *handle,
                        float *v1,