Misc. formatting fixes. (#137)

- Update the helper script to better align doxygen comments.
- Use consistent language when referring to the pNext member of structures.
- Reduce script warnings by adjusting the language used to refer to struct members.
- Fix docs generation script to correctly handle etor errors.
- Remove (comment out) deprecated/unused Doxygen flags

Signed-off-by: Will Damon <[email protected]>

Author: wdamon-intel

scripts/Doxyfile

@@ -99,7 +99,7 @@ OUTPUT_LANGUAGE        = English
 # Possible values are: None, LTR, RTL and Context.
 # The default value is: None.
 
-OUTPUT_TEXT_DIRECTION  = None
+# OUTPUT_TEXT_DIRECTION  = None
 
 # If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member
 # descriptions after the members that are listed in the file and class
@@ -1054,15 +1054,15 @@ VERBATIM_HEADERS       = NO
 # generated with the -Duse_libclang=ON option for CMake.
 # The default value is: NO.
 
-CLANG_ASSISTED_PARSING = NO
+# CLANG_ASSISTED_PARSING = NO
 
 # If clang assisted parsing is enabled you can provide the compiler with command
 # line options that you would normally use when invoking the compiler. Note that
 # the include paths will already be set by doxygen for the files and directories
 # specified with INPUT and INCLUDE_PATH.
 # This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES.
 
-CLANG_OPTIONS          =
+# CLANG_OPTIONS          =
 
 # If clang assisted parsing is enabled you can provide the clang parser with the
 # path to the compilation database (see:
@@ -1072,7 +1072,7 @@ CLANG_OPTIONS          =
 # Note: The availability of this option depends on whether or not doxygen was
 # generated with the -Duse_libclang=ON option for CMake.
 
-CLANG_DATABASE_PATH    =
+# CLANG_DATABASE_PATH    =
 
 #---------------------------------------------------------------------------
 # Configuration options related to the alphabetical class index
@@ -1090,7 +1090,7 @@ ALPHABETICAL_INDEX     = YES
 # Minimum value: 1, maximum value: 20, default value: 5.
 # This tag requires that the tag ALPHABETICAL_INDEX is set to YES.
 
-COLS_IN_ALPHA_INDEX    = 5
+# COLS_IN_ALPHA_INDEX    = 5
 
 # In case all classes in a project start with a common prefix, all classes will
 # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag
@@ -1518,7 +1518,7 @@ FORMULA_FONTSIZE       = 10
 # The default value is: YES.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-FORMULA_TRANSPARENT    = YES
+# FORMULA_TRANSPARENT    = YES
 
 # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see
 # https://www.mathjax.org) which uses client side Javascript for the rendering
@@ -1838,7 +1838,7 @@ LATEX_HIDE_INDICES     = NO
 # The default value is: NO.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-LATEX_SOURCE_CODE      = NO
+# LATEX_SOURCE_CODE      = NO
 
 # The LATEX_BIB_STYLE tag can be used to specify the style to use for the
 # bibliography, e.g. plainnat, or ieeetr. See
@@ -1928,7 +1928,7 @@ RTF_EXTENSIONS_FILE    =
 # The default value is: NO.
 # This tag requires that the tag GENERATE_RTF is set to YES.
 
-RTF_SOURCE_CODE        = NO
+# RTF_SOURCE_CODE        = NO
 
 #---------------------------------------------------------------------------
 # Configuration options related to the man page output
@@ -2033,7 +2033,7 @@ DOCBOOK_OUTPUT         = docbook
 # The default value is: NO.
 # This tag requires that the tag GENERATE_DOCBOOK is set to YES.
 
-DOCBOOK_PROGRAMLISTING = NO
+# DOCBOOK_PROGRAMLISTING = NO
 
 #---------------------------------------------------------------------------
 # Configuration options for the AutoGen Definitions output
@@ -2220,7 +2220,7 @@ EXTERNAL_PAGES         = YES
 # powerful graphs.
 # The default value is: YES.
 
-CLASS_DIAGRAMS         = YES
+# CLASS_DIAGRAMS         = YES
 
 # You can include diagrams made with dia in doxygen documentation. Doxygen will
 # then run dia to produce the diagram and insert it in the documentation. The
@@ -2262,14 +2262,14 @@ DOT_NUM_THREADS        = 0
 # The default value is: Helvetica.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_FONTNAME           = Helvetica
+# DOT_FONTNAME           = Helvetica
 
 # The DOT_FONTSIZE tag can be used to set the size (in points) of the font of
 # dot graphs.
 # Minimum value: 4, maximum value: 24, default value: 10.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_FONTSIZE           = 10
+# DOT_FONTSIZE           = 10
 
 # By default doxygen will tell dot to use the default font as specified with
 # DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set
@@ -2493,7 +2493,7 @@ MAX_DOT_GRAPH_DEPTH    = 0
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_TRANSPARENT        = NO
+# DOT_TRANSPARENT        = NO
 
 # Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output
 # files in one run (i.e. multiple -o and -T options on the command line). This

scripts/core/EUCount.yml

@@ -36,5 +36,5 @@ members:
       name: numTotalEUs
       desc: "[out] Total number of EUs available"
 details:
-    - "This structure may be returned from $xDeviceGetProperties via `pNext` member of $x_device_properties_t"
+    - "This structure may be returned from $xDeviceGetProperties via the `pNext` member of $x_device_properties_t."
     - "Used for determining the total number of EUs available on device."

scripts/core/cacheReservation.yml

@@ -32,11 +32,27 @@ class: $xDevice
 name: $x_cache_ext_region_t
 etors:
     - name: $X_CACHE_REGION_DEFAULT
-      desc: "utilize driver default scheme"
+      desc:
+            "1.6": "utilize driver default scheme"
+            "1.7": "[DEPRECATED] utilize driver default scheme. Use $X_CACHE_EXT_REGION_DEFAULT."
     - name: $X_CACHE_RESERVE_REGION
-      desc: "Utilize reserver region"
+      desc:
+            "1.6": "utilize reserved region"
+            "1.7": "[DEPRECATED] utilize reserved region. Use $X_CACHE_EXT_REGION_RESERVED."
     - name: $X_CACHE_NON_RESERVED_REGION
-      desc: "Utilize non-reserverd region"
+      desc:
+            "1.6": "utilize non-reserverd region"
+            "1.7": "[DEPRECATED] utilize non-reserverd region. Use $X_CACHE_EXT_REGION_NON_RESERVED."
+    - name: DEFAULT
+      desc: "utilize driver default scheme"
+      version: "1.7"
+      value: "0"
+    - name: RESERVED
+      desc: "utilize reserved region"
+      version: "1.7"
+    - name: NON_RESERVED
+      desc: "utilize non-reserverd region"
+      version: "1.7"
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "CacheReservation structure"
@@ -49,7 +65,7 @@ members:
       name: maxCacheReservationSize
       desc: "[out] max cache reservation size"
 details:
-    - "This structure must be passed to $xDeviceGetCacheProperties via `pNext` member of $x_device_cache_properties_t"
+    - "This structure must be passed to $xDeviceGetCacheProperties via the `pNext` member of $x_device_cache_properties_t"
     - "Used for determining the max cache reservation allowed on device. Size of zero means no reservation available."
 --- #--------------------------------------------------------------------------
 type: function

scripts/core/cmdlist.yml

@@ -153,8 +153,8 @@ class: $xCommandList
 name: AppendWriteGlobalTimestamp
 details:
     - "The application must ensure the events are accessible by the device on which the command list was created."
-    - "The timestamp frequency can be queried from $x_device_properties_t.timerResolution."
-    - "The number of valid bits in the timestamp value can be queried from $x_device_properties_t.timestampValidBits."
+    - "The timestamp frequency can be queried from the `timerResolution` member of $x_device_properties_t."
+    - "The number of valid bits in the timestamp value can be queried from the `timestampValidBits` member of $x_device_properties_t."
     - "The application must ensure the memory pointed to by dstptr is accessible by the device on which the command list was created."
     - "The application must ensure the command list and events were created, and the memory was allocated, on the same context."
     - "The application must **not** call this function from simultaneous threads with the same command list handle."
@@ -201,7 +201,7 @@ params:
       desc: |
             [in] if non-zero, then indicates the maximum time (in nanoseconds) to yield before returning $X_RESULT_SUCCESS or $X_RESULT_NOT_READY;
             if zero, then immediately returns the status of the immediate command list;
-            if UINT64_MAX, then function will not return until complete or device is lost.
+            if `UINT64_MAX`, then function will not return until complete or device is lost.
             Due to external dependencies, timeout may be rounded to the closest value allowed by the accuracy of those dependencies.
 returns:
     - $X_RESULT_NOT_READY:

scripts/core/cmdqueue.yml

@@ -181,7 +181,7 @@ params:
       desc: |
             [in] if non-zero, then indicates the maximum time (in nanoseconds) to yield before returning $X_RESULT_SUCCESS or $X_RESULT_NOT_READY;
             if zero, then immediately returns the status of the command queue;
-            if UINT64_MAX, then function will not return until complete or device is lost.
+            if `UINT64_MAX`, then function will not return until complete or device is lost.
             Due to external dependencies, timeout may be rounded to the closest value allowed by the accuracy of those dependencies.
 returns:
     - $X_RESULT_NOT_READY:

scripts/core/copy.yml

@@ -60,7 +60,7 @@ details:
     - "The application must ensure the memory pointed to by dstptr is accessible by the device on which the command list was created."
     - "The implementation must not access the memory pointed to by dstptr as it is free to be modified by either the Host or device up until execution."
     - "The value to initialize memory to is described by the pattern and the pattern size."
-    - "The pattern size must be a power-of-two and less than or equal to $x_command_queue_group_properties_t.maxMemoryFillPatternSize."
+    - "The pattern size must be a power-of-two and less than or equal to the `maxMemoryFillPatternSize` member of $x_command_queue_group_properties_t."
     - "The application must ensure the events are accessible by the device on which the command list was created."
     - "The application must ensure the command list and events were created, and the memory was allocated, on the same context."
     - "The application must **not** call this function from simultaneous threads with the same command list handle."
@@ -150,7 +150,7 @@ params:
       desc: "[in] destination pitch in bytes"
     - type: "uint32_t"
       name: dstSlicePitch
-      desc: "[in] destination slice pitch in bytes. This is required for 3D region copies where $x_copy_region_t.depth is not 0, otherwise it's ignored."
+      desc: "[in] destination slice pitch in bytes. This is required for 3D region copies where the `depth` member of $x_copy_region_t is not 0, otherwise it's ignored."
     - type: "const void*"
       name: srcptr
       desc: "[in] pointer to source memory to copy from"
@@ -162,7 +162,7 @@ params:
       desc: "[in] source pitch in bytes"
     - type: "uint32_t"
       name: srcSlicePitch
-      desc: "[in] source slice pitch in bytes. This is required for 3D region copies where $x_copy_region_t.depth is not 0, otherwise it's ignored."
+      desc: "[in] source slice pitch in bytes. This is required for 3D region copies where the `depth` member of $x_copy_region_t is not 0, otherwise it's ignored."
     - type: $x_event_handle_t
       name: hSignalEvent
       desc: "[in][optional] handle of the event to signal on completion"

scripts/core/device.yml

@@ -192,22 +192,22 @@ members:
       name: slice
       desc: |
             [in,out] the slice number.
-            Must be UINT32_MAX (all) or less than $x_device_properties_t.numSlices.
+            Must be `UINT32_MAX` (all) or less than the `numSlices` member of $x_device_properties_t.
     - type: "uint32_t"
       name: subslice
       desc: |
             [in,out] the sub-slice number within its slice.
-            Must be UINT32_MAX (all) or less than $x_device_properties_t.numSubslicesPerSlice.
+            Must be `UINT32_MAX` (all) or less than the `numSubslicesPerSlice` member of $x_device_properties_t.
     - type: "uint32_t"
       name: eu
       desc: |
             [in,out] the EU number within its sub-slice.
-            Must be UINT32_MAX (all) or less than $x_device_properties_t.numEUsPerSubslice.
+            Must be `UINT32_MAX` (all) or less than the `numEUsPerSubslice` member of $x_device_properties_t.
     - type: "uint32_t"
       name: thread
       desc: |
             [in,out] the thread number within its EU.
-            Must be UINT32_MAX (all) or less than $x_device_properties_t.numThreadsPerEU.
+            Must be `UINT32_MAX` (all) or less than the `numThreadsPerEU` member of $x_device_properties_t.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Retrieves properties of the device."

scripts/core/deviceLUID.yml

@@ -63,4 +63,4 @@ members:
             Otherwise, the returned node mask must be 1.
 
 details:
-    - "This structure may be returned from $xDeviceGetProperties, via `pNext` member of $x_device_properties_t."
+    - "This structure may be returned from $xDeviceGetProperties, via the `pNext` member of $x_device_properties_t."

scripts/core/deviceipversion.yml

@@ -40,5 +40,5 @@ members:
             version than older devices.
 
 details:
-    - "This structure may be returned from $xDeviceGetProperties via `pNext` member of $x_device_properties_t"
+    - "This structure may be returned from $xDeviceGetProperties via the `pNext` member of $x_device_properties_t"
 

scripts/core/event.yml

@@ -331,7 +331,7 @@ params:
       desc: |
             [in] if non-zero, then indicates the maximum time (in nanoseconds) to yield before returning $X_RESULT_SUCCESS or $X_RESULT_NOT_READY;
             if zero, then operates exactly like $xEventQueryStatus;
-            if UINT64_MAX, then function will not return until complete or device is lost.
+            if `UINT64_MAX`, then function will not return until complete or device is lost.
             Due to external dependencies, timeout may be rounded to the closest value allowed by the accuracy of those dependencies.
 returns:
     - $X_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT
@@ -399,8 +399,8 @@ desc: "Kernel timestamp clock data"
 class: $xEvent
 name: $x_kernel_timestamp_data_t
 details:
-    - "The timestamp frequency can be queried from $x_device_properties_t.timerResolution."
-    - "The number of valid bits in the timestamp value can be queried from $x_device_properties_t.kernelTimestampValidBits."
+    - "The timestamp frequency can be queried from the `timerResolution` member of $x_device_properties_t."
+    - "The number of valid bits in the timestamp value can be queried from the `kernelTimestampValidBits` member of $x_device_properties_t."
 members:
     - type: uint64_t
       name: kernelStart