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

- Added space below non doc-string comments to make it clear
  these aren't comments for the symbols directly below them.
- Use doxy sections for some headers.
- Minor improvements to doc-strings.

Ref T92709

1 files changed, 9 insertions, 61 deletions

diff --git a/source/blender/blenkernel/intern/image.c b/source/blender/blenkernel/intern/image.c
index 6fe415aedab..1c31e1be8bb 100644
--- a/source/blender/blenkernel/intern/image.c
+++ b/source/blender/blenkernel/intern/image.c
@@ -549,10 +549,6 @@ static void image_free_anims(Image *ima)
   }
 }
 
-/**
- * Simply free the image data from memory,
- * on display the image can load again (except for render buffers).
- */
 void BKE_image_free_buffers_ex(Image *ima, bool do_lock)
 {
   if (do_lock) {
@@ -579,7 +575,6 @@ void BKE_image_free_buffers(Image *ima)
   BKE_image_free_buffers_ex(ima, false);
 }
 
-/** Free (or release) any data used by this image (does not free the image itself). */
 void BKE_image_free_data(Image *ima)
 {
   image_free_data(&ima->id);
@@ -706,9 +701,11 @@ void BKE_image_merge(Main *bmain, Image *dest, Image *source)
   }
 }
 
-/* NOTE: We could be clever and scale all imbuf's but since some are mipmaps its not so simple. */
 bool BKE_image_scale(Image *image, int width, int height)
 {
+  /* NOTE: We could be clever and scale all imbuf's
+   * but since some are mipmaps its not so simple. */
+
   ImBuf *ibuf;
   void *lock;
 
@@ -807,9 +804,6 @@ int BKE_image_get_tile_from_pos(struct Image *ima,
   return tile_number;
 }
 
-/**
- * Return the tile_number for the closest UDIM tile.
- */
 int BKE_image_find_nearest_tile(const Image *image, const float co[2])
 {
   const float co_floor[2] = {floorf(co[0]), floorf(co[1])};
@@ -908,10 +902,6 @@ Image *BKE_image_load(Main *bmain, const char *filepath)
   return ima;
 }
 
-/* checks if image was already loaded, then returns same image */
-/* otherwise creates new. */
-/* does not load ibuf itself */
-/* pass on optional frame for #name images */
 Image *BKE_image_load_exists_ex(Main *bmain, const char *filepath, bool *r_exists)
 {
   Image *ima;
@@ -1058,7 +1048,6 @@ static ImBuf *add_ibuf_size(unsigned int width,
   return ibuf;
 }
 
-/* adds new image block, creates ImBuf and initializes color */
 Image *BKE_image_add_generated(Main *bmain,
                                unsigned int width,
                                unsigned int height,
@@ -1119,11 +1108,6 @@ Image *BKE_image_add_generated(Main *bmain,
   return ima;
 }
 
-/**
- * Create an image from ibuf. The refcount of ibuf is increased,
- * caller should take care to drop its reference by calling
- * #IMB_freeImBuf if needed.
- */
 Image *BKE_image_add_from_imbuf(Main *bmain, ImBuf *ibuf, const char *name)
 {
   /* on save, type is changed to FILE in editsima.c */
@@ -1175,7 +1159,6 @@ static bool image_memorypack_imbuf(Image *ima, ImBuf *ibuf, const char *filepath
   return true;
 }
 
-/* Pack image to memory. */
 bool BKE_image_memorypack(Image *ima)
 {
   bool ok = true;
@@ -1408,7 +1391,6 @@ static bool imagecache_check_free_anim(ImBuf *ibuf, void *UNUSED(userkey), void
          (except_frame != IMA_INDEX_ENTRY(ibuf->index));
 }
 
-/* except_frame is weak, only works for seqs without offset... */
 void BKE_image_free_anim_ibufs(Image *ima, int except_frame)
 {
   BLI_mutex_lock(ima->runtime.cache_mutex);
@@ -1670,8 +1652,6 @@ char BKE_imtype_valid_depths(const char imtype)
   }
 }
 
-/* string is from command line --render-format arg, keep in sync with
- * creator_args.c help info */
 char BKE_imtype_from_arg(const char *imtype_arg)
 {
   if (STREQ(imtype_arg, "TGA")) {
@@ -2775,8 +2755,6 @@ static const char *stamp_metadata_fields[] = {
     NULL,
 };
 
-/* Check whether the given metadata field name translates to a known field of
- * a stamp. */
 bool BKE_stamp_is_known_field(const char *field_name)
 {
   int i = 0;
@@ -2938,8 +2916,6 @@ bool BKE_imbuf_alpha_test(ImBuf *ibuf)
   return false;
 }
 
-/* NOTE: imf->planes is ignored here, its assumed the image channels
- * are already set */
 void BKE_imbuf_write_prepare(ImBuf *ibuf, const ImageFormatData *imf)
 {
   char imtype = imf->imtype;
@@ -3116,8 +3092,6 @@ int BKE_imbuf_write(ImBuf *ibuf, const char *name, const ImageFormatData *imf)
   return ok;
 }
 
-/* same as BKE_imbuf_write() but crappy workaround not to permanently modify
- * _some_, values in the imbuf */
 int BKE_imbuf_write_as(ImBuf *ibuf, const char *name, ImageFormatData *imf, const bool save_copy)
 {
   ImBuf ibuf_back = *ibuf;
@@ -3216,7 +3190,6 @@ struct anim *openanim_noload(const char *name,
   return anim;
 }
 
-/* used by sequencer too */
 struct anim *openanim(const char *name, int flags, int streamindex, char colorspace[IMA_MAX_SPACE])
 {
   struct anim *anim;
@@ -3262,8 +3235,6 @@ struct anim *openanim(const char *name, int flags, int streamindex, char colorsp
  *   -> comes from packedfile or filename or generated
  */
 
-/* forces existence of 1 Image for renderout or nodes, returns Image */
-/* name is only for default, when making new one */
 Image *BKE_image_ensure_viewer(Main *bmain, int type, const char *name)
 {
   Image *ima;
@@ -3304,7 +3275,6 @@ static void image_viewer_create_views(const RenderData *rd, Image *ima)
   }
 }
 
-/* Reset the image cache and views when the Viewer Nodes views don't match the scene views */
 void BKE_image_ensure_viewer_views(const RenderData *rd, Image *ima, ImageUser *iuser)
 {
   bool do_reset;
@@ -3959,7 +3929,6 @@ bool BKE_image_fill_tile(struct Image *ima,
 
 /* if layer or pass changes, we need an index for the imbufs list */
 /* note it is called for rendered results, but it doesn't use the index! */
-/* and because rendered results use fake layer/passes, don't correct for wrong indices here */
 RenderPass *BKE_image_multilayer_index(RenderResult *rr, ImageUser *iuser)
 {
   RenderLayer *rl;
@@ -4014,7 +3983,6 @@ void BKE_image_multiview_index(Image *ima, ImageUser *iuser)
 
 /* if layer or pass changes, we need an index for the imbufs list */
 /* note it is called for rendered results, but it doesn't use the index! */
-/* and because rendered results use fake layer/passes, don't correct for wrong indices here */
 bool BKE_image_is_multilayer(Image *ima)
 {
   if (ELEM(ima->source, IMA_SRC_FILE, IMA_SRC_SEQUENCE, IMA_SRC_TILED)) {
@@ -5046,9 +5014,10 @@ BLI_INLINE bool image_quick_test(Image *ima, const ImageUser *iuser)
   return true;
 }
 
-/* Checks optional ImageUser and verifies/creates ImBuf.
+/**
+ * Checks optional #ImageUser and verifies/creates #ImBuf.
  *
- * not thread-safe, so callee should worry about thread locks
+ * \warning Not thread-safe, so callee should worry about thread locks.
  */
 static ImBuf *image_acquire_ibuf(Image *ima, ImageUser *iuser, void **r_lock)
 {
@@ -5169,15 +5138,11 @@ static ImBuf *image_acquire_ibuf(Image *ima, ImageUser *iuser, void **r_lock)
   return ibuf;
 }
 
-/* return image buffer for given image and user
- *
- * - will lock render result if image type is render result and lock is not NULL
- * - will return NULL if image is NULL or image type is render or composite result and lock is NULL
- *
- * references the result, BKE_image_release_ibuf should be used to de-reference
- */
 ImBuf *BKE_image_acquire_ibuf(Image *ima, ImageUser *iuser, void **r_lock)
 {
+  /* NOTE: same as #image_acquire_ibuf, but can be used to retrieve images being rendered in
+   * a thread safe way, always call both acquire and release. */
+
   if (ima == NULL) {
     return NULL;
   }
@@ -5213,7 +5178,6 @@ void BKE_image_release_ibuf(Image *ima, ImBuf *ibuf, void *lock)
   }
 }
 
-/* checks whether there's an image buffer for given image and user */
 bool BKE_image_has_ibuf(Image *ima, ImageUser *iuser)
 {
   ImBuf *ibuf;
@@ -5721,19 +5685,16 @@ bool BKE_image_has_filepath(Image *ima)
   return ima->filepath[0] != '\0';
 }
 
-/* Checks the image buffer changes with time (not keyframed values). */
 bool BKE_image_is_animated(Image *image)
 {
   return ELEM(image->source, IMA_SRC_MOVIE, IMA_SRC_SEQUENCE);
 }
 
-/* Checks whether the image consists of multiple buffers. */
 bool BKE_image_has_multiple_ibufs(Image *image)
 {
   return ELEM(image->source, IMA_SRC_MOVIE, IMA_SRC_SEQUENCE, IMA_SRC_TILED);
 }
 
-/* Image modifications */
 bool BKE_image_is_dirty_writable(Image *image, bool *r_is_writable)
 {
   bool is_dirty = false;
@@ -5819,10 +5780,6 @@ bool BKE_image_has_loaded_ibuf(Image *image)
   return has_loaded_ibuf;
 }
 
-/**
- * References the result, #BKE_image_release_ibuf is to be called to de-reference.
- * Use lock=NULL when calling #BKE_image_release_ibuf().
- */
 ImBuf *BKE_image_get_ibuf_with_name(Image *image, const char *name)
 {
   ImBuf *ibuf = NULL;
@@ -5847,15 +5804,6 @@ ImBuf *BKE_image_get_ibuf_with_name(Image *image, const char *name)
   return ibuf;
 }
 
-/**
- * References the result, #BKE_image_release_ibuf is to be called to de-reference.
- * Use lock=NULL when calling #BKE_image_release_ibuf().
- *
- * TODO(sergey): This is actually "get first item from the cache", which is
- *               not so much predictable. But using first loaded image buffer
- *               was also malicious logic and all the areas which uses this
- *               function are to be re-considered.
- */
 ImBuf *BKE_image_get_first_ibuf(Image *image)
 {
   ImBuf *ibuf = NULL;