Add some documenting comments to the image encoders; no bug

image/encoders/ico/nsICOEncoder.cpp

@@ -157,7 +157,9 @@ nsICOEncoder::AddImageFrame(const uint8_t* aData,
     }
     mImageBufferCurr = mImageBufferStart;
 
-    // The icon buffer does not include the BFH at all.
+    // Icon files that wrap a BMP file must not include the BITMAPFILEHEADER
+    // section at the beginning of the encoded BMP data, so we must skip over
+    // BFH_LENGTH bytes when adding the BMP content to the icon file.
     mICODirEntry.mBytesInRes = BMPImageBufferSize - BFH_LENGTH + andMaskSize;
 
     // Encode the icon headers

image/src/ICOFileHeaders.h

@@ -14,28 +14,63 @@ namespace mozilla {
     #define PNGSIGNATURESIZE 8
     #define BMPFILEHEADERSIZE 14
 
+    /**
+     * The header that comes right at the start of an icon file. (This
+     * corresponds to the Windows ICONDIR structure.)
+     */
     struct IconFileHeader
     {
+      /**
+       * Must be set to 0;
+       */
       uint16_t   mReserved;
+      /**
+       * 1 for icon (.ICO) image (or 2 for cursor (.CUR) image (icon with the
+       * addition of a hotspot), but we don't support cursor).
+       */
       uint16_t   mType;
+      /**
+       * The number of BMP/PNG images contained in the icon file.
+       */
       uint16_t   mCount;
     };
 
+    /**
+     * For each BMP/PNG image that the icon file containts there must be a
+     * corresponding icon dir entry. (This corresponds to the Windows
+     * ICONDIRENTRY structure.) These entries are encoded directly after the
+     * IconFileHeader.
+     */
     struct IconDirEntry
     {
       uint8_t   mWidth;
       uint8_t   mHeight;
+      /**
+       * The number of colors in the color palette of the BMP/PNG that this dir
+       * entry corresponds to, or 0 if the image does not use a color palette.
+       */
       uint8_t   mColorCount;
+      /**
+       * Should be set to 0.
+       */
       uint8_t   mReserved;
       union {
         uint16_t mPlanes;   // ICO
         uint16_t mXHotspot; // CUR
       };
       union {
-        uint16_t mBitCount; // ICO
+        uint16_t mBitCount; // ICO (bits per pixel)
         uint16_t mYHotspot; // CUR
       };
+      /**
+       * "bytes in resource" is the length of the encoded BMP/PNG that this dir
+       * entry corresponds to.
+       */
       uint32_t  mBytesInRes;
+      /**
+       * The offset of the start of the encoded BMP/PNG that this dir entry
+       * corresponds to (from the start of the icon file).
+       */
       uint32_t  mImageOffset;
     };