Clean up OpenEXRCore doxygen comments (AcademySoftwareFoundation#1130)

* Fix improper use of \ref, etc
* Fix various warnings
* Make consistent use of punctuation, capitalization, and verb tense
* Add entries to reference section in OpenEXRCoreAPI.rst to get proper
  references.

Signed-off-by: Cary Phillips <cary@ilm.com>

docs/OpenEXRCoreAPI.rst

@@ -88,6 +88,7 @@ a sorted order, or the order within which they appear in the file. One
 example might be to retrieve the data window:
 
 .. code-block::
+   :linenos:
 
     exr_attr_box2i_t datawindow;
     exr_result_t rv = exr_get_data_window(ctxt, 0, &datawindow);
@@ -172,6 +173,12 @@ would result from unpacking that chunk, and it’s raw position on disk.
 Reference
 ---------
 
+Basic Types
+^^^^^^^^^^^
+
+.. doxygentypedef:: exr_result_t
+
+
 Basic Enumerated Types
 ^^^^^^^^^^^^^^^^^^^^^^
 
@@ -189,6 +196,9 @@ Basic Enumerated Types
 Global State
 ^^^^^^^^^^^^
 
+.. doxygentypedef:: exr_memory_allocation_func_t
+.. doxygentypedef:: exr_memory_free_func_t
+
 .. doxygenfunction:: exr_get_library_version
 .. doxygenfunction:: exr_set_default_maximum_image_size
 .. doxygenfunction:: exr_get_default_maximum_image_size 
@@ -236,12 +246,17 @@ Open for Write
 Close
 ^^^^^
 
+.. doxygentypedef:: exr_destroy_stream_func_ptr_t
+
 .. doxygenfunction:: exr_finish
 
 
 Context
 ^^^^^^^
 
+.. doxygentypedef:: exr_context_t
+.. doxygentypedef:: exr_const_context_t
+
 .. doxygenstruct:: _exr_context_initializer
    :members:
 .. doxygentypedef:: exr_context_initializer_t
@@ -266,6 +281,8 @@ Decoding
 Encoding
 ^^^^^^^^
 
+.. doxygenenum:: transcoding_pipeline_buffer_id
+
 .. doxygenstruct:: _exr_encode_pipeline
    :members:
 .. doxygentypedef:: exr_encode_pipeline_t
@@ -283,6 +300,8 @@ Encoding
 Attribute Values
 ^^^^^^^^^^^^^^^^
 
+
+
 .. doxygenstruct:: exr_attr_chromaticities_t
    :members:
    :undoc-members:
@@ -297,13 +316,96 @@ Attribute Values
    :members:
    :undoc-members:
 
+.. doxygenstruct:: exr_attr_v2i_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_v2f_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_v2d_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_v3i_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_v3f_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_v3d_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_m33f_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_m33d_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_m44f_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_m44d_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_box2i_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_box2f_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_string_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_string_vector_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_float_vector_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_chlist_entry_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_chlist_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_preview_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_tiledesc_t
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: exr_attr_timecode_t
+   :members:
+   :undoc-members:
+
 .. doxygenstruct:: exr_attr_opaquedata_t
    :members:
    :undoc-members:
 
 Reading
 ^^^^^^^
 
+.. doxygentypedef:: exr_read_func_ptr_t
+.. doxygentypedef:: exr_query_size_func_ptr_t
+
 .. doxygenfunction:: exr_get_count
 .. doxygenfunction:: exr_get_name
 .. doxygenfunction:: exr_get_storage
@@ -368,6 +470,8 @@ Reading
 Writing
 ^^^^^^^
 
+.. doxygentypedef:: exr_write_func_ptr_t
+
 .. doxygenfunction:: exr_add_part
 
 .. doxygenfunction:: exr_add_channel
@@ -421,6 +525,8 @@ Error Handling
 
 .. doxygenenum:: exr_error_code_t
 
+.. doxygentypedef:: exr_error_handler_cb_t
+
 .. doxygenfunction:: exr_get_default_error_message
 .. doxygenfunction:: exr_get_error_code_as_string
 

docs/index.rst

@@ -1,8 +1,5 @@
-.. Imath documentation master file, created by
-   sphinx-quickstart on Wed Apr 24 15:19:01 2019.
-
-OpenEXR Technical Documentation
-===============================
+OpenEXR |version| Technical Documentation
+=========================================
 
 .. sidebar:: OpenEXR
 

src/lib/Iex/IexBaseExc.cpp

@@ -191,6 +191,8 @@ BaseExc::stackTrace () const noexcept
     return _stackTrace;
 }
 
+/// @cond Doxygen_Suppress
+
 DEFINE_EXC_EXP_IMPL (IEX_EXPORT, ArgExc, BaseExc)
 DEFINE_EXC_EXP_IMPL (IEX_EXPORT, LogicExc, BaseExc)
 DEFINE_EXC_EXP_IMPL (IEX_EXPORT, InputExc, BaseExc)
@@ -363,6 +365,8 @@ DEFINE_EXC_EXP_IMPL (IEX_EXPORT, DivzeroExc, MathExc)
 DEFINE_EXC_EXP_IMPL (IEX_EXPORT, InexactExc, MathExc)
 DEFINE_EXC_EXP_IMPL (IEX_EXPORT, InvalidFpOpExc, MathExc)
 
+/// @endcond Doxygen_Suppress
+
 IEX_INTERNAL_NAMESPACE_SOURCE_EXIT
 
 

src/lib/Iex/IexExport.h

@@ -33,7 +33,5 @@
 
 #endif // OPENEXR_DLL
 
-/// @}
-
 #endif // #ifndef INCLUDED_IEXEXPORT_H
 

src/lib/OpenEXRCore/internal_attr.h

@@ -44,25 +44,25 @@ int internal_exr_is_standard_type (const char* typen);
 
 typedef struct exr_attribute_list
 {
-    int num_attributes; /**< number of attribute entries in the list */
-    int num_alloced; /**< allocation count. if > 0, attribute list owns pointer */
-    exr_attribute_t** entries; /**< creation order list of attributes */
+    int num_attributes; /**< Number of attribute entries in the list */
+    int num_alloced; /**< Allocation count. if > 0, attribute list owns pointer */
+    exr_attribute_t** entries; /**< Creation order list of attributes */
     exr_attribute_t**
-        sorted_entries; /**< sorted order list of attributes for fast lookup */
+        sorted_entries; /**< Sorted order list of attributes for fast lookup */
 } exr_attribute_list_t;
 
-/** Initializes a list to an empty attribute list */
+/** Initialize a list to an empty attribute list */
 exr_result_t exr_attr_list_init (exr_context_t ctxt, exr_attribute_list_t* l);
 
-/** Frees memory for all the owned attributes in the list as well as the list itself */
+/** Free memory for all the owned attributes in the list as well as the list itself */
 exr_result_t
 exr_attr_list_destroy (exr_context_t ctxt, exr_attribute_list_t* l);
 
-/** Computes the number of bytes required to store this attribute list in a file */
+/** Compute the number of bytes required to store this attribute list in a file */
 exr_result_t exr_attr_list_compute_size (
     exr_context_t ctxt, exr_attribute_list_t* l, uint64_t* out);
 
-/** Finds an attribute in the list by name */
+/** Find an attribute in the list by name */
 exr_result_t exr_attr_list_find_by_name (
     exr_const_context_t   ctxt,
     exr_attribute_list_t* l,