Merge pull request #710 from GerHobbelt/comment-tweaks-2

Source comment tweaks/fixes

src/adaptmap.c

@@ -291,7 +291,7 @@ pixBackgroundNormSimple(PIX  *pixs,
  *        grayscale version can be used elsewhere.  If the input is RGB
  *        and this is not supplied, it is made internally using only
  *        the green component, and destroyed after use.
- *    (6) The dimensions of the pixel tile (%sx, %sy) give the amount by
+ *    (6) The dimensions of the pixel tile (%sx, %sy) give the amount
  *        by which the map is reduced in size from the input image.
  *    (7) The input image is binarized using %thresh, in order to
  *        locate the foreground components.  If this is set too low,

src/coloring.c

@@ -459,7 +459,7 @@ PIXCMAP   *cmap;
  * \param[in]    srcval   color center to be selected for change: 0xrrggbb00
  * \param[in]    dstval   target color for pixels: 0xrrggbb00
  * \param[in]    diff     max absolute difference, applied to all components
- * \return  pixd   with all pixels within diff of pixval set to pixval,
+ * \return  pixd   with all pixels within diff of srcval set to dstval,
  *                 or pixd on error
  *
  * <pre>

src/convolve.c

@@ -296,7 +296,7 @@ PIX       *pixd, *pixt;
  *          for the first wc + 1 and last wc columns in the intermediate
  *          lines.
  *      (5) The caller should verify that wc < w and hc < h.
- *          Under those conditions, illegal reads and writes can occur.
+ *          Failing either condition, illegal reads and writes can occur.
  *      (6) Implementation note: to get the same results in the interior
  *          between this function and pixConvolve(), it is necessary to
  *          add 0.5 for roundoff in the main loop that runs over all pixels.

src/numafunc1.c

@@ -1415,7 +1415,7 @@ NUMA      *nad;
  *
  * <pre>
  * Notes:
- *      (1) For each edge interval, where where the value is less
+ *      (1) For each edge interval, where the value is less
  *          than %thresh1 on one side, greater than %thresh2 on
  *          the other, and between these thresholds throughout the
  *          interval, this records a triplet of values: the

src/pix2.c

@@ -1465,9 +1465,9 @@ l_uint32  *data, *pword;
 /*!
  * \brief   pixSetOrClearBorder()
  *
- * \param[in]    pixs   all depths
- * \param[in]    left,  right, top, bot amount to set or clear
- * \param[in]    op     operation PIX_SET or PIX_CLR
+ * \param[in]    pixs                     all depths
+ * \param[in]    left, right, top, bot    border region amount to set or clear: these distances are from outside
+ * \param[in]    op                       operation PIX_SET or PIX_CLR
  * \return  0 if OK; 1 on error
  *
  * <pre>
@@ -1511,7 +1511,7 @@ l_int32  w, h;
  * \brief   pixSetBorderVal()
  *
  * \param[in]    pixs                   8, 16 or 32 bpp
- * \param[in]    left, right, top, bot  amount to set
+ * \param[in]    left, right, top, bot  border region amount to set: these distances are from outside
  * \param[in]    val                    value to set at each border pixel
  * \return  0 if OK; 1 on error
  *
@@ -2196,7 +2196,7 @@ PIX     *pixd;
  *
  * <pre>
  * Notes:
- *      (1) This applies mirrored boundary conditions horizontally
+ *      (1) This applies mirrored boundary conditions (b.c.) horizontally
  *          and repeated b.c. vertically.
  *      (2) It is specifically used for avoiding special operations
  *          near boundaries when convolving a hue-saturation histogram
@@ -2408,7 +2408,7 @@ PIXCMAP   *cmap;
  * Notes:
  *      (1) the 4th byte, sometimes called the "alpha channel",
  *          and which is often used for blending between different
- *          images, is left with 0 value.
+ *          images, is left with 0 value (fully opaque).
  *      (2) see Note (4) in pix.h for details on storage of
  *          8-bit samples within each 32-bit word.
  *      (3) This implementation, setting the r, g and b components

src/pix3.c

@@ -1507,7 +1507,7 @@ pixInvert(PIX  *pixd,
  * <pre>
  * Notes:
  *      (1) This gives the union of two images with equal depth,
- *          aligning them to the the UL corner.  pixs1 and pixs2
+ *          aligning them to the UL corner.  pixs1 and pixs2
  *          need not have the same width and height.
  *      (2) There are 3 cases:
  *            (a) pixd == null,   (src1 | src2) --> new pixd
@@ -1767,7 +1767,7 @@ l_int32  w, h;
  * Notes:
  *      (1) For a binary image, if there are no fg (black) pixels, empty = 1.
  *      (2) For a grayscale image, if all pixels are black (0), empty = 1.
- *      (3) For an RGB image, if all 4 components in every pixel is 0,
+ *      (3) For an RGB image, if all 4 components in every pixel is 0 (i.e. opaque black),
  *          empty = 1.
  *      (4) For a colormapped image, pixel values are 0.  The colormap
  *          is ignored.

src/pixarith.c

@@ -1117,9 +1117,9 @@ PIX       *pixc1, *pixc2, *pixd;
  *          for a 3 component image.  For 32 bpp, ignore the LSB
  *          of each word (the alpha channel)
  *      (3) There are 3 cases:
- *          ~  if pixd == null,   Min(src1, src2) --> new pixd
- *          ~  if pixd == pixs1,  Min(src1, src2) --> src1  (in-place)
- *          ~  if pixd != pixs1,  Min(src1, src2) --> input pixd
+ *          ~  if pixd == null,   MinOrMax(src1, src2) --> new pixd
+ *          ~  if pixd == pixs1,  MinOrMax(src1, src2) --> src1  (in-place)
+ *          ~  if pixd != pixs1,  MinOrMax(src1, src2) --> input pixd
  * </pre>
  */
 PIX *
@@ -1401,7 +1401,7 @@ PIX        *pixd;
  * Notes:
  *      (1) Scales pixel values to fit maximally within a 32 bpp dest pixd
  *      (2) All color components are scaled with the same factor, based
- *          on the maximum r,g or b component in the image.  This should
+ *          on the maximum r, g or b component in the image.  This should
  *          not be used if the 32-bit value is a single number (e.g., a
  *          count in a histogram generated by pixMakeHistoHS()).
  *      (3) Uses a LUT for log scaling.

src/rop.c

@@ -100,7 +100,7 @@ static l_int32 checkRasteropCrop(l_int32 pixw, l_int32 pixh, l_int32 dx,
  *  Three, PIX_CLR, PIX_SET, and PIX_NOT(PIX_DST) operate only on the dest.
  *  These are handled by the low-level rasteropUniLow().
  *
- *  The other 14 involve the both the src and the dest, and depend on
+ *  The other 14 involve both the src and the dest, and depend on
  *  the bit values of either just the src or the bit values of both
  *  src and dest.  They are handled by rasteropLow():
  *