docs: update IC docs, clean up outdated docs, and fix typos

CONTRIBUTING.md

@@ -246,7 +246,7 @@ It is also encouraged, when it makes sense to do so, to put a subcategory in
 parenthesis after the prefix, like `fix(exr):` or `feat(IBA):`. It's ok to use
 obvious abbreviations for major classes or subsections: IB=ImageBuf,
 IBA=ImageBufAlgo, IC=ImageCache, TS=TextureSystem, etc. If there is no clear
-single format or class that is the man focus of the patch, then you can omit
+single format or class that is the main focus of the patch, then you can omit
 the subcategory.
 
 API or ABI-breaking changes should additionally be marked with an exclamation

src/include/OpenImageIO/imagebuf.h

@@ -1161,7 +1161,7 @@ class OIIO_API ImageBuf {
                     stride_t ystride      = AutoStride,
                     stride_t zstride      = AutoStride);
 
-    /// Potentially unsafe set_pixels() using raw pointers. Use with catution!
+    /// Potentially unsafe set_pixels() using raw pointers. Use with caution!
     OIIO_IB_DEPRECATE_RAW_PTR
     bool set_pixels(ROI roi, TypeDesc format, const void* data,
                     stride_t xstride = AutoStride,

src/include/OpenImageIO/imagebufalgo.h

@@ -2674,8 +2674,7 @@ bool OIIO_API deep_merge (ImageBuf &dst, const ImageBuf &A,
 
 
 /// Return the samples of deep image `src` that are closer than the opaque
-/// frontier of deep image holdout, returning true upon success and false
-/// for any failures. Samples of `src` that are farther than the first
+/// frontier of deep image holdout. Samples of `src` that are farther than the first
 /// opaque sample of holdout (for the corresponding pixel) will not be copied
 /// to `dst`. Image holdout is only used as the depth threshold; no sample
 /// values from holdout are themselves copied to `dst`.

src/include/OpenImageIO/imagecache.h

@@ -28,7 +28,7 @@
 OIIO_NAMESPACE_3_1_BEGIN
 
 
-/// Define an API to an abstract class that manages image files,
+/// Define an API to a class that manages image files,
 /// caches of open file handles as well as tiles of pixels so that truly
 /// huge amounts of image data may be accessed by an application with low
 /// memory footprint.
@@ -37,8 +37,7 @@ class OIIO_API ImageCache {
     /// @{
     /// @name Creating and destroying an image cache
     ///
-    /// ImageCache is an abstract API described as a pure virtual class.
-    /// The actual internal implementation is not exposed through the
+    /// ImageCache's actual internal implementation is not exposed through the
     /// external API of OpenImageIO.  Because of this, you cannot construct
     /// or destroy the concrete implementation, so two static methods of
     /// ImageCache are provided:
@@ -499,7 +498,7 @@ class OIIO_API ImageCache {
     ///
     /// 1. Don't worry about it at all: don't use the methods that want
     ///    `Perthread` pointers, or always pass `nullptr` for any
-    ///    `Perthread*1 arguments, and ImageCache will do
+    ///    `Perthread*` arguments, and ImageCache will do
     ///    thread-specific-pointer retrieval as necessary (though at some
     ///    small cost).
     ///
@@ -779,9 +778,9 @@ class OIIO_API ImageCache {
     /// @param  subimage
     ///             The subimage to query.
     /// @returns
-    ///             `true` upon success, `false` upon failure failure (such
+    ///             `true` upon success, `false` upon failure (such
     ///             as being unable to find, open, or read the file, or if
-    ///             it does not contain the designated subimage.
+    ///             it does not contain the designated subimage).
     bool get_imagespec(ustring filename, ImageSpec& spec, int subimage = 0);
     /// A more efficient variety of `get_imagespec()` for cases where you
     /// can use an `ImageHandle*` to specify the image and optionally have a
@@ -871,9 +870,9 @@ class OIIO_API ImageCache {
     /// @param  subimage/miplevel
     ///             The subimage and mip level to query.
     /// @returns
-    ///             `true` upon success, `false` upon failure failure (such
+    ///             `true` upon success, `false` upon failure (such
     ///             as being unable to find, open, or read the file, or if
-    ///             it does not contain the designated subimage or mip level.
+    ///             it does not contain the designated subimage or mip level).
     bool get_cache_dimensions(ustring filename, ImageSpec& spec,
                               int subimage = 0, int miplevel = 0);
     /// A more efficient variety of `get_cache_dimensions()` for cases where
@@ -895,7 +894,7 @@ class OIIO_API ImageCache {
     /// @param  subimage
     ///             The subimage to query.
     /// @returns
-    ///             `true` upon success, `false` upon failure failure (such
+    ///             `true` upon success, `false` upon failure (such
     ///             as being unable to find, open, or read the file, or if
     ///             it does not contain a thumbnail).
     bool get_thumbnail(ustring filename, ImageBuf& thumbnail, int subimage = 0);
@@ -1322,7 +1321,7 @@ class OIIO_API ImageCache {
     std::string getstats(int level = 1) const;
 
     /// Reset most statistics to be as they were with a fresh ImageCache.
-    /// Caveat emptor: this does not flush the cache itelf, so the resulting
+    /// Caveat emptor: this does not flush the cache itself, so the resulting
     /// statistics from the next set of texture requests will not match the
     /// number of tile reads, etc., that would have resulted from a new
     /// ImageCache.

src/include/OpenImageIO/imageio.h

@@ -86,7 +86,7 @@ typedef bool (*ProgressCallback)(void *opaque_data, float portion_done);
 
 
 /// ROI is a small helper struct describing a rectangular region of interest
-/// in an image. The region is [xbegin,xend) x [begin,yend) x [zbegin,zend),
+/// in an image. The region is [xbegin,xend) x [ybegin,yend) x [zbegin,zend),
 /// with the "end" designators signifying one past the last pixel in each
 /// dimension, a la STL style.
 ///
@@ -333,7 +333,7 @@ class OIIO_API ImageSpec {
     /// All other fields are set to the obvious defaults -- the image is an
     /// ordinary 2D image (not a volume), the image is not offset or a crop
     /// of a bigger image, the image is scanline-oriented (not tiled),
-    /// channel names are "R", "G", "B"' and "A" (up to and including 4
+    /// channel names are "R", "G", "B", and "A" (up to and including 4
     /// channels, beyond that they are named "channel *n*"), the fourth
     /// channel (if it exists) is assumed to be alpha.
     ImageSpec (int xres, int yres, int nchans, TypeDesc fmt = TypeUInt8) noexcept;
@@ -366,7 +366,7 @@ class OIIO_API ImageSpec {
     /// Sets the `channelnames` to reasonable defaults for the number of
     /// channels.  Specifically, channel names are set to "R", "G", "B,"
     /// and "A" (up to and including 4 channels, beyond that they are named
-    /// "channel*n*".
+    /// "channel*n*").
     void default_channel_names () noexcept;
 
     /// Returns the number of bytes comprising each channel of each pixel
@@ -3996,7 +3996,7 @@ OIIO_API std::string geterror(bool clear = true);
 ///   But for less sophisticated applications (or users), this is very useful
 ///   for forcing display of error messages so that users can see relevant
 ///   errors even if they never check them explicitly, thus self-diagnose
-///   their troubles before asking the project dev deam for help. Advanced
+///   their troubles before asking the project dev team for help. Advanced
 ///   users who for some reason desire to neither retrieve errors themselves
 ///   nor have them printed in this manner can disable the behavior by setting
 ///   this attribute to 0.
@@ -4011,7 +4011,7 @@ OIIO_API std::string geterror(bool clear = true);
 ///   applications (or users), this is very useful for forcing display of
 ///   error messages so that users can see relevant errors even if they never
 ///   check them explicitly, thus self-diagnose their troubles before asking
-///   the project dev deam for help. Advanced users who for some reason desire
+///   the project dev team for help. Advanced users who for some reason desire
 ///   to neither retrieve errors themselves nor have them printed in this
 ///   manner can disable the behavior by setting this attribute to 0.
 ///
@@ -4183,7 +4183,7 @@ inline bool attribute(string_view name, string_view value) {
 /// - int64_t IB_local_mem_peak
 ///
 ///   Current and peak size (in bytes) of how much memory was consumed by
-///   ImageBufs that owned their own allcoated local pixel buffers. (Added in
+///   ImageBufs that owned their own allocated local pixel buffers. (Added in
 ///   OpenImageIO 2.5.)
 ///
 /// - float IB_total_open_time
@@ -4192,12 +4192,12 @@ inline bool attribute(string_view name, string_view value) {
 ///   Total amount of time (in seconds) that ImageBufs spent opening
 ///   (including reading header information) and reading pixel data from files
 ///   that they opened and read themselves (that is, excluding I/O from IBs
-///   that were backed by ImageCach.  (Added in OpenImageIO 2.5.)
+///   that were backed by ImageCache).  (Added in OpenImageIO 2.5.)
 ///
 /// - `string opencolorio_version`
 ///
 ///   Returns the version (such as "2.2.0") of OpenColorIO that is used by
-///   OpenImageiO, or "0.0.0" if no OpenColorIO support has been enabled.
+///   OpenImageIO, or "0.0.0" if no OpenColorIO support has been enabled.
 ///   (Added in OpenImageIO 2.4.6)
 ///
 /// - `string hw:simd`
@@ -4223,7 +4223,7 @@ inline bool attribute(string_view name, string_view value) {
 ///
 /// - `string build:dependencies` (read-only)
 ///
-///   List of library dependencieis (where known) and versions, separatd by
+///   List of library dependencies (where known) and versions, separated by
 ///   semicolons. (Added in OpenImageIO 2.5.8.)
 ///
 /// - `int resident_memory_used_MB`

src/include/OpenImageIO/span.h

@@ -47,7 +47,7 @@ inline constexpr span_size_t dynamic_extent
 
 
 /// `span<T>` is a non-owning, non-copying, non-allocating reference to a
-/// contiguous array of T objects of known length. A 'span` encapsulates both
+/// contiguous array of T objects of known length. A `span` encapsulates both
 /// a pointer and a length, and thus is a safer way of passing pointers around
 /// (because the function called knows how long the array is). A function
 /// that might ordinarily take a `T*` and a length could instead just take a

src/include/OpenImageIO/strongparam.h

@@ -83,8 +83,8 @@ OIIO_NAMESPACE_3_1_BEGIN
 /// you use it in the function, it implicitly converts to the underlying
 /// base type.
 ///
-/// As an alternative to `OIIO_STRONG_TYPE(Meters, float)`, you may also use
-/// this notation (if you find it more pleasing):
+/// As an alternative to `OIIO_STRONG_PARAM_TYPE(Meters, float)`, you may
+/// also use this notation (if you find it more pleasing):
 ///
 ///     using Meters = StrongParam<struct MetersTag, float>;
 ///

src/libOpenImageIO/imagebuf.cpp

@@ -584,7 +584,7 @@ ImageBufImpl::~ImageBufImpl()
 
     // Upon destruction, print uncaught errors to help users who don't know
     // how to properly check for errors.
-    if (!m_err.empty() /* Note: safe becausethis is the dtr */
+    if (!m_err.empty() /* Note: safe because this is the dtr */
         && OIIO::pvt::imagebuf_print_uncaught_errors) {
         try {
             OIIO::print(

src/libtexture/imagecache_pvt.h

@@ -931,7 +931,7 @@ class ImageCachePerThreadInfo {
 
 
 
-/// Working implementation of the abstract ImageCache class.
+/// Working implementation of the ImageCache class.
 ///
 /// Some of the methods require a pointer to the thread-specific IC data
 /// including microcache and statistics.