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

Ref T92709

8 files changed, 34 insertions, 28 deletions

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);