diff --git a/src/lib/OpenEXRCore/openexr_attr.h b/src/lib/OpenEXRCore/openexr_attr.h
index a12a251709..f63f2aca0c 100644
--- a/src/lib/OpenEXRCore/openexr_attr.h
+++ b/src/lib/OpenEXRCore/openexr_attr.h
@@ -336,7 +336,7 @@ typedef struct
     exr_attr_string_t name;
     /** Data representation for these pixels: uint, half, float */
     exr_pixel_type_t pixel_type;
-    /** Possible values are 0 and 1 per docs @sa exr_perceptual_treatment_t */
+    /** Possible values are 0 and 1 per docs \ref exr_perceptual_treatment_t */
     uint8_t p_linear;
     uint8_t reserved[3];
     int32_t x_sampling;
@@ -483,7 +483,7 @@ typedef struct _exr_attribute_t
 	 * storing the value you want, with the exception of the pod types
 	 * which are just put in place (i.e. small value optimization)
 	 *
-	 * The attribute type @sa type should directly correlate to one of
+	 * The attribute type \ref type should directly correlate to one of
 	 * these entries
 	 */
     union
diff --git a/src/lib/OpenEXRCore/openexr_base.h b/src/lib/OpenEXRCore/openexr_base.h
index 6b5c1e5011..b455226626 100644
--- a/src/lib/OpenEXRCore/openexr_base.h
+++ b/src/lib/OpenEXRCore/openexr_base.h
@@ -14,7 +14,7 @@
 extern "C" {
 #endif
 
-/** @brief Retrieve the current library version. The 'extra' string is for
+/** @brief Retrieve the current library version. The @p extra string is for
  *  custom installs, and is a static string, do not free the returned pointer */
 EXR_EXPORT void
 exr_get_library_version (int* maj, int* min, int* patch, const char** extra);
@@ -41,24 +41,24 @@ exr_get_library_version (int* maj, int* min, int* patch, const char** extra);
  * potential security issue.
  *
  * These global values are combined with the values in
- * @sa exr_context_initializer using the following rules:
+ * \ref exr_context_initializer_t using the following rules:
  *
- * 1. negative values are ignored
+ * 1. negative values are ignored.
  *
  * 2. if either value has a positive (non-zero) value, and the other
- * has 0, the positive value is preferred.
+ *    has 0, the positive value is preferred.
  *
- * 3. If both are positive (non-zero), the minimum value is used
+ * 3. If both are positive (non-zero), the minimum value is used.
  *
  * 4. If both values are 0, this disables the constrained size checks.
  *
- * This function does not fail
+ * This function does not fail.
  */
 EXR_EXPORT void exr_set_default_maximum_image_size (int w, int h);
 
 /** @brief Retrieve the global default maximum image size
  *
- * This function does not fail
+ * This function does not fail.
  */
 EXR_EXPORT void exr_get_default_maximum_image_size (int* w, int* h);
 
@@ -82,24 +82,24 @@ EXR_EXPORT void exr_get_default_maximum_image_size (int* w, int* h);
  * potential security issue.
  *
  * These global values are combined with the values in
- * @sa exr_context_initializer using the following rules:
+ * \ref exr_context_initializer_t using the following rules:
  *
- * 1. negative values are ignored
+ * 1. negative values are ignored.
  *
  * 2. if either value has a positive (non-zero) value, and the other
  * has 0, the positive value is preferred.
  *
- * 3. If both are positive (non-zero), the minimum value is used
+ * 3. If both are positive (non-zero), the minimum value is used.
  *
  * 4. If both values are 0, this disables the constrained size checks.
  *
- * This function does not fail
+ * This function does not fail.
  */
 EXR_EXPORT void exr_set_default_maximum_tile_size (int w, int h);
 
 /** @brief Retrieve the global maximum tile size.
  *
- * This function does not fail
+ * This function does not fail.
  */
 EXR_EXPORT void exr_get_default_maximum_tile_size (int* w, int* h);
 
@@ -115,7 +115,7 @@ EXR_EXPORT void exr_get_default_maximum_tile_size (int* w, int* h);
  * handle, or NULL if allocation failed (which the library will then
  * handle and return an out-of-memory error).
  *
- * If providing one, probably need to provide both routines.
+ * If one is provided, both should be provided.
  * @sa exr_memory_free_func_t
  */
 typedef void* (*exr_memory_allocation_func_t) (size_t bytes);
@@ -143,9 +143,9 @@ typedef void (*exr_memory_free_func_t) (void* ptr);
  * however this provides global defaults such that the default can be
  * applied.
  *
- * If either pointer is NULL, the appropriate malloc / free routine will be substituted
+ * If either pointer is 0, the appropriate malloc/free routine will be substituted.
  *
- * This function does not fail
+ * This function does not fail.
  */
 EXR_EXPORT void exr_set_default_memory_routines (
     exr_memory_allocation_func_t alloc_func, exr_memory_free_func_t free_func);
diff --git a/src/lib/OpenEXRCore/openexr_chunkio.h b/src/lib/OpenEXRCore/openexr_chunkio.h
index 24da708ab7..61ac2ae358 100644
--- a/src/lib/OpenEXRCore/openexr_chunkio.h
+++ b/src/lib/OpenEXRCore/openexr_chunkio.h
@@ -25,9 +25,9 @@ typedef struct
 {
     int32_t idx;
 
-    /** for tiles, this is the tilex, for scans it is the x */
+    /** for tiles, this is the tilex; for scans it is the x */
     int32_t start_x;
-    /** for tiles, this is the tiley, for scans it is the scanline y */
+    /** for tiles, this is the tiley; for scans it is the scanline y */
     int32_t start_y;
     int32_t height; /**< for this chunk */
     int32_t width;  /**< for this chunk */
@@ -62,7 +62,7 @@ exr_result_t exr_read_tile_chunk_info (
 
 /** Read the packed data block for a chunk
  *
- * This assumes that the buffer pointed to by @param packed_data is
+ * This assumes that the buffer pointed to by @p packed_data is
  * large enough to hold the chunk block info packed_size bytes
  */
 EXR_EXPORT
@@ -75,8 +75,8 @@ exr_result_t exr_read_chunk (
 /**
  * Read chunk for deep data.
  *
- * allows one to read the packed data, the sample count data, or both.
- * @sa exr_read_chunk also works to read deep data packed data,
+ * This allows one to read the packed data, the sample count data, or both.
+ * \ref exr_read_chunk also works to read deep data packed data,
  * but this is a routine to get the sample count table and the packed
  * data in one go, or if you want to pre-read the sample count data,
  * you can get just that buffer.
@@ -91,15 +91,17 @@ exr_result_t exr_read_deep_chunk (
 
 /**************************************/
 
-/** Initializes a @sa exr_chunk_info_t structure when encoding scanline
+/** Initialize a \ref exr_chunk_info_t structure when encoding scanline
  * data (similar to read but does not do anything with a chunk
- * table) */
+ * table)
+ */
 EXR_EXPORT
 exr_result_t exr_write_scanline_chunk_info (
     exr_context_t ctxt, int part_index, int y, exr_chunk_info_t* cinfo);
 
-/** Initializes a chunk_info_t structure when encoding tiled data
- * (similar to read but does not do anything with a chunk table) */
+/** Initialize a \ref chunk_info_t structure when encoding tiled data
+ * (similar to read but does not do anything with a chunk table)
+ */
 EXR_EXPORT
 exr_result_t exr_write_tile_chunk_info (
     exr_context_t     ctxt,
@@ -110,7 +112,9 @@ exr_result_t exr_write_tile_chunk_info (
     int               levely,
     exr_chunk_info_t* cinfo);
 
-/** y must the appropriate starting y for the specified chunk */
+/**
+ * @p y must the appropriate starting y for the specified chunk
+ */
 EXR_EXPORT
 exr_result_t exr_write_scanline_chunk (
     exr_context_t ctxt,
@@ -119,7 +123,9 @@ exr_result_t exr_write_scanline_chunk (
     const void*   packed_data,
     uint64_t      packed_size);
 
-/** y must the appropriate starting y for the specified chunk */
+/**
+ * @p y must the appropriate starting y for the specified chunk
+ */
 EXR_EXPORT
 exr_result_t exr_write_deep_scanline_chunk (
     exr_context_t ctxt,
diff --git a/src/lib/OpenEXRCore/openexr_context.h b/src/lib/OpenEXRCore/openexr_context.h
index ce858373d7..39389896d1 100644
--- a/src/lib/OpenEXRCore/openexr_context.h
+++ b/src/lib/OpenEXRCore/openexr_context.h
@@ -173,7 +173,7 @@ typedef int64_t (*exr_write_func_ptr_t) (
  *
  * The size member is required for version portability
  *
- * It can be initialized using @sa EXR_DEFAULT_CONTEXT_INITIALIZER
+ * It can be initialized using \ref EXR_DEFAULT_CONTEXT_INITIALIZER
  *
  * \code{.c}
  * exr_context_initializer_t myctxtinit = DEFAULT_CONTEXT_INITIALIZER;
@@ -213,7 +213,7 @@ typedef struct _exr_context_initializer
      * This is only used during read or update contexts. If this is
      * provided, it is expected that the caller has previously made
      * the stream available, and placed whatever stream / file data
-     * into @sa user_data above.
+     * into \ref user_data above.
      *
      * If this is NULL, and the context requested is for reading an
      * exr file, an internal implementation is provided for reading
@@ -249,7 +249,7 @@ typedef struct _exr_context_initializer
      * This is only used during write or update contexts. If this is
      * provided, it is expected that the caller has previously made
      * the stream available, and placed whatever stream / file data
-     * into @sa user_data above.
+     * into \ref user_data above.
      *
      * If this is NULL, and the context requested is for writing an
      * exr file, an internal implementation is provided for reading
@@ -272,19 +272,19 @@ typedef struct _exr_context_initializer
     exr_destroy_stream_func_ptr_t destroy_fn;
 
     /** initializes a field specifying what the maximum image width
-     * allowed by the context is. @sa exr_set_maximum_image_size to
+     * allowed by the context is. See \ref exr_set_default_maximum_image_size to
      * understand how this interacts with global defaults */
     int max_image_width;
     /** initializes a field specifying what the maximum image height
-     * allowed by the context is. @sa exr_set_maximum_image_size to
+     * allowed by the context is. See \ref exr_set_default_maximum_image_size to
      * understand how this interacts with global defaults */
     int max_image_height;
     /** initializes a field specifying what the maximum tile width
-     * allowed by the context is. @sa exr_set_maximum_tile_size to
+     * allowed by the context is. See \ref exr_set_default_maximum_tile_size to
      * understand how this interacts with global defaults */
     int max_tile_width;
     /** initializes a field specifying what the maximum tile height
-     * allowed by the context is. @sa exr_set_maximum_tile_size to
+     * allowed by the context is. See \ref exr_set_default_maximum_tile_size to
      * understand how this interacts with global defaults */
     int max_tile_height;
 } exr_context_initializer_t;
@@ -297,23 +297,23 @@ typedef struct _exr_context_initializer
 
 /** @} */ /* context function pointer declarations */
 
-/** @brief Checks the magic number of the file and reports
- * EXR_ERR_SUCCESS if the file appears to be a valid file (or at least
+/** @brief Check the magic number of the file and report
+ * `EXR_ERR_SUCCESS` if the file appears to be a valid file (or at least
  * has the correct magic number and can be read)
  */
 EXR_EXPORT exr_result_t exr_test_file_header (
     const char*                      filename,
     const exr_context_initializer_t* ctxtdata);
 
-/** @brief Closes and frees any internally allocated memory,
+/** @brief Close and free any internally allocated memory,
  * calling any provided destroy function for custom streams
  *
- * If the file was opened for write, will first save the chunk offsets
+ * If the file was opened for write, first save the chunk offsets
  * or any other unwritten data.
  */
 EXR_EXPORT exr_result_t exr_finish (exr_context_t* ctxt);
 
-/** @brief Creates and initializes a read-only exr read context.
+/** @brief Create and initialize a read-only exr read context
  *
  * If a custom read function is provided, the filename is for
  * informational purposes only, the system assumes the user has
@@ -326,12 +326,12 @@ EXR_EXPORT exr_result_t exr_finish (exr_context_t* ctxt);
  * provide a safe context for multiple threads to request data from
  * the same context concurrently.
  *
- * Once finished reading data, use @sa exr_context_finish to clean up
+ * Once finished reading data, use \ref exr_finish to clean up
  * the context.
  *
  * If you have custom I/O requirements, see the initializer context
- * documentation @sa exr_context_initializer_t. The ctxtdata parameter
- * is optional, if NULL, default values will be used.
+ * documentation \ref exr_context_initializer_t. The @p ctxtdata parameter
+ * is optional, if `NULL`, default values will be used.
  */
 EXR_EXPORT exr_result_t exr_start_read (
     exr_context_t*                   ctxt,
@@ -350,7 +350,7 @@ enum exr_default_write_mode
 /** @brief Creates and initializes a write-only context. 
  *
  * If a custom write function is provided, the filename is for
- * informational purposes only, and the default_mode parameter will be
+ * informational purposes only, and the @p default_mode parameter will be
  * ignored. As such, the system assumes the user has previously opened
  * a stream, file, or whatever and placed relevant data in userdata to
  * access that.
@@ -376,13 +376,13 @@ enum exr_default_write_mode
  * temporarily cache chunks until the data is received to flush in
  * order. The concurrency around this is handled by the library
  *
- * 6. Once finished writing data, use @sa exr_context_finish to clean
+ * 6. Once finished writing data, use \ref exr_finish to clean
  * up the context, which will flush any unwritten data such as the
  * final chunk offset tables, and handle the temporary file flags.
  *
  * If you have custom I/O requirements, see the initializer context
- * documentation @sa exr_context_initializer_t. The ctxtdata parameter
- * is optional, if NULL, default values will be used.
+ * documentation \ref exr_context_initializer_t. The @p ctxtdata
+ * parameter is optional, if NULL, default values will be used.
  */
 EXR_EXPORT exr_result_t exr_start_write (
     exr_context_t*                   ctxt,
@@ -390,14 +390,14 @@ EXR_EXPORT exr_result_t exr_start_write (
     enum exr_default_write_mode      default_mode,
     const exr_context_initializer_t* ctxtdata);
 
-/** @brief Creates a new context for updating an exr file in place.
+/** @brief Creates a new context for updating an exr file in place
  *
  * This is a custom mode that allows one to modify the value of a
  * metadata entry, although not to change the size of the header, or
  * any of the image data.
  *
  * If you have custom I/O requirements, see the initializer context
- * documentation @sa exr_context_initializer_t. The ctxtdata parameter
+ * documentation \ref exr_context_initializer_t. The @p ctxtdata parameter
  * is optional, if NULL, default values will be used.
  */
 EXR_EXPORT exr_result_t exr_start_inplace_header_update (
@@ -405,15 +405,15 @@ EXR_EXPORT exr_result_t exr_start_inplace_header_update (
     const char*                      filename,
     const exr_context_initializer_t* ctxtdata);
 
-/** @brief retrieves the file name the context is for as provided
+/** @brief Retrieve the file name the context is for as provided
  * during the start routine.
  *
- * do not free the resulting string.
+ * Do not free the resulting string.
  */
 EXR_EXPORT exr_result_t
 exr_get_file_name (exr_const_context_t ctxt, const char** name);
 
-/** @brief query the user data the context was constructed with. This
+/** @brief Query the user data the context was constructed with. This
  * is perhaps useful in the error handler callback to jump back into
  * an object the user controls.
  */
@@ -457,13 +457,13 @@ EXR_EXPORT exr_result_t exr_register_attr_type_handler (
 EXR_EXPORT exr_result_t
 exr_set_longname_support (exr_context_t ctxt, int onoff);
 
-/** @brief Writes the header data.
+/** @brief Write the header data
  *
  * Opening a new output file has a small initialization state problem
  * compared to opening for read / update: we need to enable the user
  * to specify an arbitrary set of metadata across an arbitrary number
  * of parts. To avoid having to create the list of parts and entire
- * metadata up front, prior to calling the above @sa exr_start_write,
+ * metadata up front, prior to calling the above \ref exr_start_write,
  * allow the data to be set, then once this is called, it switches
  * into a mode where the library assumes the data is now valid.
  * 
diff --git a/src/lib/OpenEXRCore/openexr_debug.h b/src/lib/OpenEXRCore/openexr_debug.h
index 20d1bc417e..ac8c230bb7 100644
--- a/src/lib/OpenEXRCore/openexr_debug.h
+++ b/src/lib/OpenEXRCore/openexr_debug.h
@@ -12,7 +12,9 @@
 extern "C" {
 #endif
 
-/** Debug function, prints to stdout the parts and attributes of the context passed in */
+/** Debug function: print to stdout the parts and attributes of the
+ * context @p c
+ */
 EXR_EXPORT exr_result_t exr_print_context_info( exr_const_context_t c, int verbose );
 
 #ifdef __cplusplus
diff --git a/src/lib/OpenEXRCore/openexr_decode.h b/src/lib/OpenEXRCore/openexr_decode.h
index 4adc8e4ae3..2a7c1a0d5f 100644
--- a/src/lib/OpenEXRCore/openexr_decode.h
+++ b/src/lib/OpenEXRCore/openexr_decode.h
@@ -62,12 +62,12 @@ typedef struct _exr_decode_pipeline
      *
      * User is expected to fill the channel pointers for the desired
      * output channels (any that are NULL will be skipped) if you are
-     * going to use @sa exr_choose_unpack_routine. If all that is
+     * going to use \ref exr_choose_unpack_routine. If all that is
      * desired is to read and decompress the data, this can be left
      * uninitialized.
      *
      * Describes the channel information. This information is
-     * allocated dynamically during @sa exr_initialize_decoding
+     * allocated dynamically during \ref exr_initialize_decoding
      */
     exr_coding_channel_info_t* channels;
     int16_t                    channel_count;
@@ -175,7 +175,7 @@ typedef struct _exr_decode_pipeline
      * Function chosen to read chunk data from the context.
      *
      * Initialized to a default generic read routine, may be updated
-     * based on channel information when @sa
+     * based on channel information when \ref
      * exr_choose_default_routines is called. This is done such that
      * if the file is uncompressed and the output channel data is
      * planar and the same type, the read function can read straight
@@ -215,7 +215,7 @@ typedef struct _exr_decode_pipeline
      *
      * This will be NULL after initialization, until the user
      * specifies a custom routine, or initializes the channel data and
-     * calls @sa exr_choose_unpack_routine.
+     * calls \ref exr_choose_unpack_routine.
      *
      * If only compressed data is desired, then leave or assign this
      * to NULL after initialization.
@@ -239,11 +239,12 @@ typedef struct _exr_decode_pipeline
         0                                                                      \
     }
 
-/** initializes the decoding pipeline structure with the channel info for the specified part, and the first block to be read.
+/** Initialize the decoding pipeline structure with the channel info
+ * for the specified part, and the first block to be read.
  *
- * NB: The unpack_and_convert_fn will be NULL after this. If that
+ * NB: The \ref unpack_and_convert_fn will be NULL after this. If that
  * stage is desired, initialize the channel output information and
- * call @sa exr_choose_unpack_routine
+ * call \ref exr_choose_unpack_routine
  */
 EXR_EXPORT
 exr_result_t exr_decoding_initialize (
@@ -252,17 +253,19 @@ exr_result_t exr_decoding_initialize (
     const exr_chunk_info_t* cinfo,
     exr_decode_pipeline_t*  decode);
 
-/** Given an initialized decode pipeline, finds appropriate functions
+/** Given an initialized decode pipeline, find appropriate functions
  * to read and shuffle / convert data into the defined channel outputs
  *
- * Calling this is not required if custom routines will be used, or
- * if just the raw compressed data is desired. Although in that scenario, it is probably easier to just read the chunk directly using @sa exr_read_chunk
+ * Calling this is not required if custom routines will be used, or if
+ * just the raw compressed data is desired. Although in that scenario,
+ * it is probably easier to just read the chunk directly using \ref
+ * exr_read_chunk
  */
 EXR_EXPORT
 exr_result_t exr_decoding_choose_default_routines (
     exr_const_context_t ctxt, int part_index, exr_decode_pipeline_t* decode);
 
-/** Given a decode pipeline previously initialized, updates it for the
+/** Given a decode pipeline previously initialized, update it for the
  * new chunk to be read.
  *
  * In this manner, memory buffers can be re-used to avoid continual
@@ -283,7 +286,7 @@ exr_result_t exr_decoding_run (
 
 /** Free any intermediate memory in the decoding pipeline
  *
- * This does NOT free any pointers referred to in the channel info
+ * This does *not* free any pointers referred to in the channel info
  * areas, but rather only the intermediate buffers and memory needed
  * for the structure itself.
  */
diff --git a/src/lib/OpenEXRCore/openexr_encode.h b/src/lib/OpenEXRCore/openexr_encode.h
index f21a8dec5e..978db7c51a 100644
--- a/src/lib/OpenEXRCore/openexr_encode.h
+++ b/src/lib/OpenEXRCore/openexr_encode.h
@@ -57,11 +57,11 @@ typedef struct _exr_encode_pipeline
      *
      * User is expected to fill the channel pointers for the input
      * channels. For writing, all channels must be initialized prior
-     * to using @sa exr_choose_pack_routine. If a custom pack routine
+     * to using \ref exr_choose_pack_routine. If a custom pack routine
      * is written, that is up to the implementor.
      *
      * Describes the channel information. This information is
-     * allocated dynamically during @sa exr_initialize_encoding
+     * allocated dynamically during \ref exr_initialize_encoding
      */
     exr_coding_channel_info_t* channels;
     int16_t                    channel_count;
@@ -271,12 +271,12 @@ typedef struct _exr_encode_pipeline
         0                                                                      \
     }
 
-/** initializes the encoding pipeline structure with the channel info
- * for the specified part based on the chunk to be written.
+/** Initialize the encoding pipeline structure with the channel info
+ * for the specified part based on the chunk to be written
  *
- * NB: The pack_and_convert_fn will be NULL after this. If that
+ * NB: The \ref pack_and_convert_fn will be NULL after this. If that
  * stage is desired, initialize the channel output information and
- * call @sa exr_choose_unpack_routine
+ * call \ref exr_choose_unpack_routine
  */
 EXR_EXPORT
 exr_result_t exr_encoding_initialize (
@@ -285,7 +285,7 @@ exr_result_t exr_encoding_initialize (
     const exr_chunk_info_t* cinfo,
     exr_encode_pipeline_t*  encode_pipe);
 
-/** Given an initialized encode pipeline, finds an appropriate
+/** Given an initialized encode pipeline, find an appropriate
  * function to shuffle and convert data into the defined channel
  * outputs
  *
@@ -298,7 +298,7 @@ exr_result_t exr_encoding_choose_default_routines (
     int                    part_index,
     exr_encode_pipeline_t* encode_pipe);
 
-/** Given a encode pipeline previously initialized, updates it for the
+/** Given a encode pipeline previously initialized, update it for the
  * new chunk to be written.
  *
  * In this manner, memory buffers can be re-used to avoid continual
diff --git a/src/lib/OpenEXRCore/openexr_errors.h b/src/lib/OpenEXRCore/openexr_errors.h
index bb42295978..95e5e1a739 100644
--- a/src/lib/OpenEXRCore/openexr_errors.h
+++ b/src/lib/OpenEXRCore/openexr_errors.h
@@ -66,15 +66,15 @@ typedef enum
 /** Return type for all functions */
 typedef int32_t exr_result_t;
 
-/** @brief Returns a static string corresponding to the specified error code.
+/** @brief Return a static string corresponding to the specified error code
  *
- * The string should not be freed (it is compiled into the binary)
+ * The string should not be freed (it is compiled into the binary).
  */
 EXR_EXPORT const char* exr_get_default_error_message (exr_result_t code);
 
-/** @brief Returns a static string corresponding to the specified error code.
+/** @brief Return a static string corresponding to the specified error code
  *
- * The string should not be freed (it is compiled into the binary)
+ * The string should not be freed (it is compiled into the binary).
  */
 EXR_EXPORT const char* exr_get_error_code_as_string (exr_result_t code);
 
diff --git a/src/lib/OpenEXRCore/openexr_part.h b/src/lib/OpenEXRCore/openexr_part.h
index 08c166b5f3..0e366d8ccc 100644
--- a/src/lib/OpenEXRCore/openexr_part.h
+++ b/src/lib/OpenEXRCore/openexr_part.h
@@ -41,7 +41,7 @@ EXR_EXPORT exr_result_t exr_get_count (exr_const_context_t ctxt, int* count);
 /** @brief Query the part name for the specified part
  *
  * NB: If this file is a single part file and name has not been set, this
- * will output NULL
+ * will return NULL.
  */
 EXR_EXPORT exr_result_t
 exr_get_name (exr_const_context_t ctxt, int part_index, const char** out);
@@ -50,7 +50,7 @@ exr_get_name (exr_const_context_t ctxt, int part_index, const char** out);
 EXR_EXPORT exr_result_t
 exr_get_storage (exr_const_context_t ctxt, int part_index, exr_storage_t* out);
 
-/** @brief Define a new part in the file. */
+/** @brief Define a new part in the file */
 EXR_EXPORT exr_result_t exr_add_part (
     exr_context_t ctxt,
     const char*   partname,
@@ -59,12 +59,12 @@ EXR_EXPORT exr_result_t exr_add_part (
 
 /** @brief Query how many levels are in the specified part.
  *
- * If the part is a tiled part, fills in how many tile levels are present.
+ * If the part is a tiled part, fill in how many tile levels are present.
  *
- * return ERR_SUCCESS on sucess, an error otherwise (i.e. if the part
- * is not tiled)
+ * Return `ERR_SUCCESS` on success, an error otherwise (i.e. if the part
+ * is not tiled).
  *
- * it is valid to pass NULL to either of the levelsx or levelsy
+ * It is valid to pass NULL to either of the @p levelsx or @p levelsy
  * arguments, which enables testing if this part is a tiled part, or
  * if you don't need both (i.e. in the case of a mip-level tiled
  * image)
@@ -75,14 +75,15 @@ EXR_EXPORT exr_result_t exr_get_tile_levels (
     int32_t*            levelsx,
     int32_t*            levelsy);
 
-/** @brief Query the tile size for a particular level in the specified part.
+/** @brief Query the tile size for a particular level in the specified part
  *
- * If the part is a tiled part, fills in the tile size for the specified part / level
+ * If the part is a tiled part, fill in the tile size for the
+ * specified part / level.
  *
- * return ERR_SUCCESS on sucess, an error otherwise (i.e. if the part
- * is not tiled)
+ * Return `ERR_SUCCESS` on `success`, an error otherwise (i.e. if the
+ * part is not tiled).
  *
- * it is valid to pass NULL to either of the tilew or tileh
+ * It is valid to pass NULL to either of the @p tilew or @p tileh
  * arguments, which enables testing if this part is a tiled part, or
  * if you don't need both (i.e. in the case of a mip-level tiled
  * image)
@@ -95,15 +96,15 @@ EXR_EXPORT exr_result_t exr_get_tile_sizes (
     int32_t*            tilew,
     int32_t*            tileh);
 
-/** @brief Query the data sizes for a particular level in the specified part.
+/** @brief Query the data sizes for a particular level in the specified part
  *
- * If the part is a tiled part, fills in the width / height for the
- * specified levels
+ * If the part is a tiled part, fill in the width / height for the
+ * specified levels.
  *
- * return ERR_SUCCESS on sucess, an error otherwise (i.e. if the part
+ * Return `ERR_SUCCESS` on success, an error otherwise (i.e. if the part
  * is not tiled)
  *
- * it is valid to pass NULL to either of the levw or levh
+ * It is valid to pass NULL to either of the @p levw or @p levh
  * arguments, which enables testing if this part is a tiled part, or
  * if you don't need both for some reason
  */
@@ -139,7 +140,7 @@ exr_get_chunk_count (exr_const_context_t ctxt, int part_index, int32_t* out);
 EXR_EXPORT exr_result_t exr_get_scanlines_per_chunk (
     exr_const_context_t ctxt, int part_index, int32_t* out);
 
-/** returns the maximum unpacked size of a chunk for the file part.
+/** Return the maximum unpacked size of a chunk for the file part
  *
  * This may be used ahead of any actual reading of data, so can be
  * used to pre-allocate buffers for multiple threads in one block or
@@ -182,11 +183,11 @@ EXR_EXPORT exr_result_t exr_get_attribute_by_name (
 
 /** @brief Query the list of attributes in a part
  *
- * This retrieves a list of attributes currently defined in a part
+ * This retrieves a list of attributes currently defined in a part.
  *
- * if outlist is NULL, this function still succeeds, filling only the
+ * If outlist is NULL, this function still succeeds, filling only the
  * count. In this manner, the user can allocate memory for the list of
- * attributes, then re-call this function to get the full list
+ * attributes, then re-call this function to get the full list.
  */
 EXR_EXPORT exr_result_t exr_get_attribute_list (
     exr_const_context_t            ctxt,
@@ -195,7 +196,7 @@ EXR_EXPORT exr_result_t exr_get_attribute_list (
     int32_t*                       count,
     const exr_attribute_t**        outlist);
 
-/** Declare an attribute within the specified part.
+/** Declare an attribute within the specified part
  *
  * Only valid when a file is opened for write.
  */
@@ -206,7 +207,7 @@ EXR_EXPORT exr_result_t exr_attr_declare_by_type (
     const char*       type,
     exr_attribute_t** newattr);
 
-/** @brief Declare an attribute within the specified part.
+/** @brief Declare an attribute within the specified part
  *
  * Only valid when a file is opened for write.
  */
@@ -226,10 +227,10 @@ EXR_EXPORT exr_result_t exr_attr_declare (
  * @{
  */
 
-/** @brief initialize all required attributes for all files.
+/** @brief Initialize all required attributes for all files
  *
  * NB: other file types do require other attributes, such as the tile
- * description for a tiled file
+ * description for a tiled file.
  */
 EXR_EXPORT exr_result_t exr_initialize_required_attr (
     exr_context_t           ctxt,
@@ -242,15 +243,15 @@ EXR_EXPORT exr_result_t exr_initialize_required_attr (
     exr_lineorder_t         lineorder,
     exr_compression_t       ctype);
 
-/** @brief initializes all required attributes to default values
+/** @brief Initialize all required attributes to default values:
  *
- * displayWindow is set to (0, 0 -> width - 1, height - 1)
- * dataWindow is set to (0, 0 -> width - 1, height - 1)
- * pixelAspectRatio is set to 1.0
- * screenWindowCenter is set to 0.f, 0.f
- * screenWindowWidth is set to 1.f
- * lineorder is set to INCREASING_Y
- * compression is set to @p ctype
+ * - `displayWindow` is set to (0, 0 -> @p width - 1, @p height - 1)
+ * - `dataWindow` is set to (0, 0 -> @p width - 1, @p height - 1)
+ * - `pixelAspectRatio` is set to 1.0
+ * - `screenWindowCenter` is set to 0.f, 0.f
+ * - `screenWindowWidth` is set to 1.f
+ * - `lineorder` is set to `INCREASING_Y`
+ * - `compression` is set to @p ctype
  */
 EXR_EXPORT exr_result_t exr_initialize_required_attr_simple (
     exr_context_t     ctxt,
@@ -278,16 +279,16 @@ EXR_EXPORT exr_result_t exr_copy_unset_attributes (
     exr_const_context_t source,
     int                 src_part_index);
 
-/** @brief retrieves the list of channels */
+/** @brief Retrieve the list of channels */
 EXR_EXPORT exr_result_t exr_get_channels (
     exr_const_context_t ctxt, int part_index, const exr_attr_chlist_t** chlist);
 
-/** @brief Defines a new channel to the output file part.
+/** @brief Define a new channel to the output file part
  *
- * the @param percept parameter is used for lossy compression
- * techniques to indicate that the value represented is closer to
- * linear (1) or closer to logarithmic (0). For r, g, b, luminance,
- * this is normally 0
+ * The @p percept parameter is used for lossy compression techniques
+ * to indicate that the value represented is closer to linear (1) or
+ * closer to logarithmic (0). For r, g, b, luminance, this is normally
+ * 0
  */
 EXR_EXPORT int exr_add_channel (
     exr_context_t              ctxt,
@@ -298,63 +299,64 @@ EXR_EXPORT int exr_add_channel (
     int32_t                    xsamp,
     int32_t                    ysamp);
 
-/** @brief Copies the channels from another source.
+/** @brief Copy the channels from another source
  *
  * Useful if you are manually constructing the list or simply copying
- * from an input file */
+ * from an input file
+ */
 EXR_EXPORT exr_result_t exr_set_channels (
     exr_context_t ctxt, int part_index, const exr_attr_chlist_t* channels);
 
-/** @brief Retrieves the compression method used for the specified part. */
+/** @brief Retrieve the compression method used for the specified part */
 EXR_EXPORT exr_result_t exr_get_compression (
     exr_const_context_t ctxt, int part_index, exr_compression_t* compression);
-/** @brief Sets the compression method used for the specified part. */
+/** @brief Set the compression method used for the specified part */
 EXR_EXPORT exr_result_t exr_set_compression (
     exr_context_t ctxt, int part_index, exr_compression_t ctype);
 
-/** @brief Retrieves the data window for the specified part. */
+/** @brief Retrieve the data window for the specified part */
 EXR_EXPORT exr_result_t exr_get_data_window (
     exr_const_context_t ctxt, int part_index, exr_attr_box2i_t* out);
-/** @brief Sets the data window for the specified part. */
+/** @brief Set the data window for the specified part */
 EXR_EXPORT int exr_set_data_window (
     exr_context_t ctxt, int part_index, const exr_attr_box2i_t* dw);
 
-/** @brief Retrieves the display window for the specified part. */
+/** @brief Retrieve the display window for the specified part */
 EXR_EXPORT exr_result_t exr_get_display_window (
     exr_const_context_t ctxt, int part_index, exr_attr_box2i_t* out);
-/** @brief Sets the display window for the specified part. */
+/** @brief Set the display window for the specified part */
 EXR_EXPORT int exr_set_display_window (
     exr_context_t ctxt, int part_index, const exr_attr_box2i_t* dw);
 
-/** @brief Retrieves the line order for storing data in the specified part (use 0 for single part images). */
+/** @brief Retrieve the line order for storing data in the specified part (use 0 for single part images) */
 EXR_EXPORT exr_result_t exr_get_lineorder (
     exr_const_context_t ctxt, int part_index, exr_lineorder_t* out);
-/** @brief Sets the line order for storing data in the specified part (use 0 for single part images). */
+/** @brief Set the line order for storing data in the specified part (use 0 for single part images) */
 EXR_EXPORT exr_result_t
 exr_set_lineorder (exr_context_t ctxt, int part_index, exr_lineorder_t lo);
 
-/** @brief Retrieves the pixel aspect ratio for the specified part (use 0 for single part images). */
+/** @brief Retrieve the pixel aspect ratio for the specified part (use 0 for single part images). */
 EXR_EXPORT exr_result_t exr_get_pixel_aspect_ratio (
     exr_const_context_t ctxt, int part_index, float* par);
-/** @brief Sets the pixel aspect ratio for the specified part (use 0 for single part images). */
+/** @brief Set the pixel aspect ratio for the specified part (use 0 for single part images) */
 EXR_EXPORT exr_result_t
 exr_set_pixel_aspect_ratio (exr_context_t ctxt, int part_index, float par);
 
-/** @brief Retrieves the screen oriented window center for the specified part (use 0 for single part images). */
+/** @brief Retrieve the screen oriented window center for the specified part (use 0 for single part images) */
 EXR_EXPORT exr_result_t exr_get_screen_window_center (
     exr_const_context_t ctxt, int part_index, exr_attr_v2f_t* wc);
-/** @brief Sets the screen oriented window center for the specified part (use 0 for single part images). */
+/** @brief Set the screen oriented window center for the specified part (use 0 for single part images) */
 EXR_EXPORT int exr_set_screen_window_center (
     exr_context_t ctxt, int part_index, const exr_attr_v2f_t* wc);
 
-/** @brief Retrieves the screen oriented window width for the specified part (use 0 for single part images). */
+/** @brief Retrieve the screen oriented window width for the specified part (use 0 for single part images) */
 EXR_EXPORT exr_result_t exr_get_screen_window_width (
     exr_const_context_t ctxt, int part_index, float* out);
-/** @brief Sets the screen oriented window width for the specified part (use 0 for single part images). */
+/** @brief Set the screen oriented window width for the specified part (use 0 for single part images) */
 EXR_EXPORT exr_result_t
 exr_set_screen_window_width (exr_context_t ctxt, int part_index, float ssw);
 
-/** @brief Retrieves the tiling info for a tiled part (use 0 for single part images). */
+/** @brief Retrieve the tiling info for a tiled part (use 0 for single part images) */
 EXR_EXPORT exr_result_t exr_get_tile_descriptor (
     exr_const_context_t    ctxt,
     int                    part_index,
@@ -363,7 +365,7 @@ EXR_EXPORT exr_result_t exr_get_tile_descriptor (
     exr_tile_level_mode_t* level,
     exr_tile_round_mode_t* round);
 
-/** @brief Sets the tiling info for a tiled part (use 0 for single part images). */
+/** @brief Set the tiling info for a tiled part (use 0 for single part images) */
 EXR_EXPORT exr_result_t exr_set_tile_descriptor (
     exr_context_t         ctxt,
     int                   part_index,
@@ -387,9 +389,9 @@ exr_set_chunk_count (exr_context_t ctxt, int part_index, int32_t val);
 /** @} */ /* required attr group */
 
 /** 
- * @defgroup BuiltinAttributeHelpers Attribute Utililities for builtin types
+ * @defgroup BuiltinAttributeHelpers Attribute utilities for builtin types
  *
- * @brief These are a group of functions for attributes that use the builtin types
+ * @brief These are a group of functions for attributes that use the builtin types.
  *
  * @{
  */
@@ -418,11 +420,10 @@ EXR_EXPORT exr_result_t exr_attr_set_box2f (
     const char*             name,
     const exr_attr_box2f_t* val);
 
-/** @brief zero copy query of channel data.
- *
+/** @brief Zero-copy query of channel data
  *
- * Do not free or manipulate the const exr_attr_chlist_t data, or use
- * after the lifetime of the context
+ * Do not free or manipulate the @p chlist data, or use
+ * after the lifetime of the context.
  */
 EXR_EXPORT exr_result_t exr_attr_get_channels (
     exr_const_context_t       ctxt,
@@ -484,10 +485,10 @@ EXR_EXPORT exr_result_t exr_attr_get_float (
 EXR_EXPORT exr_result_t exr_attr_set_float (
     exr_context_t ctxt, int part_index, const char* name, float val);
 
-/** @brief zero copy query of float data.
+/** @brief Zero-copy query of float data
  *
- * Do not free or manipulate the const float * data, or use after the
- * lifetime of the context
+ * Do not free or manipulate the @p out data, or use after the
+ * lifetime of the context.
  */
 EXR_EXPORT exr_result_t exr_attr_get_float_vector (
     exr_const_context_t ctxt,
@@ -602,10 +603,10 @@ EXR_EXPORT exr_result_t exr_attr_set_rational (
     const char*                name,
     const exr_attr_rational_t* r);
 
-/** @brief zero copy query of string value.
+/** @brief Zero-copy query of string value
  *
  * Do not modify the string pointed to by @p out, and do not use
- * after the lifetime of the context
+ * after the lifetime of the context.
  */
 EXR_EXPORT exr_result_t exr_attr_get_string (
     exr_const_context_t ctxt,
@@ -617,14 +618,14 @@ EXR_EXPORT exr_result_t exr_attr_get_string (
 EXR_EXPORT exr_result_t exr_attr_set_string (
     exr_context_t ctxt, int part_index, const char* name, const char* s);
 
-/** @brief zero copy query of string data.
+/** @brief Zero-copy query of string data
  *
  * Do not free the strings pointed to by the array.
  *
- * Must provide @p size
+ * Must provide @p size.
  *
- * @param out must be a const char** array large enough to hold the
- * string pointers for the string vector when provided
+ * @param out must be a ``const char**`` array large enough to hold
+ * the string pointers for the string vector when provided.
  */
 EXR_EXPORT exr_result_t exr_attr_get_string_vector (
     exr_const_context_t ctxt,