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

Ref T92709

35 files changed, 526 insertions, 289 deletions

diff --git a/source/blender/imbuf/IMB_colormanagement.h b/source/blender/imbuf/IMB_colormanagement.h
index 53b0e295385..3ea8ac47f17 100644
--- a/source/blender/imbuf/IMB_colormanagement.h
+++ b/source/blender/imbuf/IMB_colormanagement.h
@@ -45,7 +45,9 @@ struct bContext;
 struct ColorManagedDisplay;
 struct ColorSpace;
 
-/* ** Generic functions ** */
+/* -------------------------------------------------------------------- */
+/** \name Generic Functions
+ * \{ */
 
 void IMB_colormanagement_check_file_config(struct Main *bmain);
 
@@ -67,13 +69,35 @@ bool IMB_colormanagement_space_is_scene_linear(struct ColorSpace *colorspace);
 bool IMB_colormanagement_space_is_srgb(struct ColorSpace *colorspace);
 bool IMB_colormanagement_space_name_is_data(const char *name);
 
+/**
+ * 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
+ */
 BLI_INLINE float IMB_colormanagement_get_luminance(const float rgb[3]);
+/**
+ * Byte equivalent of #IMB_colormanagement_get_luminance().
+ */
 BLI_INLINE unsigned char IMB_colormanagement_get_luminance_byte(const unsigned char[3]);
 BLI_INLINE void IMB_colormanagement_xyz_to_rgb(float rgb[3], const float xyz[3]);
 BLI_INLINE void IMB_colormanagement_rgb_to_xyz(float xyz[3], const float rgb[3]);
 const float *IMB_colormanagement_get_xyz_to_rgb(void);
 
-/* ** Color space transformation functions ** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Color Space Transformation Functions
+ * \{ */
+
+/**
+ * Convert the whole buffer from specified by name color space to another.
+ */
 void IMB_colormanagement_transform(float *buffer,
                                    int width,
                                    int height,
@@ -81,6 +105,10 @@ void IMB_colormanagement_transform(float *buffer,
                                    const char *from_colorspace,
                                    const char *to_colorspace,
                                    bool predivide);
+/**
+ * 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,
@@ -88,6 +116,9 @@ void IMB_colormanagement_transform_threaded(float *buffer,
                                             const char *from_colorspace,
                                             const char *to_colorspace,
                                             bool predivide);
+/**
+ * Similar to #IMB_colormanagement_transform_threaded, but operates on byte buffer.
+ */
 void IMB_colormanagement_transform_byte(unsigned char *buffer,
                                         int width,
                                         int height,
@@ -100,6 +131,9 @@ void IMB_colormanagement_transform_byte_threaded(unsigned char *buffer,
                                                  int channels,
                                                  const char *from_colorspace,
                                                  const char *to_colorspace);
+/**
+ * Similar to #IMB_colormanagement_transform_byte_threaded, but gets float buffer from display one.
+ */
 void IMB_colormanagement_transform_from_byte(float *float_buffer,
                                              unsigned char *byte_buffer,
                                              int width,
@@ -118,12 +152,20 @@ void IMB_colormanagement_transform_v4(float pixel[4],
                                       const char *from_colorspace,
                                       const char *to_colorspace);
 
+/**
+ * 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],
                                                        struct ColorSpace *colorspace);
 void IMB_colormanagement_colorspace_to_scene_linear_v4(float pixel[4],
                                                        bool predivide,
                                                        struct ColorSpace *colorspace);
 
+/**
+ * Same as #IMB_colormanagement_colorspace_to_scene_linear_v4,
+ * but converts colors in opposite direction.
+ */
 void IMB_colormanagement_scene_linear_to_colorspace_v3(float pixel[3],
                                                        struct ColorSpace *colorspace);
 
@@ -150,14 +192,36 @@ void IMB_colormanagement_imbuf_to_float_texture(float *out_buffer,
                                                 const struct ImBuf *ibuf,
                                                 const bool store_premultiplied);
 
+/**
+ * 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]);
 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]);
 void IMB_colormanagement_srgb_to_scene_linear_v3(float pixel[3]);
 
+/**
+ * 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],
                                                     struct ColorManagedDisplay *display);
+/**
+ * Same as #IMB_colormanagement_scene_linear_to_display_v3,
+ * but converts color in opposite direction.
+ */
 void IMB_colormanagement_display_to_scene_linear_v3(float pixel[3],
                                                     struct ColorManagedDisplay *display);
 
@@ -178,6 +242,18 @@ void IMB_colormanagement_imbuf_make_display_space(
     const struct ColorManagedViewSettings *view_settings,
     const struct ColorManagedDisplaySettings *display_settings);
 
+/**
+ * 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.
+ */
 struct ImBuf *IMB_colormanagement_imbuf_for_write(
     struct ImBuf *ibuf,
     bool save_as_render,
@@ -196,7 +272,11 @@ void IMB_colormanagement_buffer_make_display_space(
     const struct ColorManagedViewSettings *view_settings,
     const struct ColorManagedDisplaySettings *display_settings);
 
-/* ** Public display buffers interfaces ** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Public Display Buffers Interfaces
+ * \{ */
 
 void IMB_colormanagement_display_settings_from_ctx(
     const struct bContext *C,
@@ -207,11 +287,17 @@ const char *IMB_colormanagement_get_display_colorspace_name(
     const struct ColorManagedViewSettings *view_settings,
     const struct ColorManagedDisplaySettings *display_settings);
 
+/**
+ * Acquire display buffer for given image buffer using specified view and display settings.
+ */
 unsigned char *IMB_display_buffer_acquire(
     struct ImBuf *ibuf,
     const struct ColorManagedViewSettings *view_settings,
     const struct ColorManagedDisplaySettings *display_settings,
     void **cache_handle);
+/**
+ * Same as #IMB_display_buffer_acquire but gets view and display settings from context.
+ */
 unsigned char *IMB_display_buffer_acquire_ctx(const struct bContext *C,
                                               struct ImBuf *ibuf,
                                               void **cache_handle);
@@ -227,24 +313,47 @@ void IMB_display_buffer_transform_apply(unsigned char *display_buffer,
 
 void IMB_display_buffer_release(void *cache_handle);
 
-/* ** Display functions ** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Display Functions
+ * \{ */
+
 int IMB_colormanagement_display_get_named_index(const char *name);
 const char *IMB_colormanagement_display_get_indexed_name(int index);
 const char *IMB_colormanagement_display_get_default_name(void);
+/**
+ * Used by performance-critical pixel processing areas, such as color widgets.
+ */
 struct ColorManagedDisplay *IMB_colormanagement_display_get_named(const char *name);
 const char *IMB_colormanagement_display_get_none_name(void);
 const char *IMB_colormanagement_display_get_default_view_transform_name(
     struct ColorManagedDisplay *display);
 
-/* ** View functions ** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name View Functions
+ * \{ */
+
 int IMB_colormanagement_view_get_named_index(const char *name);
 const char *IMB_colormanagement_view_get_indexed_name(int index);
 
-/* ** Look functions ** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Look Functions
+ * \{ */
+
 int IMB_colormanagement_look_get_named_index(const char *name);
 const char *IMB_colormanagement_look_get_indexed_name(int index);
 
-/* ** Color space functions ** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Color Space Functions
+ * \{ */
+
 int IMB_colormanagement_colorspace_get_named_index(const char *name);
 const char *IMB_colormanagement_colorspace_get_indexed_name(int index);
 const char *IMB_colormanagement_view_get_default_name(const char *display_name);
@@ -252,7 +361,12 @@ const char *IMB_colormanagement_view_get_default_name(const char *display_name);
 void IMB_colormanagement_colorspace_from_ibuf_ftype(
     struct ColorManagedColorspaceSettings *colorspace_settings, struct ImBuf *ibuf);
 
-/* ** RNA helper functions ** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name RNA Helper Functions
+ * \{ */
+
 void IMB_colormanagement_display_items_add(struct EnumPropertyItem **items, int *totitem);
 void IMB_colormanagement_view_items_add(struct EnumPropertyItem **items,
                                         int *totitem,
@@ -262,7 +376,12 @@ void IMB_colormanagement_look_items_add(struct EnumPropertyItem **items,
                                         const char *view_name);
 void IMB_colormanagement_colorspace_items_add(struct EnumPropertyItem **items, int *totitem);
 
-/* ** Tile-based buffer management ** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Tile-based Buffer Management
+ * \{ */
+
 void IMB_partial_display_buffer_update(struct ImBuf *ibuf,
                                        const float *linear_buffer,
                                        const unsigned char *byte_buffer,
@@ -293,7 +412,12 @@ void IMB_partial_display_buffer_update_threaded(
 void IMB_partial_display_buffer_update_delayed(
     struct ImBuf *ibuf, int xmin, int ymin, int xmax, int ymax);
 
-/* ** Pixel processor functions ** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Pixel Processor Functions
+ * \{ */
+
 struct ColormanageProcessor *IMB_colormanagement_display_processor_new(
     const struct ColorManagedViewSettings *view_settings,
     const struct ColorManagedDisplaySettings *display_settings);
@@ -321,17 +445,40 @@ void IMB_colormanagement_processor_apply_byte(struct ColormanageProcessor *cm_pr
                                               int channels);
 void IMB_colormanagement_processor_free(struct ColormanageProcessor *cm_processor);
 
-/* ** OpenGL drawing routines using GLSL for color space transform ** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name OpenGL Drawing Routines Using GLSL for Color Space Transform
+ * \{ */
 
-/* Test if GLSL drawing is supported for combination of graphics card and this configuration */
+/**
+ * Test if GLSL drawing is supported for combination of graphics card and this configuration.
+ */
 bool IMB_colormanagement_support_glsl_draw(const struct ColorManagedViewSettings *view_settings);
-/* Configures GLSL shader for conversion from scene linear to display space */
+/**
+ * Configures GLSL shader for conversion from scene linear to display space.
+ */
 bool IMB_colormanagement_setup_glsl_draw(
     const struct ColorManagedViewSettings *view_settings,
     const struct ColorManagedDisplaySettings *display_settings,
     float dither,
     bool predivide);
-/* Same as above, but display space conversion happens from a specified space */
+/**
+ * \note Same as IMB_colormanagement_setup_glsl_draw,
+ * but display space conversion happens from a specified space.
+ *
+ * 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 struct ColorManagedViewSettings *view_settings,
     const struct ColorManagedDisplaySettings *display_settings,
@@ -339,20 +486,31 @@ bool IMB_colormanagement_setup_glsl_draw_from_space(
     float dither,
     bool predivide,
     bool do_overlay_merge);
-/* Same as setup_glsl_draw, but color management settings are guessing from a given context */
+/**
+ * Same as setup_glsl_draw, but color management settings are guessing from a given context.
+ */
 bool IMB_colormanagement_setup_glsl_draw_ctx(const struct bContext *C,
                                              float dither,
                                              bool predivide);
-/* Same as setup_glsl_draw_from_space,
- * but color management settings are guessing from a given context. */
+/**
+ * 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 struct bContext *C,
                                                         struct ColorSpace *colorspace,
                                                         float dither,
                                                         bool predivide);
-/* Finish GLSL-based display space conversion */
+/**
+ * Finish GLSL-based display space conversion.
+ */
 void IMB_colormanagement_finish_glsl_draw(void);
 
-/* ** View transform ** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name View Transform
+ * \{ */
+
 void IMB_colormanagement_init_default_view_settings(
     struct ColorManagedViewSettings *view_settings,
     const struct ColorManagedDisplaySettings *display_settings);
@@ -368,6 +526,8 @@ enum {
   COLOR_ROLE_DATA,
 };
 
+/** \} */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/source/blender/imbuf/IMB_imbuf.h b/source/blender/imbuf/IMB_imbuf.h
index 45236033dfe..28e84d3d973 100644
--- a/source/blender/imbuf/IMB_imbuf.h
+++ b/source/blender/imbuf/IMB_imbuf.h
@@ -152,6 +152,8 @@ bool IMB_initImBuf(
  * Create a copy of a pixel buffer and wrap it to a new ImBuf
  * (transferring ownership to the in imbuf).
  * \attention Defined in allocimbuf.c
+ *
+ * \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);
@@ -244,8 +246,14 @@ void IMB_blend_color_float(float dst[4],
                            const float src2[4],
                            IMB_BlendMode mode);
 
+/**
+ * In-place image crop.
+ */
 void IMB_rect_crop(struct ImBuf *ibuf, const struct rcti *crop);
 
+/**
+ * In-place size setting (caller must fill in buffer contents).
+ */
 void IMB_rect_size_set(struct ImBuf *ibuf, const uint size[2]);
 
 void IMB_rectclip(struct ImBuf *dbuf,
@@ -342,7 +350,9 @@ typedef enum eIMBInterpolationFilterMode {
   IMB_FILTER_BILINEAR,
 } eIMBInterpolationFilterMode;
 
-/* Defaults to BL_proxy within the directory of the animation. */
+/**
+ * Defaults to BL_proxy within the directory of the animation.
+ */
 void IMB_anim_set_index_dir(struct anim *anim, const char *dir);
 void IMB_anim_get_fname(struct anim *anim, char *file, int size);
 
@@ -352,7 +362,9 @@ IMB_Proxy_Size IMB_anim_proxy_get_existing(struct anim *anim);
 
 struct IndexBuildContext;
 
-/* Prepare context for proxies/time-codes builder. */
+/**
+ * Prepare context for proxies/time-codes builder
+ */
 struct IndexBuildContext *IMB_anim_index_rebuild_context(struct anim *anim,
                                                          IMB_Timecode_Type tcs_in_use,
                                                          IMB_Proxy_Size proxy_sizes_in_use,
@@ -360,13 +372,17 @@ struct IndexBuildContext *IMB_anim_index_rebuild_context(struct anim *anim,
                                                          const bool overwrite,
                                                          struct GSet *file_list);
 
-/* Will rebuild all used indices and proxies at once. */
+/**
+ * Will rebuild all used indices and proxies at once.
+ */
 void IMB_anim_index_rebuild(struct IndexBuildContext *context,
                             short *stop,
                             short *do_update,
                             float *progress);
 
-/* Finish rebuilding proxies/time-codes and free temporary contexts used. */
+/**
+ * Finish rebuilding proxies/time-codes and free temporary contexts used.
+ */
 void IMB_anim_index_rebuild_finish(struct IndexBuildContext *context, short stop);
 
 /**
@@ -442,8 +458,20 @@ void IMB_free_anim(struct anim *anim);
 void IMB_filter(struct ImBuf *ibuf);
 void IMB_mask_filter_extend(char *mask, int width, int height);
 void IMB_mask_clear(struct ImBuf *ibuf, const char *mask, int val);
+/**
+ * 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);
+/**
+ * Frees too (if there) and recreates new data.
+ */
 void IMB_makemipmap(struct ImBuf *ibuf, int use_filter);
+/**
+ * Thread-safe version, only recreates existing maps.
+ */
 void IMB_remakemipmap(struct ImBuf *ibuf, int use_filter);
 struct ImBuf *IMB_getmipmap(struct ImBuf *ibuf, int level);
 
@@ -452,6 +480,9 @@ struct ImBuf *IMB_getmipmap(struct ImBuf *ibuf, int level);
  * \attention Defined in cache.c
  */
 
+/**
+ * Presumed to be called when no threads are running.
+ */
 void IMB_tile_cache_params(int totthread, int maxmem);
 unsigned int *IMB_gettile(struct ImBuf *ibuf, int tx, int ty, int thread);
 void IMB_tiles_to_rect(struct ImBuf *ibuf);
@@ -471,6 +502,8 @@ struct ImBuf *IMB_onehalf(struct ImBuf *ibuf1);
 /**
  *
  * \attention Defined in scaling.c
+ *
+ * Return true if \a ibuf is modified.
  */
 bool IMB_scaleImBuf(struct ImBuf *ibuf, unsigned int newx, unsigned int newy);
 
@@ -478,6 +511,9 @@ bool IMB_scaleImBuf(struct ImBuf *ibuf, unsigned int newx, unsigned int newy);
  *
  * \attention Defined in scaling.c
  */
+/**
+ * Return true if \a ibuf is modified.
+ */
 bool IMB_scalefastImBuf(struct ImBuf *ibuf, unsigned int newx, unsigned int newy);
 
 /**
@@ -520,16 +556,27 @@ int imb_get_anim_type(const char *filepath);
  */
 bool IMB_isfloat(const struct ImBuf *ibuf);
 
-/* Do byte/float and colorspace conversions need to take alpha into account? */
+/**
+ * Test if color-space conversions of pixels in buffer need to take into account alpha.
+ */
 bool IMB_alpha_affects_rgb(const struct ImBuf *ibuf);
 
-/* create char buffer, color corrected if necessary, for ImBufs that lack one */
+/**
+ * Create char buffer, color corrected if necessary, for ImBufs that lack one.
+ */
 void IMB_rect_from_float(struct ImBuf *ibuf);
 void IMB_float_from_rect(struct ImBuf *ibuf);
+/**
+ * No profile conversion.
+ */
 void IMB_color_to_bw(struct ImBuf *ibuf);
 void IMB_saturation(struct ImBuf *ibuf, float sat);
 
-/* converting pixel buffers */
+/* Converting pixel buffers. */
+
+/**
+ * Float to byte pixels, output 4-channel RGBA.
+ */
 void IMB_buffer_byte_from_float(unsigned char *rect_to,
                                 const float *rect_from,
                                 int channels_from,
@@ -541,6 +588,9 @@ void IMB_buffer_byte_from_float(unsigned char *rect_to,
                                 int height,
                                 int stride_to,
                                 int stride_from);
+/**
+ * Float to byte pixels, output 4-channel RGBA.
+ */
 void IMB_buffer_byte_from_float_mask(unsigned char *rect_to,
                                      const float *rect_from,
                                      int channels_from,
@@ -551,6 +601,9 @@ void IMB_buffer_byte_from_float_mask(unsigned char *rect_to,
                                      int stride_to,
                                      int stride_from,
                                      char *mask);
+/**
+ * Byte to float pixels, input and output 4-channel RGBA.
+ */
 void IMB_buffer_float_from_byte(float *rect_to,
                                 const unsigned char *rect_from,
                                 int profile_to,
@@ -560,6 +613,9 @@ void IMB_buffer_float_from_byte(float *rect_to,
                                 int height,
                                 int stride_to,
                                 int stride_from);
+/**
+ * Float to float pixels, output 4-channel RGBA.
+ */
 void IMB_buffer_float_from_float(float *rect_to,
                                  const float *rect_from,
                                  int channels_from,
@@ -580,6 +636,9 @@ void IMB_buffer_float_from_float_threaded(float *rect_to,
                                           int height,
                                           int stride_to,
                                           int stride_from);
+/**
+ * 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,
@@ -588,6 +647,9 @@ void IMB_buffer_float_from_float_mask(float *rect_to,
                                       int stride_to,
                                       int stride_from,
                                       char *mask);
+/**
+ * Byte to byte pixels, input and output 4-channel RGBA.
+ */
 void IMB_buffer_byte_from_byte(unsigned char *rect_to,
                                const unsigned char *rect_from,
                                int profile_to,
@@ -605,6 +667,8 @@ void IMB_buffer_float_premultiply(float *buf, int width, int height);
  * rgba to abgr. size * 4 color bytes are reordered.
  *
  * \attention Defined in imageprocess.c
+ *
+ * Only this one is used liberally here, and in imbuf.
  */
 void IMB_convert_rgba_to_abgr(struct ImBuf *ibuf);
 
@@ -624,6 +688,9 @@ typedef void (*InterpolationColorFunction)(
     const struct ImBuf *in, unsigned char outI[4], float outF[4], float u, float v);
 void bicubic_interpolation_color(
     const struct ImBuf *in, unsigned char outI[4], float outF[4], float u, float v);
+
+/* Functions assumes out to be zero'ed, only does RGBA. */
+
 void nearest_interpolation_color_char(
     const struct ImBuf *in, unsigned char outI[4], float outF[4], float u, float v);
 void nearest_interpolation_color_fl(
@@ -638,12 +705,21 @@ void bilinear_interpolation_color_char(
     const struct ImBuf *in, unsigned char outI[4], float outF[4], float u, float v);
 void bilinear_interpolation_color_fl(
     const struct ImBuf *in, unsigned char outI[4], float outF[4], float u, float v);
+/**
+ * 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);
 
 void IMB_alpha_under_color_float(float *rect_float, int x, int y, float backcol[3]);
 void IMB_alpha_under_color_byte(unsigned char *rect, int x, int y, const float backcol[3]);
 
+/**
+ * Sample pixel of image using NEAREST method.
+ */
 void IMB_sampleImageAtLocation(
     struct ImBuf *ibuf, float x, float y, bool make_linear_rgb, float color[4]);
 
@@ -697,7 +773,7 @@ struct ImBuf *IMB_double_y(struct ImBuf *ibuf1);
 void IMB_flipx(struct ImBuf *ibuf);
 void IMB_flipy(struct ImBuf *ibuf);
 
-/* Premultiply alpha */
+/* Pre-multiply alpha. */
 
 void IMB_premultiply_alpha(struct ImBuf *ibuf);
 void IMB_unpremultiply_alpha(struct ImBuf *ibuf);
@@ -713,7 +789,27 @@ void IMB_freezbuffloatImBuf(struct ImBuf *ibuf);
  *
  * \attention Defined in rectop.c
  */
+/**
+ * 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(struct ImBuf *drect, const float col[4]);
+/**
+ * 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(struct ImBuf *ibuf,
                        const float col[4],
                        int x1,
@@ -721,12 +817,23 @@ void IMB_rectfill_area(struct ImBuf *ibuf,
                        int x2,
                        int y2,
                        struct ColorManagedDisplay *display);
+/**
+ * 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 struct ImBuf *ibuf, const float col[4], int x1, int y1, int x2, int y2);
 void IMB_rectfill_alpha(struct ImBuf *ibuf, const float value);
 
-/* This should not be here, really,
- * we needed it for operating on render data, IMB_rectfill_area calls it. */
+/**
+ * This should not be here, really,
+ * we needed it for operating on render data, #IMB_rectfill_area calls it.
+ */
 void buf_rectfill_area(unsigned char *rect,
                        float *rectf,
                        int width,
@@ -738,23 +845,34 @@ void buf_rectfill_area(unsigned char *rect,
                        int x2,
                        int y2);
 
-/* exported for image tools in blender, to quickly allocate 32 bits rect */
+/**
+ * Exported for image tools in blender, to quickly allocate 32 bits rect.
+ */
 void *imb_alloc_pixels(
     unsigned int x, unsigned int y, unsigned int channels, size_t typesize, const char *name);
 
 bool imb_addrectImBuf(struct ImBuf *ibuf);
+/**
+ * Any free `ibuf->rect` frees mipmaps to be sure, creation is in render on first request.
+ */
 void imb_freerectImBuf(struct ImBuf *ibuf);
 
 bool imb_addrectfloatImBuf(struct ImBuf *ibuf);
+/**
+ * Any free `ibuf->rect` frees mipmaps to be sure, creation is in render on first request.
+ */
 void imb_freerectfloatImBuf(struct ImBuf *ibuf);
 void imb_freemipmapImBuf(struct ImBuf *ibuf);
 
 bool imb_addtilesImBuf(struct ImBuf *ibuf);
 void imb_freetilesImBuf(struct ImBuf *ibuf);
 
+/** Free all pixel data (associated with image size). */
 void imb_freerectImbuf_all(struct ImBuf *ibuf);
 
-/* threaded processors */
+/**
+ * Threaded processors.
+ */
 void IMB_processor_apply_threaded(
     int buffer_lines,
     int handle_size,
@@ -788,7 +906,8 @@ void IMB_transform(const struct ImBuf *src,
                    const float transform_matrix[4][4],
                    const struct rctf *src_crop);
 
-/* ffmpeg */
+/* FFMPEG */
+
 void IMB_ffmpeg_init(void);
 const char *IMB_ffmpeg_last_error(void);
 
@@ -801,8 +920,17 @@ struct GPUTexture *IMB_create_gpu_texture(const char *name,
                                           bool use_high_bitdepth,
                                           bool use_premult,
                                           bool limit_gl_texture_size);
+/**
+ * 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().
+ */
 struct GPUTexture *IMB_touch_gpu_texture(
     const char *name, struct ImBuf *ibuf, int w, int h, int layers, bool use_high_bitdepth);
+/**
+ * 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(struct GPUTexture *tex,
                                 struct ImBuf *ibuf,
                                 int x,
@@ -814,7 +942,6 @@ void IMB_update_gpu_texture_sub(struct GPUTexture *tex,
                                 bool use_premult);
 
 /**
- *
  * \attention defined in stereoimbuf.c
  */
 void IMB_stereo3d_write_dimensions(const char mode,
@@ -841,9 +968,15 @@ float *IMB_stereo3d_from_rectf(struct ImageFormatData *im_format,
                                const size_t channels,
                                float *rectf_left,
                                float *rectf_right);
+/**
+ * Left/right are always float.
+ */
 struct ImBuf *IMB_stereo3d_ImBuf(struct ImageFormatData *im_format,
                                  struct ImBuf *ibuf_left,
                                  struct ImBuf *ibuf_right);
+/**
+ * Reading a stereo encoded ibuf (*left) and generating two ibufs from it (*left and *right).
+ */
 void IMB_ImBufFromStereo3d(struct Stereo3dFormat *s3d,
                            struct ImBuf *ibuf_stereo,
                            struct ImBuf **r_ibuf_left,
diff --git a/source/blender/imbuf/IMB_imbuf_types.h b/source/blender/imbuf/IMB_imbuf_types.h
index 9697064b445..a083d4e360c 100644
--- a/source/blender/imbuf/IMB_imbuf_types.h
+++ b/source/blender/imbuf/IMB_imbuf_types.h
@@ -322,7 +322,7 @@ enum {
 #  endif /* DDS_MAKEFOURCC */
 
 /*
- * FOURCC codes for DX compressed-texture pixel formats
+ * FOURCC codes for DX compressed-texture pixel formats.
  */
 
 #  define FOURCC_DDS (DDS_MAKEFOURCC('D', 'D', 'S', ' '))
@@ -337,7 +337,7 @@ extern const char *imb_ext_image[];
 extern const char *imb_ext_movie[];
 extern const char *imb_ext_audio[];
 
-/* image formats that can only be loaded via filepath */
+/** Image formats that can only be loaded via filepath. */
 extern const char *imb_ext_image_filepath_only[];
 
 /**
diff --git a/source/blender/imbuf/IMB_moviecache.h b/source/blender/imbuf/IMB_moviecache.h
index d32346a8418..156a060c621 100644
--- a/source/blender/imbuf/IMB_moviecache.h
+++ b/source/blender/imbuf/IMB_moviecache.h
@@ -70,6 +70,9 @@ void IMB_moviecache_cleanup(struct MovieCache *cache,
                                                    void *userdata),
                             void *userdata);
 
+/**
+ * Get segments of cached frames. Useful for debugging cache policies.
+ */
 void IMB_moviecache_get_cache_segments(
     struct MovieCache *cache, int proxy, int render_flags, int *r_totseg, int **r_points);
 
diff --git a/source/blender/imbuf/IMB_thumbs.h b/source/blender/imbuf/IMB_thumbs.h
index e1a315a0bd2..6a739002fb3 100644
--- a/source/blender/imbuf/IMB_thumbs.h
+++ b/source/blender/imbuf/IMB_thumbs.h
@@ -48,47 +48,66 @@ typedef enum ThumbSource {
   THB_SOURCE_FONT,
 } ThumbSource;
 
-/* don't generate thumbs for images bigger than this (100mb) */
+/**
+ * Don't generate thumbs for images bigger than this (100mb).
+ */
 #define THUMB_SIZE_MAX (100 * 1024 * 1024)
 
 #define PREVIEW_RENDER_DEFAULT_HEIGHT 128
 #define PREVIEW_RENDER_LARGE_HEIGHT 256
 
-/* Note this can also be used as versioning system,
+/**
+ * Note this can also be used as versioning system,
  * to force refreshing all thumbnails if e.g. we change some thumb generating code or so.
- * Only used by fonts so far. */
+ * Only used by fonts so far.
+ */
 #define THUMB_DEFAULT_HASH "00000000000000000000000000000000"
 
-/* create thumbnail for file and returns new imbuf for thumbnail */
+/**
+ * Create thumbnail for file and returns new imbuf for thumbnail.
+ */
 struct ImBuf *IMB_thumb_create(const char *path,
                                ThumbSize size,
                                ThumbSource source,
                                struct ImBuf *img);
 
-/* read thumbnail for file and returns new imbuf for thumbnail */
+/**
+ * Read thumbnail for file and returns new imbuf for thumbnail.
+ */
 struct ImBuf *IMB_thumb_read(const char *path, ThumbSize size);
 
-/* delete all thumbs for the file */
+/**
+ * Delete all thumbs for the file.
+ */
 void IMB_thumb_delete(const char *path, ThumbSize size);
 
-/* return the state of the thumb, needed to determine how to manage the thumb */
+/**
+ * Create the thumb if necessary and manage failed and old thumbs.
+ */
 struct ImBuf *IMB_thumb_manage(const char *path, ThumbSize size, ThumbSource source);
 
-/* create the necessary dirs to store the thumbnails */
+/**
+ * Create the necessary dirs to store the thumbnails.
+ */
 void IMB_thumb_makedirs(void);
 
-/* special function for loading a thumbnail embedded into a blend file */
+/**
+ * Special function for loading a thumbnail embedded into a blend file.
+ */
 struct ImBuf *IMB_thumb_load_blend(const char *blen_path,
                                    const char *blen_group,
                                    const char *blen_id);
 
-/* special function for previewing fonts */
+/**
+ * Special function for previewing fonts.
+ */
 struct ImBuf *IMB_thumb_load_font(const char *filename, unsigned int x, unsigned int y);
 bool IMB_thumb_load_font_get_hash(char *r_hash);
 void IMB_thumb_clear_translations(void);
 void IMB_thumb_ensure_translations(void);
 
 /* Threading */
+
 void IMB_thumb_locks_acquire(void);
 void IMB_thumb_locks_release(void);
 void IMB_thumb_path_lock(const char *path);
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,