From 9f546d690899e05b25a6ef764cc8cf2f5db918b0 Mon Sep 17 00:00:00 2001
From: Campbell Barton <ideasman42@gmail.com>
Date: Thu, 9 Dec 2021 20:01:45 +1100
Subject: Cleanup: move public doc-strings into headers for 'imbuf'

Ref T92709
---
 source/blender/imbuf/intern/IMB_filetype.h         | 107 ++++++++++++++++++---
 source/blender/imbuf/intern/IMB_filter.h           |   3 +
 source/blender/imbuf/intern/allocimbuf.c           |  10 +-
 source/blender/imbuf/intern/bmp.c                  |   1 -
 source/blender/imbuf/intern/cache.c                |   2 -
 source/blender/imbuf/intern/colormanagement.c      |  59 ------------
 .../blender/imbuf/intern/colormanagement_inline.c  |  12 ---
 source/blender/imbuf/intern/dds/BlockDXT.cpp       |  18 ----
 source/blender/imbuf/intern/dds/BlockDXT.h         |  18 ++++
 source/blender/imbuf/intern/dds/ColorBlock.cpp     |   5 -
 source/blender/imbuf/intern/dds/ColorBlock.h       |   5 +
 .../blender/imbuf/intern/dds/DirectDrawSurface.cpp |   2 -
 .../blender/imbuf/intern/dds/DirectDrawSurface.h   |   7 +-
 source/blender/imbuf/intern/dds/FlipDXT.cpp        |   1 -
 source/blender/imbuf/intern/dds/FlipDXT.h          |   6 +-
 source/blender/imbuf/intern/divers.c               |   8 --
 source/blender/imbuf/intern/filter.c               |   8 --
 source/blender/imbuf/intern/imageprocess.c         |   7 --
 source/blender/imbuf/intern/iris.c                 |   6 --
 source/blender/imbuf/intern/moviecache.c           |   1 -
 .../blender/imbuf/intern/openexr/openexr_api.cpp   |  15 ---
 source/blender/imbuf/intern/openexr/openexr_api.h  |   4 +
 .../blender/imbuf/intern/openexr/openexr_multi.h   |  27 +++++-
 source/blender/imbuf/intern/rectop.c               |  35 -------
 source/blender/imbuf/intern/scaling.c              |   7 --
 source/blender/imbuf/intern/stereoimbuf.c          |   2 -
 source/blender/imbuf/intern/thumbs.c               |   3 -
 source/blender/imbuf/intern/tiff.c                 |  24 -----
 source/blender/imbuf/intern/util.c                 |   2 +-
 source/blender/imbuf/intern/util_gpu.c             |   5 -
 30 files changed, 166 insertions(+), 244 deletions(-)

(limited to 'source/blender/imbuf/intern')

diff --git a/source/blender/imbuf/intern/IMB_filetype.h b/source/blender/imbuf/intern/IMB_filetype.h
index c8f6135f330..7a4a2c84df2 100644
--- a/source/blender/imbuf/intern/IMB_filetype.h
+++ b/source/blender/imbuf/intern/IMB_filetype.h
@@ -22,7 +22,9 @@
 
 #include "IMB_imbuf.h"
 
-/* Generic File Type */
+/* -------------------------------------------------------------------- */
+/** \name Generic File Type
+ * \{ */
 
 struct ImBuf;
 
@@ -78,11 +80,19 @@ void imb_tile_cache_init(void);
 void imb_tile_cache_exit(void);
 
 void imb_loadtile(struct ImBuf *ibuf, int tx, int ty, unsigned int *rect);
+/**
+ * External free.
+ */
 void imb_tile_cache_tile_free(struct ImBuf *ibuf, int tx, int ty);
 
+/** \} */
+
 /* Type Specific Functions */
 
-/* png */
+/* -------------------------------------------------------------------- */
+/** \name Format: PNG (#IMB_FTYPE_PNG)
+ * \{ */
+
 bool imb_is_a_png(const unsigned char *mem, const size_t size);
 struct ImBuf *imb_loadpng(const unsigned char *mem,
                           size_t size,
@@ -90,7 +100,12 @@ struct ImBuf *imb_loadpng(const unsigned char *mem,
                           char colorspace[IM_MAX_SPACE]);
 bool imb_savepng(struct ImBuf *ibuf, const char *filepath, int flags);
 
-/* targa */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Format: TARGA (#IMB_FTYPE_TGA)
+ * \{ */
+
 bool imb_is_a_targa(const unsigned char *buf, const size_t size);
 struct ImBuf *imb_loadtarga(const unsigned char *mem,
                             size_t size,
@@ -98,15 +113,28 @@ struct ImBuf *imb_loadtarga(const unsigned char *mem,
                             char colorspace[IM_MAX_SPACE]);
 bool imb_savetarga(struct ImBuf *ibuf, const char *filepath, int flags);
 
-/* iris */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Format: IRIS (#IMB_FTYPE_IMAGIC)
+ * \{ */
+
 bool imb_is_a_iris(const unsigned char *mem, const size_t size);
+/**
+ * Read in a B/W RGB or RGBA iris image file and return an image buffer.
+ */
 struct ImBuf *imb_loadiris(const unsigned char *mem,
                            size_t size,
                            int flags,
                            char colorspace[IM_MAX_SPACE]);
 bool imb_saveiris(struct ImBuf *ibuf, const char *filepath, int flags);
 
-/* jp2 */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Format: JP2 (#IMB_FTYPE_JP2)
+ * \{ */
+
 bool imb_is_a_jp2(const unsigned char *buf, const size_t size);
 struct ImBuf *imb_load_jp2(const unsigned char *mem,
                            size_t size,
@@ -117,7 +145,12 @@ struct ImBuf *imb_load_jp2_filepath(const char *filepath,
                                     char colorspace[IM_MAX_SPACE]);
 bool imb_save_jp2(struct ImBuf *ibuf, const char *filepath, int flags);
 
-/* jpeg */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Format: JPEG (#IMB_FTYPE_JPG)
+ * \{ */
+
 bool imb_is_a_jpeg(const unsigned char *mem, const size_t size);
 bool imb_savejpeg(struct ImBuf *ibuf, const char *filepath, int flags);
 struct ImBuf *imb_load_jpeg(const unsigned char *buffer,
@@ -125,15 +158,26 @@ struct ImBuf *imb_load_jpeg(const unsigned char *buffer,
                             int flags,
                             char colorspace[IM_MAX_SPACE]);
 
-/* bmp */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Format: BMP (#IMB_FTYPE_BMP)
+ * \{ */
+
 bool imb_is_a_bmp(const unsigned char *buf, const size_t size);
 struct ImBuf *imb_bmp_decode(const unsigned char *mem,
                              size_t size,
                              int flags,
                              char colorspace[IM_MAX_SPACE]);
+/* Found write info at http://users.ece.gatech.edu/~slabaugh/personal/c/bitmapUnix.c */
 bool imb_savebmp(struct ImBuf *ibuf, const char *filepath, int flags);
 
-/* cineon */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Format: CINEON (#IMB_FTYPE_CINEON)
+ * \{ */
+
 bool imb_is_a_cineon(const unsigned char *buf, const size_t size);
 bool imb_save_cineon(struct ImBuf *buf, const char *filepath, int flags);
 struct ImBuf *imb_load_cineon(const unsigned char *mem,
@@ -141,7 +185,12 @@ struct ImBuf *imb_load_cineon(const unsigned char *mem,
                               int flags,
                               char colorspace[IM_MAX_SPACE]);
 
-/* dpx */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Format: DPX (#IMB_FTYPE_DPX)
+ * \{ */
+
 bool imb_is_a_dpx(const unsigned char *buf, const size_t size);
 bool imb_save_dpx(struct ImBuf *buf, const char *filepath, int flags);
 struct ImBuf *imb_load_dpx(const unsigned char *mem,
@@ -149,7 +198,12 @@ struct ImBuf *imb_load_dpx(const unsigned char *mem,
                            int flags,
                            char colorspace[IM_MAX_SPACE]);
 
-/* hdr */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Format: HDR (#IMB_FTYPE_RADHDR)
+ * \{ */
+
 bool imb_is_a_hdr(const unsigned char *buf, const size_t size);
 struct ImBuf *imb_loadhdr(const unsigned char *mem,
                           size_t size,
@@ -157,13 +211,44 @@ struct ImBuf *imb_loadhdr(const unsigned char *mem,
                           char colorspace[IM_MAX_SPACE]);
 bool imb_savehdr(struct ImBuf *ibuf, const char *filepath, int flags);
 
-/* tiff */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Format: TIFF (#IMB_FTYPE_TIF)
+ * \{ */
+
 void imb_inittiff(void);
 bool imb_is_a_tiff(const unsigned char *buf, const size_t size);
+/**
+ * Loads a TIFF file.
+ * \param mem: Memory containing the TIFF file.
+ * \param size: Size of the mem buffer.
+ * \param flags: If flags has IB_test set then the file is not actually loaded,
+ * but all other operations take place.
+ *
+ * \return A newly allocated #ImBuf structure if successful, otherwise NULL.
+ */
 struct ImBuf *imb_loadtiff(const unsigned char *mem,
                            size_t size,
                            int flags,
                            char colorspace[IM_MAX_SPACE]);
 void imb_loadtiletiff(
     struct ImBuf *ibuf, const unsigned char *mem, size_t size, int tx, int ty, unsigned int *rect);
+/**
+ * Saves a TIFF file.
+ *
+ * #ImBuf structures with 1, 3 or 4 bytes per pixel (GRAY, RGB, RGBA
+ * respectively) are accepted, and interpreted correctly.  Note that the TIFF
+ * convention is to use pre-multiplied alpha, which can be achieved within
+ * Blender by setting "Premul" alpha handling.  Other alpha conventions are
+ * not strictly correct, but are permitted anyhow.
+ *
+ * \param ibuf: Image buffer.
+ * \param name: Name of the TIFF file to create.
+ * \param flags: Currently largely ignored.
+ *
+ * \return 1 if the function is successful, 0 on failure.
+ */
 bool imb_savetiff(struct ImBuf *ibuf, const char *filepath, int flags);
+
+/** \} */
diff --git a/source/blender/imbuf/intern/IMB_filter.h b/source/blender/imbuf/intern/IMB_filter.h
index 556362d78c1..434750e6736 100644
--- a/source/blender/imbuf/intern/IMB_filter.h
+++ b/source/blender/imbuf/intern/IMB_filter.h
@@ -34,4 +34,7 @@ void IMB_premultiply_rect_float(float *rect_float, int channels, int w, int h);
 void IMB_unpremultiply_rect(unsigned int *rect, char planes, int w, int h);
 void IMB_unpremultiply_rect_float(float *rect_float, int channels, int w, int h);
 
+/**
+ * Result in ibuf2, scaling should be done correctly.
+ */
 void imb_onehalf_no_alloc(struct ImBuf *ibuf2, struct ImBuf *ibuf1);
diff --git a/source/blender/imbuf/intern/allocimbuf.c b/source/blender/imbuf/intern/allocimbuf.c
index 1369f8cc0f8..9bace323372 100644
--- a/source/blender/imbuf/intern/allocimbuf.c
+++ b/source/blender/imbuf/intern/allocimbuf.c
@@ -93,7 +93,6 @@ void imb_freemipmapImBuf(ImBuf *ibuf)
   ibuf->miptot = 0;
 }
 
-/* any free rect frees mipmaps to be sure, creation is in render on first request */
 void imb_freerectfloatImBuf(ImBuf *ibuf)
 {
   if (ibuf == NULL) {
@@ -111,7 +110,6 @@ void imb_freerectfloatImBuf(ImBuf *ibuf)
   ibuf->mall &= ~IB_rectfloat;
 }
 
-/* any free rect frees mipmaps to be sure, creation is in render on first request */
 void imb_freerectImBuf(ImBuf *ibuf)
 {
   if (ibuf == NULL) {
@@ -197,7 +195,6 @@ void IMB_freezbuffloatImBuf(ImBuf *ibuf)
   ibuf->mall &= ~IB_zbuffloat;
 }
 
-/** Free all pixel data (associated with image size). */
 void imb_freerectImbuf_all(ImBuf *ibuf)
 {
   imb_freerectImBuf(ibuf);
@@ -403,9 +400,10 @@ bool imb_addrectfloatImBuf(ImBuf *ibuf)
   return false;
 }
 
-/* question; why also add zbuf? */
 bool imb_addrectImBuf(ImBuf *ibuf)
 {
+  /* Question; why also add ZBUF (when `planes > 32`)? */
+
   if (ibuf == NULL) {
     return false;
   }
@@ -430,9 +428,6 @@ bool imb_addrectImBuf(ImBuf *ibuf)
   return false;
 }
 
-/**
- * \param take_ownership: When true, the buffers become owned by the resulting image.
- */
 struct ImBuf *IMB_allocFromBufferOwn(
     unsigned int *rect, float *rectf, unsigned int w, unsigned int h, unsigned int channels)
 {
@@ -580,7 +575,6 @@ bool IMB_initImBuf(
   return true;
 }
 
-/* does no zbuffers? */
 ImBuf *IMB_dupImBuf(const ImBuf *ibuf1)
 {
   ImBuf *ibuf2, tbuf;
diff --git a/source/blender/imbuf/intern/bmp.c b/source/blender/imbuf/intern/bmp.c
index 5b9d78f5614..b44b12999bf 100644
--- a/source/blender/imbuf/intern/bmp.c
+++ b/source/blender/imbuf/intern/bmp.c
@@ -306,7 +306,6 @@ static int putShortLSB(ushort us, FILE *ofile)
   return putc((us >> 8) & 0xFF, ofile);
 }
 
-/* Found write info at http://users.ece.gatech.edu/~slabaugh/personal/c/bitmapUnix.c */
 bool imb_savebmp(ImBuf *ibuf, const char *filepath, int UNUSED(flags))
 {
   BMPINFOHEADER infoheader;
diff --git a/source/blender/imbuf/intern/cache.c b/source/blender/imbuf/intern/cache.c
index 02d1fe3710a..ce11e1c3f80 100644
--- a/source/blender/imbuf/intern/cache.c
+++ b/source/blender/imbuf/intern/cache.c
@@ -153,7 +153,6 @@ static void imb_global_cache_tile_unload(ImGlobalTile *gtile)
   GLOBAL_CACHE.totmem -= sizeof(unsigned int) * ibuf->tilex * ibuf->tiley;
 }
 
-/* external free */
 void imb_tile_cache_tile_free(ImBuf *ibuf, int tx, int ty)
 {
   ImGlobalTile *gtile, lookuptile;
@@ -248,7 +247,6 @@ void imb_tile_cache_exit(void)
   }
 }
 
-/* presumed to be called when no threads are running */
 void IMB_tile_cache_params(int totthread, int maxmem)
 {
   int a;
diff --git a/source/blender/imbuf/intern/colormanagement.c b/source/blender/imbuf/intern/colormanagement.c
index c8c6f39507f..6e9e5dd3ddb 100644
--- a/source/blender/imbuf/intern/colormanagement.c
+++ b/source/blender/imbuf/intern/colormanagement.c
@@ -1968,7 +1968,6 @@ static void colormanagement_transform_ex(unsigned char *byte_buffer,
   IMB_colormanagement_processor_free(cm_processor);
 }
 
-/* convert the whole buffer from specified by name color space to another */
 void IMB_colormanagement_transform(float *buffer,
                                    int width,
                                    int height,
@@ -1981,9 +1980,6 @@ void IMB_colormanagement_transform(float *buffer,
       NULL, buffer, width, height, channels, from_colorspace, to_colorspace, predivide, false);
 }
 
-/* convert the whole buffer from specified by name color space to another
- * will do threaded conversion
- */
 void IMB_colormanagement_transform_threaded(float *buffer,
                                             int width,
                                             int height,
@@ -1996,7 +1992,6 @@ void IMB_colormanagement_transform_threaded(float *buffer,
       NULL, buffer, width, height, channels, from_colorspace, to_colorspace, predivide, true);
 }
 
-/* Similar to functions above, but operates on byte buffer. */
 void IMB_colormanagement_transform_byte(unsigned char *buffer,
                                         int width,
                                         int height,
@@ -2018,7 +2013,6 @@ void IMB_colormanagement_transform_byte_threaded(unsigned char *buffer,
       buffer, NULL, width, height, channels, from_colorspace, to_colorspace, false, true);
 }
 
-/* Similar to above, but gets float buffer from display one. */
 void IMB_colormanagement_transform_from_byte(float *float_buffer,
                                              unsigned char *byte_buffer,
                                              int width,
@@ -2098,9 +2092,6 @@ void IMB_colormanagement_transform_v4(float pixel[4],
   IMB_colormanagement_processor_free(cm_processor);
 }
 
-/* convert pixel from specified by descriptor color space to scene linear
- * used by performance-critical areas such as renderer and baker
- */
 void IMB_colormanagement_colorspace_to_scene_linear_v3(float pixel[3], ColorSpace *colorspace)
 {
   OCIO_ConstCPUProcessorRcPtr *processor;
@@ -2118,7 +2109,6 @@ void IMB_colormanagement_colorspace_to_scene_linear_v3(float pixel[3], ColorSpac
   }
 }
 
-/* same as above, but converts colors in opposite direction */
 void IMB_colormanagement_scene_linear_to_colorspace_v3(float pixel[3], ColorSpace *colorspace)
 {
   OCIO_ConstCPUProcessorRcPtr *processor;
@@ -2315,14 +2305,6 @@ void IMB_colormanagement_imbuf_to_float_texture(float *out_buffer,
   }
 }
 
-/* Conversion between color picking role. Typically we would expect such a
- * requirements:
- * - It is approximately perceptually linear, so that the HSV numbers and
- *   the HSV cube/circle have an intuitive distribution.
- * - It has the same gamut as the scene linear color space.
- * - Color picking values 0..1 map to scene linear values in the 0..1 range,
- *   so that picked albedo values are energy conserving.
- */
 void IMB_colormanagement_scene_linear_to_color_picking_v3(float pixel[3])
 {
   if (!global_color_picking_state.cpu_processor_to && !global_color_picking_state.failed) {
@@ -2377,8 +2359,6 @@ void IMB_colormanagement_color_picking_to_scene_linear_v3(float pixel[3])
   }
 }
 
-/* Conversion between sRGB, for rare cases like hex color or copy/pasting
- * between UI theme and scene linear colors. */
 void IMB_colormanagement_scene_linear_to_srgb_v3(float pixel[3])
 {
   mul_m3_v3(imbuf_rgb_to_xyz, pixel);
@@ -2393,10 +2373,6 @@ void IMB_colormanagement_srgb_to_scene_linear_v3(float pixel[3])
   mul_m3_v3(imbuf_xyz_to_rgb, pixel);
 }
 
-/* convert pixel from scene linear to display space using default view
- * used by performance-critical areas such as color-related widgets where we want to reduce
- * amount of per-widget allocations
- */
 void IMB_colormanagement_scene_linear_to_display_v3(float pixel[3], ColorManagedDisplay *display)
 {
   OCIO_ConstCPUProcessorRcPtr *processor = display_from_scene_linear_processor(display);
@@ -2406,7 +2382,6 @@ void IMB_colormanagement_scene_linear_to_display_v3(float pixel[3], ColorManaged
   }
 }
 
-/* same as above, but converts color in opposite direction */
 void IMB_colormanagement_display_to_scene_linear_v3(float pixel[3], ColorManagedDisplay *display)
 {
   OCIO_ConstCPUProcessorRcPtr *processor = display_to_scene_linear_processor(display);
@@ -2468,17 +2443,6 @@ void IMB_colormanagement_imbuf_make_display_space(
   colormanagement_imbuf_make_display_space(ibuf, view_settings, display_settings, false);
 }
 
-/* prepare image buffer to be saved on disk, applying color management if needed
- * color management would be applied if image is saving as render result and if
- * file format is not expecting float buffer to be in linear space (currently
- * JPEG2000 and TIFF are such formats -- they're storing image as float but
- * file itself stores applied color space).
- *
- * Both byte and float buffers would contain applied color space, and result's
- * float_colorspace would be set to display color space. This should be checked
- * in image format write callback and if float_colorspace is not NULL, no color
- * space transformation should be applied on this buffer.
- */
 ImBuf *IMB_colormanagement_imbuf_for_write(ImBuf *ibuf,
                                            bool save_as_render,
                                            bool allocate_result,
@@ -2640,7 +2604,6 @@ void IMB_colormanagement_buffer_make_display_space(
 /** \name Public Display Buffers Interfaces
  * \{ */
 
-/* acquire display buffer for given image buffer using specified view and display settings */
 unsigned char *IMB_display_buffer_acquire(ImBuf *ibuf,
                                           const ColorManagedViewSettings *view_settings,
                                           const ColorManagedDisplaySettings *display_settings,
@@ -2738,7 +2701,6 @@ unsigned char *IMB_display_buffer_acquire(ImBuf *ibuf,
   return display_buffer;
 }
 
-/* same as IMB_display_buffer_acquire but gets view and display settings from context */
 unsigned char *IMB_display_buffer_acquire_ctx(const bContext *C, ImBuf *ibuf, void **cache_handle)
 {
   ColorManagedViewSettings *view_settings;
@@ -2899,7 +2861,6 @@ const char *IMB_colormanagement_display_get_default_name(void)
   return display->name;
 }
 
-/* used by performance-critical pixel processing areas, such as color widgets */
 ColorManagedDisplay *IMB_colormanagement_display_get_named(const char *name)
 {
   return colormanage_display_get_named(name);
@@ -4027,19 +3988,6 @@ bool IMB_colormanagement_support_glsl_draw(const ColorManagedViewSettings *UNUSE
   return OCIO_supportGPUShader();
 }
 
-/**
- * Configures GLSL shader for conversion from specified to
- * display color space
- *
- * Will create appropriate OCIO processor and setup GLSL shader,
- * so further 2D texture usage will use this conversion.
- *
- * When there's no need to apply transform on 2D textures, use
- * IMB_colormanagement_finish_glsl_draw().
- *
- * This is low-level function, use ED_draw_imbuf_ctx if you
- * only need to display given image buffer
- */
 bool IMB_colormanagement_setup_glsl_draw_from_space(
     const ColorManagedViewSettings *view_settings,
     const ColorManagedDisplaySettings *display_settings,
@@ -4097,7 +4045,6 @@ bool IMB_colormanagement_setup_glsl_draw_from_space(
   return global_gpu_state.gpu_shader_bound;
 }
 
-/* Configures GLSL shader for conversion from scene linear to display space */
 bool IMB_colormanagement_setup_glsl_draw(const ColorManagedViewSettings *view_settings,
                                          const ColorManagedDisplaySettings *display_settings,
                                          float dither,
@@ -4107,10 +4054,6 @@ bool IMB_colormanagement_setup_glsl_draw(const ColorManagedViewSettings *view_se
       view_settings, display_settings, NULL, dither, predivide, false);
 }
 
-/**
- * Same as setup_glsl_draw_from_space,
- * but color management settings are guessing from a given context.
- */
 bool IMB_colormanagement_setup_glsl_draw_from_space_ctx(const bContext *C,
                                                         struct ColorSpace *from_colorspace,
                                                         float dither,
@@ -4125,13 +4068,11 @@ bool IMB_colormanagement_setup_glsl_draw_from_space_ctx(const bContext *C,
       view_settings, display_settings, from_colorspace, dither, predivide, false);
 }
 
-/* Same as setup_glsl_draw, but color management settings are guessing from a given context */
 bool IMB_colormanagement_setup_glsl_draw_ctx(const bContext *C, float dither, bool predivide)
 {
   return IMB_colormanagement_setup_glsl_draw_from_space_ctx(C, NULL, dither, predivide);
 }
 
-/* Finish GLSL-based display space conversion */
 void IMB_colormanagement_finish_glsl_draw(void)
 {
   if (global_gpu_state.gpu_shader_bound) {
diff --git a/source/blender/imbuf/intern/colormanagement_inline.c b/source/blender/imbuf/intern/colormanagement_inline.c
index c304ad8d8e5..6e57a8cc1b2 100644
--- a/source/blender/imbuf/intern/colormanagement_inline.c
+++ b/source/blender/imbuf/intern/colormanagement_inline.c
@@ -27,23 +27,11 @@
 #include "BLI_math_vector.h"
 #include "IMB_colormanagement_intern.h"
 
-/* Convert a float RGB triplet to the correct luminance weighted average.
- *
- * Grayscale, or Luma is a distillation of RGB data values down to a weighted average
- * based on the luminance positions of the red, green, and blue primaries.
- * Given that the internal reference space may be arbitrarily set, any
- * effort to glean the luminance coefficients must be aware of the reference
- * space primaries.
- *
- * See http://wiki.blender.org/index.php/User:Nazg-gul/ColorManagement#Luminance
- */
-
 float IMB_colormanagement_get_luminance(const float rgb[3])
 {
   return dot_v3v3(imbuf_luma_coefficients, rgb);
 }
 
-/* Byte equivalent of IMB_colormanagement_get_luminance(). */
 unsigned char IMB_colormanagement_get_luminance_byte(const unsigned char rgb[3])
 {
   float rgbf[3];
diff --git a/source/blender/imbuf/intern/dds/BlockDXT.cpp b/source/blender/imbuf/intern/dds/BlockDXT.cpp
index 4e4fca864a0..e471b6834ae 100644
--- a/source/blender/imbuf/intern/dds/BlockDXT.cpp
+++ b/source/blender/imbuf/intern/dds/BlockDXT.cpp
@@ -158,7 +158,6 @@ uint BlockDXT1::evaluatePaletteNV5x(Color32 color_array[4]) const
   return 3;
 }
 
-/* Evaluate palette assuming 3 color block. */
 void BlockDXT1::evaluatePalette3(Color32 color_array[4]) const
 {
   color_array[0].b = (col0.b << 3) | (col0.b >> 2);
@@ -184,7 +183,6 @@ void BlockDXT1::evaluatePalette3(Color32 color_array[4]) const
   color_array[3].a = 0x00;
 }
 
-/* Evaluate palette assuming 4 color block. */
 void BlockDXT1::evaluatePalette4(Color32 color_array[4]) const
 {
   color_array[0].b = (col0.b << 3) | (col0.b >> 2);
@@ -247,14 +245,12 @@ void BlockDXT1::setIndices(const int *idx)
   }
 }
 
-/** Flip DXT1 block vertically. */
 inline void BlockDXT1::flip4()
 {
   swap(row[0], row[3]);
   swap(row[1], row[2]);
 }
 
-/** Flip half DXT1 block vertically. */
 inline void BlockDXT1::flip2()
 {
   swap(row[0], row[1]);
@@ -299,27 +295,23 @@ void AlphaBlockDXT3::decodeBlock(ColorBlock *block) const
   block->color(0xF).a = (alphaF << 4) | alphaF;
 }
 
-/** Flip DXT3 alpha block vertically. */
 void AlphaBlockDXT3::flip4()
 {
   swap(row[0], row[3]);
   swap(row[1], row[2]);
 }
 
-/** Flip half DXT3 alpha block vertically. */
 void AlphaBlockDXT3::flip2()
 {
   swap(row[0], row[1]);
 }
 
-/** Flip DXT3 block vertically. */
 void BlockDXT3::flip4()
 {
   alpha.flip4();
   color.flip4();
 }
 
-/** Flip half DXT3 block vertically. */
 void BlockDXT3::flip2()
 {
   alpha.flip2();
@@ -458,21 +450,18 @@ void BlockDXT5::decodeBlockNV5x(ColorBlock *block) const
   alpha.decodeBlock(block);
 }
 
-/** Flip DXT5 block vertically. */
 void BlockDXT5::flip4()
 {
   alpha.flip4();
   color.flip4();
 }
 
-/** Flip half DXT5 block vertically. */
 void BlockDXT5::flip2()
 {
   alpha.flip2();
   color.flip2();
 }
 
-/** Decode ATI1 block. */
 void BlockATI1::decodeBlock(ColorBlock *block) const
 {
   uint8 alpha_array[8];
@@ -488,19 +477,16 @@ void BlockATI1::decodeBlock(ColorBlock *block) const
   }
 }
 
-/** Flip ATI1 block vertically. */
 void BlockATI1::flip4()
 {
   alpha.flip4();
 }
 
-/** Flip half ATI1 block vertically. */
 void BlockATI1::flip2()
 {
   alpha.flip2();
 }
 
-/** Decode ATI2 block. */
 void BlockATI2::decodeBlock(ColorBlock *block) const
 {
   uint8 alpha_array[8];
@@ -525,14 +511,12 @@ void BlockATI2::decodeBlock(ColorBlock *block) const
   }
 }
 
-/** Flip ATI2 block vertically. */
 void BlockATI2::flip4()
 {
   x.flip4();
   y.flip4();
 }
 
-/** Flip half ATI2 block vertically. */
 void BlockATI2::flip2()
 {
   x.flip2();
@@ -586,14 +570,12 @@ void BlockCTX1::setIndices(const int *idx)
   }
 }
 
-/** Flip CTX1 block vertically. */
 inline void BlockCTX1::flip4()
 {
   swap(row[0], row[3]);
   swap(row[1], row[2]);
 }
 
-/** Flip half CTX1 block vertically. */
 inline void BlockCTX1::flip2()
 {
   swap(row[0], row[1]);
diff --git a/source/blender/imbuf/intern/dds/BlockDXT.h b/source/blender/imbuf/intern/dds/BlockDXT.h
index 1fefa7c739d..eb2d5f8726c 100644
--- a/source/blender/imbuf/intern/dds/BlockDXT.h
+++ b/source/blender/imbuf/intern/dds/BlockDXT.h
@@ -69,7 +69,9 @@ struct BlockDXT1 {
   uint evaluatePalette(Color32 color_array[4]) const;
   uint evaluatePaletteNV5x(Color32 color_array[4]) const;
 
+  /** Evaluate palette assuming 3 color block. */
   void evaluatePalette3(Color32 color_array[4]) const;
+  /** Evaluate palette assuming 4 color block. */
   void evaluatePalette4(Color32 color_array[4]) const;
 
   void decodeBlock(ColorBlock *block) const;
@@ -77,7 +79,9 @@ struct BlockDXT1 {
 
   void setIndices(const int *idx);
 
+  /** Flip DXT1 block vertically. */
   void flip4();
+  /** Flip half DXT1 block vertically. */
   void flip2();
 };
 
@@ -113,7 +117,9 @@ struct AlphaBlockDXT3 {
 
   void decodeBlock(ColorBlock *block) const;
 
+  /** Flip DXT3 alpha block vertically. */
   void flip4();
+  /** Flip half DXT3 alpha block vertically. */
   void flip2();
 };
 
@@ -125,7 +131,9 @@ struct BlockDXT3 {
   void decodeBlock(ColorBlock *block) const;
   void decodeBlockNV5x(ColorBlock *block) const;
 
+  /** Flip DXT3 block vertically. */
   void flip4();
+  /** Flip half DXT3 block vertically. */
   void flip2();
 };
 
@@ -253,7 +261,9 @@ struct BlockDXT5 {
   void decodeBlock(ColorBlock *block) const;
   void decodeBlockNV5x(ColorBlock *block) const;
 
+  /** Flip DXT5 block vertically. */
   void flip4();
+  /** Flip half DXT5 block vertically. */
   void flip2();
 };
 
@@ -261,9 +271,12 @@ struct BlockDXT5 {
 struct BlockATI1 {
   AlphaBlockDXT5 alpha;
 
+  /** Decode ATI1 block. */
   void decodeBlock(ColorBlock *block) const;
 
+  /** Flip ATI1 block vertically. */
   void flip4();
+  /** Flip half ATI1 block vertically. */
   void flip2();
 };
 
@@ -272,9 +285,12 @@ struct BlockATI2 {
   AlphaBlockDXT5 x;
   AlphaBlockDXT5 y;
 
+  /** Decode ATI2 block. */
   void decodeBlock(ColorBlock *block) const;
 
+  /** Flip ATI2 block vertically. */
   void flip4();
+  /** Flip half ATI2 block vertically. */
   void flip2();
 };
 
@@ -292,7 +308,9 @@ struct BlockCTX1 {
 
   void decodeBlock(ColorBlock *block) const;
 
+  /** Flip CTX1 block vertically. */
   void flip4();
+  /** Flip half CTX1 block vertically. */
   void flip2();
 };
 
diff --git a/source/blender/imbuf/intern/dds/ColorBlock.cpp b/source/blender/imbuf/intern/dds/ColorBlock.cpp
index 6974e0bf99d..0ab98c01f6f 100644
--- a/source/blender/imbuf/intern/dds/ColorBlock.cpp
+++ b/source/blender/imbuf/intern/dds/ColorBlock.cpp
@@ -46,7 +46,6 @@ inline static uint colorDistance(Color32 c0, Color32 c1)
 }
 #endif
 
-/** Init the color block from an array of colors. */
 ColorBlock::ColorBlock(const uint *linearImage)
 {
   for (uint i = 0; i < 16; i++) {
@@ -54,7 +53,6 @@ ColorBlock::ColorBlock(const uint *linearImage)
   }
 }
 
-/** Init the color block with the contents of the given block. */
 ColorBlock::ColorBlock(const ColorBlock &block)
 {
   for (uint i = 0; i < 16; i++) {
@@ -62,7 +60,6 @@ ColorBlock::ColorBlock(const ColorBlock &block)
   }
 }
 
-/** Initialize this color block. */
 ColorBlock::ColorBlock(const Image *img, uint x, uint y)
 {
   init(img, x, y);
@@ -153,7 +150,6 @@ void ColorBlock::swizzle(uint x, uint y, uint z, uint w)
   }
 }
 
-/** Returns true if the block has a single color. */
 bool ColorBlock::isSingleColor(Color32 mask /*= Color32(0xFF, 0xFF, 0xFF, 0x00) */) const
 {
   uint u = m_color[0].u & mask.u;
@@ -234,7 +230,6 @@ Color32 ColorBlock::averageColor() const
 }
 #endif
 
-/** Return true if the block is not fully opaque. */
 bool ColorBlock::hasAlpha() const
 {
   for (const auto &i : m_color) {
diff --git a/source/blender/imbuf/intern/dds/ColorBlock.h b/source/blender/imbuf/intern/dds/ColorBlock.h
index 934837bb129..1dee5c76c9e 100644
--- a/source/blender/imbuf/intern/dds/ColorBlock.h
+++ b/source/blender/imbuf/intern/dds/ColorBlock.h
@@ -35,8 +35,11 @@
 /** Uncompressed 4x4 color block. */
 struct ColorBlock {
   ColorBlock() = default;
+  /** Init the color block from an array of colors. */
   ColorBlock(const uint *linearImage);
+  /** Init the color block with the contents of the given block. */
   ColorBlock(const ColorBlock &block);
+  /** Initialize this color block. */
   ColorBlock(const Image *img, uint x, uint y);
 
   void init(const Image *img, uint x, uint y);
@@ -45,7 +48,9 @@ struct ColorBlock {
 
   void swizzle(uint x, uint y, uint z, uint w); /* 0=r, 1=g, 2=b, 3=a, 4=0xFF, 5=0 */
 
+  /** Returns true if the block has a single color. */
   bool isSingleColor(Color32 mask = Color32(0xFF, 0xFF, 0xFF, 0x00)) const;
+  /** Return true if the block is not fully opaque. */
   bool hasAlpha() const;
 
   /* Accessors */
diff --git a/source/blender/imbuf/intern/dds/DirectDrawSurface.cpp b/source/blender/imbuf/intern/dds/DirectDrawSurface.cpp
index b665996b18f..efa438c2af5 100644
--- a/source/blender/imbuf/intern/dds/DirectDrawSurface.cpp
+++ b/source/blender/imbuf/intern/dds/DirectDrawSurface.cpp
@@ -1107,8 +1107,6 @@ void DirectDrawSurface::mipmap(Image *img, uint face, uint mipmap)
   }
 }
 
-/* It was easier to copy this function from upstream than to resync.
- * This should be removed if a resync ever occurs. */
 void *DirectDrawSurface::readData(uint &rsize)
 {
   uint header_size = 128;  // sizeof(DDSHeader);
diff --git a/source/blender/imbuf/intern/dds/DirectDrawSurface.h b/source/blender/imbuf/intern/dds/DirectDrawSurface.h
index 381fa51f75c..343a7367f91 100644
--- a/source/blender/imbuf/intern/dds/DirectDrawSurface.h
+++ b/source/blender/imbuf/intern/dds/DirectDrawSurface.h
@@ -157,6 +157,10 @@ class DirectDrawSurface {
   void setUserVersion(int version);
 
   void mipmap(Image *img, uint f, uint m);
+  /**
+   * It was easier to copy this function from upstream than to resync.
+   * This should be removed if a resync ever occurs.
+   */
   void *readData(uint &size);
   //  void mipmap(FloatImage *img, uint f, uint m);
 
@@ -174,7 +178,8 @@ class DirectDrawSurface {
   void readBlock(ColorBlock *rgba);
 
  private:
-  Stream stream; /* Memory where DDS file resides. */
+  /** Memory where DDS file resides. */
+  Stream stream;
   DDSHeader header;
 };
 
diff --git a/source/blender/imbuf/intern/dds/FlipDXT.cpp b/source/blender/imbuf/intern/dds/FlipDXT.cpp
index 2acf072556a..359d6f30cdc 100644
--- a/source/blender/imbuf/intern/dds/FlipDXT.cpp
+++ b/source/blender/imbuf/intern/dds/FlipDXT.cpp
@@ -168,7 +168,6 @@ static void FlipDXT5BlockHalf(uint8_t *block)
   FlipDXT1BlockHalf(block + 8);
 }
 
-/* Flips a DXTC image, by flipping and swapping DXTC blocks as appropriate. */
 int FlipDXTCImage(
     unsigned int width, unsigned int height, unsigned int levels, int fourcc, uint8_t *data)
 {
diff --git a/source/blender/imbuf/intern/dds/FlipDXT.h b/source/blender/imbuf/intern/dds/FlipDXT.h
index d35157251bd..b4f71e4eca7 100644
--- a/source/blender/imbuf/intern/dds/FlipDXT.h
+++ b/source/blender/imbuf/intern/dds/FlipDXT.h
@@ -18,6 +18,10 @@
 
 #include "BLI_sys_types.h"
 
-/* flip compressed DXT image vertically to fit OpenGL convention */
+/**
+ * Flips a DXTC image, by flipping and swapping DXTC blocks as appropriate.
+ *
+ * Use to flip vertically to fit OpenGL convention.
+ */
 int FlipDXTCImage(
     unsigned int width, unsigned int height, unsigned int levels, int fourcc, uint8_t *data);
diff --git a/source/blender/imbuf/intern/divers.c b/source/blender/imbuf/intern/divers.c
index e6f42da1597..1d0839b502b 100644
--- a/source/blender/imbuf/intern/divers.c
+++ b/source/blender/imbuf/intern/divers.c
@@ -102,13 +102,11 @@ MINLINE void float_to_byte_dither_v4(
   b[3] = unit_float_to_uchar_clamp(f[3]);
 }
 
-/* Test if colorspace conversions of pixels in buffer need to take into account alpha. */
 bool IMB_alpha_affects_rgb(const ImBuf *ibuf)
 {
   return (ibuf->flags & IB_alphamode_channel_packed) == 0;
 }
 
-/* float to byte pixels, output 4-channel RGBA */
 void IMB_buffer_byte_from_float(uchar *rect_to,
                                 const float *rect_from,
                                 int channels_from,
@@ -275,7 +273,6 @@ void IMB_buffer_byte_from_float(uchar *rect_to,
   }
 }
 
-/* float to byte pixels, output 4-channel RGBA */
 void IMB_buffer_byte_from_float_mask(uchar *rect_to,
                                      const float *rect_from,
                                      int channels_from,
@@ -366,7 +363,6 @@ void IMB_buffer_byte_from_float_mask(uchar *rect_to,
   }
 }
 
-/* Byte to float pixels, input and output 4-channel RGBA. */
 void IMB_buffer_float_from_byte(float *rect_to,
                                 const uchar *rect_from,
                                 int profile_to,
@@ -426,7 +422,6 @@ void IMB_buffer_float_from_byte(float *rect_to,
   }
 }
 
-/* float to float pixels, output 4-channel RGBA */
 void IMB_buffer_float_from_float(float *rect_to,
                                  const float *rect_from,
                                  int channels_from,
@@ -592,7 +587,6 @@ void IMB_buffer_float_from_float_threaded(float *rect_to,
   }
 }
 
-/* float to float pixels, output 4-channel RGBA */
 void IMB_buffer_float_from_float_mask(float *rect_to,
                                       const float *rect_from,
                                       int channels_from,
@@ -646,7 +640,6 @@ void IMB_buffer_float_from_float_mask(float *rect_to,
   }
 }
 
-/* byte to byte pixels, input and output 4-channel RGBA */
 void IMB_buffer_byte_from_byte(uchar *rect_to,
                                const uchar *rect_from,
                                int profile_to,
@@ -837,7 +830,6 @@ void IMB_float_from_rect(ImBuf *ibuf)
 /** \name Color to Grayscale
  * \{ */
 
-/* no profile conversion */
 void IMB_color_to_bw(ImBuf *ibuf)
 {
   float *rct_fl = ibuf->rect_float;
diff --git a/source/blender/imbuf/intern/filter.c b/source/blender/imbuf/intern/filter.c
index 97d44af1315..324bc9806c1 100644
--- a/source/blender/imbuf/intern/filter.c
+++ b/source/blender/imbuf/intern/filter.c
@@ -420,12 +420,6 @@ static int check_pixel_assigned(
   return res;
 }
 
-/**
- * if alpha is zero, it checks surrounding pixels and averages color. sets new alphas to 1.0
- * When a mask is given, the mask will be used instead of the alpha channel, where only
- * pixels with a mask value of 0 will be written to, and only pixels with a mask value of 1
- * will be used for the average. The mask will be set to one for the pixels which were written.
- */
 void IMB_filter_extend(struct ImBuf *ibuf, char *mask, int filter)
 {
   const int width = ibuf->x;
@@ -557,7 +551,6 @@ void IMB_filter_extend(struct ImBuf *ibuf, char *mask, int filter)
   }
 }
 
-/* threadsafe version, only recreates existing maps */
 void IMB_remakemipmap(ImBuf *ibuf, int use_filter)
 {
   ImBuf *hbuf = ibuf;
@@ -594,7 +587,6 @@ void IMB_remakemipmap(ImBuf *ibuf, int use_filter)
   }
 }
 
-/* frees too (if there) and recreates new data */
 void IMB_makemipmap(ImBuf *ibuf, int use_filter)
 {
   ImBuf *hbuf = ibuf;
diff --git a/source/blender/imbuf/intern/imageprocess.c b/source/blender/imbuf/intern/imageprocess.c
index 75d36e10498..450067f6c6c 100644
--- a/source/blender/imbuf/intern/imageprocess.c
+++ b/source/blender/imbuf/intern/imageprocess.c
@@ -40,7 +40,6 @@
 #include "IMB_imbuf_types.h"
 #include <math.h>
 
-/* Only this one is used liberally here, and in imbuf */
 void IMB_convert_rgba_to_abgr(struct ImBuf *ibuf)
 {
   size_t size;
@@ -157,10 +156,6 @@ void bilinear_interpolation_color(
 /* function assumes out to be zero'ed, only does RGBA */
 /* BILINEAR INTERPOLATION */
 
-/* Note about wrapping, the u/v still needs to be within the image bounds,
- * just the interpolation is wrapped.
- * This the same as bilinear_interpolation_color except it wraps
- * rather than using empty and emptyI. */
 void bilinear_interpolation_color_wrap(
     const struct ImBuf *in, unsigned char outI[4], float outF[4], float u, float v)
 {
@@ -254,7 +249,6 @@ void bilinear_interpolation(const ImBuf *in, ImBuf *out, float u, float v, int x
 /** \name Nearest Interpolation
  * \{ */
 
-/* functions assumes out to be zero'ed, only does RGBA */
 void nearest_interpolation_color_char(
     const struct ImBuf *in, unsigned char outI[4], float UNUSED(outF[4]), float u, float v)
 {
@@ -502,7 +496,6 @@ void IMB_alpha_under_color_byte(unsigned char *rect, int x, int y, const float b
 /** \name Sample Pixel
  * \{ */
 
-/* Sample pixel of image using NEAREST method. */
 void IMB_sampleImageAtLocation(ImBuf *ibuf, float x, float y, bool make_linear_rgb, float color[4])
 {
   if (ibuf->rect_float) {
diff --git a/source/blender/imbuf/intern/iris.c b/source/blender/imbuf/intern/iris.c
index 6a7ad87d53d..dc714e6e85a 100644
--- a/source/blender/imbuf/intern/iris.c
+++ b/source/blender/imbuf/intern/iris.c
@@ -251,12 +251,6 @@ bool imb_is_a_iris(const uchar *mem, size_t size)
   return ((GS(mem) == IMAGIC) || (GSS(mem) == IMAGIC));
 }
 
-/*
- * longimagedata -
- * read in a B/W RGB or RGBA iris image file and return a
- * pointer to an array of ints.
- */
-
 struct ImBuf *imb_loadiris(const uchar *mem, size_t size, int flags, char colorspace[IM_MAX_SPACE])
 {
   uint *base, *lptr = NULL;
diff --git a/source/blender/imbuf/intern/moviecache.c b/source/blender/imbuf/intern/moviecache.c
index 773a3486233..f290ab1a060 100644
--- a/source/blender/imbuf/intern/moviecache.c
+++ b/source/blender/imbuf/intern/moviecache.c
@@ -496,7 +496,6 @@ void IMB_moviecache_cleanup(MovieCache *cache,
   }
 }
 
-/* get segments of cached frames. useful for debugging cache policies */
 void IMB_moviecache_get_cache_segments(
     MovieCache *cache, int proxy, int render_flags, int *r_totseg, int **r_points)
 {
diff --git a/source/blender/imbuf/intern/openexr/openexr_api.cpp b/source/blender/imbuf/intern/openexr/openexr_api.cpp
index adf09f8dda8..568bd48d863 100644
--- a/source/blender/imbuf/intern/openexr/openexr_api.cpp
+++ b/source/blender/imbuf/intern/openexr/openexr_api.cpp
@@ -327,10 +327,6 @@ static half float_to_half_safe(const float value)
 
 extern "C" {
 
-/**
- * Test presence of OpenEXR file.
- * \param mem: pointer to loaded OpenEXR bitstream
- */
 bool imb_is_a_openexr(const unsigned char *mem, const size_t size)
 {
   /* No define is exposed for this size. */
@@ -781,9 +777,6 @@ static void imb_exr_insert_view_name(char *name_full, const char *passname, cons
   }
 }
 
-/* adds flattened ExrChannels */
-/* xstride, ystride and rect can be done in set_channel too, for tile writing */
-/* passname does not include view */
 void IMB_exr_add_channel(void *handle,
                          const char *layname,
                          const char *passname,
@@ -840,7 +833,6 @@ void IMB_exr_add_channel(void *handle,
   BLI_addtail(&data->channels, echan);
 }
 
-/* used for output files (from RenderResult) (single and multilayer, single and multiview) */
 bool IMB_exr_begin_write(void *handle,
                          const char *filename,
                          int width,
@@ -896,8 +888,6 @@ bool IMB_exr_begin_write(void *handle,
   return (data->ofile != nullptr);
 }
 
-/* only used for writing temp. render results (not image files)
- * (FSA and Save Buffers) */
 void IMB_exrtile_begin_write(
     void *handle, const char *filename, int mipmap, int width, int height, int tilex, int tiley)
 {
@@ -963,7 +953,6 @@ void IMB_exrtile_begin_write(
   }
 }
 
-/* read from file */
 bool IMB_exr_begin_read(
     void *handle, const char *filename, int *width, int *height, const bool parse_channels)
 {
@@ -1024,8 +1013,6 @@ bool IMB_exr_begin_read(
   return true;
 }
 
-/* still clumsy name handling, layers/channels can be ordered as list in list later */
-/* passname here is the raw channel name without the layer */
 void IMB_exr_set_channel(
     void *handle, const char *layname, const char *passname, int xstride, int ystride, float *rect)
 {
@@ -1167,8 +1154,6 @@ void IMB_exr_write_channels(void *handle)
   }
 }
 
-/* temporary function, used for FSA and Save Buffers */
-/* called once per tile * view */
 void IMB_exrtile_write_channels(
     void *handle, int partx, int party, int level, const char *viewname, bool empty)
 {
diff --git a/source/blender/imbuf/intern/openexr/openexr_api.h b/source/blender/imbuf/intern/openexr/openexr_api.h
index 940715690a7..2636bb0d820 100644
--- a/source/blender/imbuf/intern/openexr/openexr_api.h
+++ b/source/blender/imbuf/intern/openexr/openexr_api.h
@@ -32,6 +32,10 @@ extern "C" {
 void imb_initopenexr(void);
 void imb_exitopenexr(void);
 
+/**
+ * Test presence of OpenEXR file.
+ * \param mem: pointer to loaded OpenEXR bitstream
+ */
 bool imb_is_a_openexr(const unsigned char *mem, const size_t size);
 
 bool imb_save_openexr(struct ImBuf *ibuf, const char *name, int flags);
diff --git a/source/blender/imbuf/intern/openexr/openexr_multi.h b/source/blender/imbuf/intern/openexr/openexr_multi.h
index 82a5d161ded..7fb48a92bfd 100644
--- a/source/blender/imbuf/intern/openexr/openexr_multi.h
+++ b/source/blender/imbuf/intern/openexr/openexr_multi.h
@@ -23,7 +23,7 @@
 
 #pragma once
 
-/* experiment with more advanced exr api */
+/* Experiment with more advanced EXR API. */
 
 /* XXX layer+pass name max 64? */
 /* This api also supports max 8 channels per pass now. easy to fix! */
@@ -41,6 +41,12 @@ struct StampData;
 
 void *IMB_exr_get_handle(void);
 void *IMB_exr_get_handle_name(const char *name);
+
+/**
+ * Adds flattened #ExrChannel's
+ * `xstride`, `ystride` and `rect` can be done in set_channel too, for tile writing.
+ * \param passname does not include view.
+ */
 void IMB_exr_add_channel(void *handle,
                          const char *layname,
                          const char *passname,
@@ -50,17 +56,32 @@ void IMB_exr_add_channel(void *handle,
                          float *rect,
                          bool use_half_float);
 
+/**
+ * Read from file.
+ */
 bool IMB_exr_begin_read(
     void *handle, const char *filename, int *width, int *height, const bool parse_channels);
+/**
+ * Used for output files (from #RenderResult) (single and multi-layer, single and multi-view).
+ */
 bool IMB_exr_begin_write(void *handle,
                          const char *filename,
                          int width,
                          int height,
                          int compress,
                          const struct StampData *stamp);
+/**
+ * Only used for writing temp. render results (not image files)
+ * (FSA and Save Buffers).
+ */
 void IMB_exrtile_begin_write(
     void *handle, const char *filename, int mipmap, int width, int height, int tilex, int tiley);
 
+/**
+ * Still clumsy name handling, layers/channels can be ordered as list in list later.
+ *
+ * \param passname here is the raw channel name without the layer.
+ */
 void IMB_exr_set_channel(void *handle,
                          const char *layname,
                          const char *passname,
@@ -74,6 +95,10 @@ float *IMB_exr_channel_rect(void *handle,
 
 void IMB_exr_read_channels(void *handle);
 void IMB_exr_write_channels(void *handle);
+/**
+ * Temporary function, used for FSA and Save Buffers.
+ * called once per `tile * view`.
+ */
 void IMB_exrtile_write_channels(
     void *handle, int partx, int party, int level, const char *viewname, bool empty);
 void IMB_exr_clear_channels(void *handle);
diff --git a/source/blender/imbuf/intern/rectop.c b/source/blender/imbuf/intern/rectop.c
index 4b5d68b9c13..1d81ee768e9 100644
--- a/source/blender/imbuf/intern/rectop.c
+++ b/source/blender/imbuf/intern/rectop.c
@@ -251,9 +251,6 @@ static void rect_crop_16bytes(void **buf_p, const int size_src[2], const rcti *c
   *buf_p = (void *)MEM_reallocN(*buf_p, sizeof(uint[4]) * size_dst[0] * size_dst[1]);
 }
 
-/**
- * In-place image crop.
- */
 void IMB_rect_crop(ImBuf *ibuf, const rcti *crop)
 {
   const int size_src[2] = {
@@ -302,9 +299,6 @@ static void rect_realloc_16bytes(void **buf_p, const uint size[2])
   *buf_p = MEM_mallocN(sizeof(uint[4]) * size[0] * size[1], __func__);
 }
 
-/**
- * In-place size setting (caller must fill in buffer contents).
- */
 void IMB_rect_size_set(ImBuf *ibuf, const uint size[2])
 {
   BLI_assert(size[0] > 0 && size[1] > 0);
@@ -1070,11 +1064,6 @@ void IMB_rectblend_threaded(ImBuf *dbuf,
   }
 }
 
-/**
- * Replace pixels of entire image with solid color.
- * \param ibuf: An image to be filled with color. It must be 4 channel image.
- * \param col: RGBA color, which is assigned directly to both byte (via scaling) and float buffers.
- */
 void IMB_rectfill(ImBuf *drect, const float col[4])
 {
   int num;
@@ -1107,15 +1096,6 @@ void IMB_rectfill(ImBuf *drect, const float col[4])
   }
 }
 
-/**
- * Replace pixels of image area with solid color.
- * \param ibuf: an image to be filled with color. It must be 4 channel image.
- * \param col: RGBA color, which is assigned directly to both byte (via scaling) and float buffers.
- * \param x1, y1, x2, y2: (x1, y1) defines starting point of the rectangular area to be filled,
- * (x2, y2) is the end point. Note that values are allowed to be loosely ordered, which means that
- * x2 is allowed to be lower than x1, as well as y2 is allowed to be lower than y1. No matter the
- * order the area between x1 and x2, and y1 and y2 is filled.
- */
 void IMB_rectfill_area_replace(
     const ImBuf *ibuf, const float col[4], int x1, int y1, int x2, int y2)
 {
@@ -1273,21 +1253,6 @@ void buf_rectfill_area(unsigned char *rect,
   }
 }
 
-/**
- * Blend pixels of image area with solid color.
- *
- * For images with `uchar` buffer use color matching image color-space.
- * For images with float buffer use color display color-space.
- * If display color-space can not be referenced, use color in SRGB color-space.
- *
- * \param ibuf: an image to be filled with color. It must be 4 channel image.
- * \param col: RGBA color.
- * \param x1, y1, x2, y2: (x1, y1) defines starting point of the rectangular area to be filled,
- * (x2, y2) is the end point. Note that values are allowed to be loosely ordered, which means that
- * x2 is allowed to be lower than x1, as well as y2 is allowed to be lower than y1. No matter the
- * order the area between x1 and x2, and y1 and y2 is filled.
- * \param display: color-space reference for display space.
- */
 void IMB_rectfill_area(ImBuf *ibuf,
                        const float col[4],
                        int x1,
diff --git a/source/blender/imbuf/intern/scaling.c b/source/blender/imbuf/intern/scaling.c
index 1c4b7af6ef1..67d6cd68db5 100644
--- a/source/blender/imbuf/intern/scaling.c
+++ b/source/blender/imbuf/intern/scaling.c
@@ -372,7 +372,6 @@ MINLINE void premul_ushort_to_straight_uchar(unsigned char *result, const unsign
   }
 }
 
-/* result in ibuf2, scaling should be done correctly */
 void imb_onehalf_no_alloc(struct ImBuf *ibuf2, struct ImBuf *ibuf1)
 {
   int x, y;
@@ -1661,9 +1660,6 @@ static void scalefast_Z_ImBuf(ImBuf *ibuf, int newx, int newy)
   }
 }
 
-/**
- * Return true if \a ibuf is modified.
- */
 bool IMB_scaleImBuf(struct ImBuf *ibuf, unsigned int newx, unsigned int newy)
 {
   BLI_assert_msg(newx > 0 && newy > 0, "Images must be at least 1 on both dimensions!");
@@ -1709,9 +1705,6 @@ struct imbufRGBA {
   float r, g, b, a;
 };
 
-/**
- * Return true if \a ibuf is modified.
- */
 bool IMB_scalefastImBuf(struct ImBuf *ibuf, unsigned int newx, unsigned int newy)
 {
   BLI_assert_msg(newx > 0 && newy > 0, "Images must be at least 1 on both dimensions!");
diff --git a/source/blender/imbuf/intern/stereoimbuf.c b/source/blender/imbuf/intern/stereoimbuf.c
index d3c91b55f22..dae2604802f 100644
--- a/source/blender/imbuf/intern/stereoimbuf.c
+++ b/source/blender/imbuf/intern/stereoimbuf.c
@@ -757,7 +757,6 @@ float *IMB_stereo3d_from_rectf(ImageFormatData *im_format,
   return r_rectf;
 }
 
-/* left/right are always float */
 ImBuf *IMB_stereo3d_ImBuf(ImageFormatData *im_format, ImBuf *ibuf_left, ImBuf *ibuf_right)
 {
   ImBuf *ibuf_stereo = NULL;
@@ -1275,7 +1274,6 @@ static void imb_stereo3d_read_topbottom(Stereo3DData *s3d)
 /** \name Preparing To Call The Read Functions
  * \{ */
 
-/* reading a stereo encoded ibuf (*left) and generating two ibufs from it (*left and *right) */
 void IMB_ImBufFromStereo3d(Stereo3dFormat *s3d,
                            ImBuf *ibuf_stereo3d,
                            ImBuf **r_ibuf_left,
diff --git a/source/blender/imbuf/intern/thumbs.c b/source/blender/imbuf/intern/thumbs.c
index aa1da65253d..c39ce2e9a2a 100644
--- a/source/blender/imbuf/intern/thumbs.c
+++ b/source/blender/imbuf/intern/thumbs.c
@@ -523,7 +523,6 @@ ImBuf *IMB_thumb_create(const char *path, ThumbSize size, ThumbSource source, Im
       path, uri, thumb_name, false, THUMB_DEFAULT_HASH, NULL, NULL, size, source, img);
 }
 
-/* read thumbnail for file and returns new imbuf for thumbnail */
 ImBuf *IMB_thumb_read(const char *path, ThumbSize size)
 {
   char thumb[FILE_MAX];
@@ -540,7 +539,6 @@ ImBuf *IMB_thumb_read(const char *path, ThumbSize size)
   return img;
 }
 
-/* delete all thumbs for the file */
 void IMB_thumb_delete(const char *path, ThumbSize size)
 {
   char thumb[FILE_MAX];
@@ -559,7 +557,6 @@ void IMB_thumb_delete(const char *path, ThumbSize size)
   }
 }
 
-/* create the thumb if necessary and manage failed and old thumbs */
 ImBuf *IMB_thumb_manage(const char *org_path, ThumbSize size, ThumbSource source)
 {
   char thumb_path[FILE_MAX];
diff --git a/source/blender/imbuf/intern/tiff.c b/source/blender/imbuf/intern/tiff.c
index 623c00fa670..6ad373845fc 100644
--- a/source/blender/imbuf/intern/tiff.c
+++ b/source/blender/imbuf/intern/tiff.c
@@ -553,15 +553,6 @@ void imb_inittiff(void)
   }
 }
 
-/**
- * Loads a TIFF file.
- * \param mem: Memory containing the TIFF file.
- * \param size: Size of the mem buffer.
- * \param flags: If flags has IB_test set then the file is not actually loaded,
- * but all other operations take place.
- *
- * \return A newly allocated #ImBuf structure if successful, otherwise NULL.
- */
 ImBuf *imb_loadtiff(const unsigned char *mem,
                     size_t size,
                     int flags,
@@ -744,21 +735,6 @@ void imb_loadtiletiff(
 /** \name Save TIFF
  * \{ */
 
-/**
- * Saves a TIFF file.
- *
- * #ImBuf structures with 1, 3 or 4 bytes per pixel (GRAY, RGB, RGBA
- * respectively) are accepted, and interpreted correctly.  Note that the TIFF
- * convention is to use pre-multiplied alpha, which can be achieved within
- * Blender by setting "Premul" alpha handling.  Other alpha conventions are
- * not strictly correct, but are permitted anyhow.
- *
- * \param ibuf: Image buffer.
- * \param name: Name of the TIFF file to create.
- * \param flags: Currently largely ignored.
- *
- * \return 1 if the function is successful, 0 on failure.
- */
 bool imb_savetiff(ImBuf *ibuf, const char *filepath, int flags)
 {
   TIFF *image = NULL;
diff --git a/source/blender/imbuf/intern/util.c b/source/blender/imbuf/intern/util.c
index 1bb047f1317..18ed4710e78 100644
--- a/source/blender/imbuf/intern/util.c
+++ b/source/blender/imbuf/intern/util.c
@@ -98,7 +98,7 @@ const char *imb_ext_movie[] = {
     ".mpg2", ".vob", ".mkv", ".flv",   ".divx", ".xvid", ".mxf", ".webm", NULL,
 };
 
-/* sort of wrong being here... */
+/** Sort of wrong having audio extensions in imbuf. */
 const char *imb_ext_audio[] = {
     ".wav",
     ".ogg",
diff --git a/source/blender/imbuf/intern/util_gpu.c b/source/blender/imbuf/intern/util_gpu.c
index 2b99a0aa81d..cc6fef634d5 100644
--- a/source/blender/imbuf/intern/util_gpu.c
+++ b/source/blender/imbuf/intern/util_gpu.c
@@ -162,8 +162,6 @@ static void *imb_gpu_get_data(const ImBuf *ibuf,
   return data_rect;
 }
 
-/* The ibuf is only here to detect the storage type. The produced texture will have undefined
- * content. It will need to be populated by using IMB_update_gpu_texture_sub(). */
 GPUTexture *IMB_touch_gpu_texture(
     const char *name, ImBuf *ibuf, int w, int h, int layers, bool use_high_bitdepth)
 {
@@ -183,9 +181,6 @@ GPUTexture *IMB_touch_gpu_texture(
   return tex;
 }
 
-/* Will update a GPUTexture using the content of the ImBuf. Only one layer will be updated.
- * Will resize the ibuf if needed.
- * z is the layer to update. Unused if the texture is 2D. */
 void IMB_update_gpu_texture_sub(GPUTexture *tex,
                                 ImBuf *ibuf,
                                 int x,
-- 
cgit v1.2.3