Cleanup: use doxy-sections for pipeline, text_drag & effects

Also improve on the doc-string for RE_RenderFrame & RE_RenderAnim.

2 files changed, 64 insertions, 14 deletions

diff --git a/source/blender/render/RE_pipeline.h b/source/blender/render/RE_pipeline.h
index 2d43aa7b27f..f532c705534 100644
--- a/source/blender/render/RE_pipeline.h
+++ b/source/blender/render/RE_pipeline.h
@@ -322,9 +322,13 @@ bool RE_WriteRenderViewsMovie(struct ReportList *reports,
                               bool preview);
 
 /**
- * Only #RE_NewRender() needed, main Blender render calls.
- *
  * General Blender frame render call.
+ *
+ * \note Only #RE_NewRender() needed, main Blender render calls.
+ *
+ * \param write_still: Saves frames to disk (typically disabled). Useful for batch-operations
+ * (rendering from Python for e.g.) when an additional save action for is inconvenient.
+ * This is the default behavior for #RE_RenderAnim.
  */
 void RE_RenderFrame(struct Render *re,
                     struct Main *bmain,
@@ -334,7 +338,7 @@ void RE_RenderFrame(struct Render *re,
                     int frame,
                     bool write_still);
 /**
- * Saves images to disk.
+ * A version of #RE_RenderFrame that saves images to disk.
  */
 void RE_RenderAnim(struct Render *re,
                    struct Main *bmain,
diff --git a/source/blender/render/intern/pipeline.c b/source/blender/render/intern/pipeline.c
index 2a93fb2c46b..aa006713755 100644
--- a/source/blender/render/intern/pipeline.c
+++ b/source/blender/render/intern/pipeline.c
@@ -116,14 +116,20 @@
  * - save file or append in movie
  */
 
-/* ********* globals ******** */
+/* -------------------------------------------------------------------- */
+/** \name Globals
+ * \{ */
 
 /* here we store all renders */
 static struct {
   ListBase renderlist;
 } RenderGlobal = {{NULL, NULL}};
 
-/* ********* callbacks ******** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Callbacks
+ * \{ */
 
 static void render_callback_exec_null(Render *re, Main *bmain, eCbEvent evt)
 {
@@ -141,7 +147,11 @@ static void render_callback_exec_id(Render *re, Main *bmain, ID *id, eCbEvent ev
   BKE_callback_exec_id(bmain, id, evt);
 }
 
-/* ********* alloc and free ******** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Allocation & Free
+ * \{ */
 
 static int do_write_image_or_movie(Render *re,
                                    Main *bmain,
@@ -308,7 +318,11 @@ static bool render_scene_has_layers_to_render(Scene *scene, ViewLayer *single_la
   return false;
 }
 
-/* *************************************************** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Public Render API
+ * \{ */
 
 Render *RE_GetRender(const char *name)
 {
@@ -686,7 +700,11 @@ void RE_FreePersistentData(const Scene *scene)
   }
 }
 
-/* ********* initialize state ******** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Initialize State
+ * \{ */
 
 static void re_init_resolution(Render *re, Render *source, int winx, int winy, rcti *disprect)
 {
@@ -905,7 +923,11 @@ void RE_test_break_cb(Render *re, void *handle, int (*f)(void *handle))
   re->tbh = handle;
 }
 
-/* ********* GL Context ******** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name OpenGL Context
+ * \{ */
 
 void RE_gl_context_create(Render *re)
 {
@@ -944,6 +966,16 @@ void *RE_gpu_context_get(Render *re)
   return re->gpu_context;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Render & Composite Scenes (Implementation & Public API)
+ *
+ * Main high-level functions defined here are:
+ * - #RE_RenderFrame
+ * - #RE_RenderAnim
+ * \{ */
+
 /* ************  This part uses API, for rendering Blender scenes ********** */
 
 /* make sure disprect is not affected by the render border */
@@ -1940,6 +1972,12 @@ void RE_RenderFreestyleExternal(Render *re)
 }
 #endif
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Read/Write Render Result (Images & Movies)
+ * \{ */
+
 bool RE_WriteRenderViewsImage(
     ReportList *reports, RenderResult *rr, Scene *scene, const bool stamp, char *name)
 {
@@ -2600,11 +2638,6 @@ bool RE_ReadRenderResult(Scene *scene, Scene *scenode)
   return success;
 }
 
-void RE_init_threadcount(Render *re)
-{
-  re->r.threads = BKE_render_num_threads(&re->r);
-}
-
 void RE_layer_load_from_file(
     RenderLayer *layer, ReportList *reports, const char *filename, int x, int y)
 {
@@ -2785,6 +2818,12 @@ RenderPass *RE_create_gp_pass(RenderResult *rr, const char *layername, const cha
   return render_layer_add_pass(rr, rl, 4, RE_PASSNAME_COMBINED, viewname, "RGBA", true);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Miscellaneous Public Render API
+ * \{ */
+
 bool RE_allow_render_generic_object(Object *ob)
 {
   /* override not showing object when duplis are used with particles */
@@ -2796,3 +2835,10 @@ bool RE_allow_render_generic_object(Object *ob)
   }
   return true;
 }
+
+void RE_init_threadcount(Render *re)
+{
+  re->r.threads = BKE_render_num_threads(&re->r);
+}
+
+/** \} */