Edit doxygen comments for consistency and style

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

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

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,

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,44 +376,44 @@ 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,
     const char*                      filename,
     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 (
     exr_context_t*                   ctxt,
     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.
  * 

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