fix asciidoctor refpage warnings (#1520)

* fix asciidoctor refpage warnings

* define separate attributes for enqueues and queries

* final tidy up

Changes the refpage markup to include the right content, especially
for the enqueue_kernel functions.

Author: bashbaug

OpenCL_C.txt

@@ -13308,8 +13308,6 @@ The following behavior is undefined:
 [[enqueuing-kernels]]
 === Enqueuing Kernels
 
-[open,refpage='enqueue_kernel',desc='Enqueuing Kernels',type='freeform',spec='clang',anchor='enqueuing-kernels',xrefs='enqueue_marker']
---
 NOTE: The functionality described in this section <<unified-spec, requires>>
 support for OpenCL C 2.0, or OpenCL C 3.0 or newer and the
 {opencl_c_device_enqueue} feature.
@@ -13319,11 +13317,19 @@ enqueue additional work to the same device, without host interaction.
 A kernel may enqueue code represented by Block syntax, and control execution
 order with event dependencies including user events and markers.
 There are several advantages to using the Block syntax: it is more compact;
-it does not require a cl_kernel object; and enqueuing can be done as a
+it does not require a {cl_kernel_TYPE} object; and enqueuing can be done as a
 single semantic step.
 
+The macro `CLK_NULL_EVENT` refers to an invalid device event.
+The macro `CLK_NULL_QUEUE` refers to an invalid device queue.
+
+[[built-in-functions-enqueuing-a-kernel]]
+==== Built-in Functions - Enqueuing a Kernel
+
+[open,refpage='enqueue_kernel',desc='Built-in Functions - Enqueuing Kernels',type='freeform',spec='clang',anchor='enqueuing-kernels',xrefs='enqueue_marker']
+--
 The following table describes the list of built-in functions that can be
-used to enqueue a kernel(s).
+used to enqueue a kernel.
 
 ifdef::cl_khr_device_enqueue_local_arg_types[]
 When the {cl_khr_device_enqueue_local_arg_types_EXT} extension macro is
@@ -13338,22 +13344,8 @@ signatures.
 
 When the  {cl_khr_device_enqueue_local_arg_types_EXT} extension macro is
 not supported, the pointee type of these functions must be `void`.
-
-:localArgType: gentype
-endif::cl_khr_device_enqueue_local_arg_types[]
-
-ifndef::cl_khr_device_enqueue_local_arg_types[]
-:localArgType: void
 endif::cl_khr_device_enqueue_local_arg_types[]
 
-The macro `CLK_NULL_EVENT` refers to an invalid device event.
-The macro `CLK_NULL_QUEUE` refers to an invalid device queue.
---
-
-
-[[built-in-functions-enqueuing-a-kernel]]
-==== Built-in Functions - Enqueuing a Kernel
-
 [[table-builtin-kernel-enqueue]]
 .Built-in Kernel Enqueue Functions
 [cols=",",options="header",]
@@ -13367,12 +13359,25 @@ The macro `CLK_NULL_QUEUE` refers to an invalid device queue.
     const clk_event_t *_event_wait_list_, clk_event_t *_event_ret_,
     void (^__block__)(void)) +
   int **enqueue_kernel**(queue_t _queue_, kernel_enqueue_flags_t _flags_,
-    const ndrange_t _ndrange_, void (^__block__)(local {localArgType} *, ...),
+    const ndrange_t _ndrange_, void (^__block__)(local void *, ...),
     uint size0, ...) +
   int **enqueue_kernel**(queue_t _queue_, kernel_enqueue_flags_t _flags_,
     const ndrange_t _ndrange_, uint _num_events_in_wait_list_,
     const clk_event_t *_event_wait_list_, clk_event_t *_event_ret_,
-    void (^__block__)(local {localArgType} *, ...), uint size0, ...)
+    void (^__block__)(local void *, ...), uint size0, ...)
+
+ifdef::cl_khr_device_enqueue_local_arg_types[]
+  If the {cl_khr_device_enqueue_local_arg_types_EXT} extension macro is supported:
+
+  int **enqueue_kernel**(queue_t _queue_, kernel_enqueue_flags_t _flags_,
+    const ndrange_t _ndrange_, void (^__block__)(local gentype *, ...),
+    uint size0, ...) +
+  int **enqueue_kernel**(queue_t _queue_, kernel_enqueue_flags_t _flags_,
+    const ndrange_t _ndrange_, uint _num_events_in_wait_list_,
+    const clk_event_t *_event_wait_list_, clk_event_t *_event_ret_,
+    void (^__block__)(local gentype *, ...), uint size0, ...)
+endif::cl_khr_device_enqueue_local_arg_types[]
+
     | Enqueue the block for execution to _queue_.
 
       If an event is returned, *enqueue_kernel* performs an implicit retain
@@ -13381,7 +13386,7 @@ The macro `CLK_NULL_QUEUE` refers to an invalid device queue.
 
 The *enqueue_kernel* built-in function allows a work-item to enqueue a
 block.
-Work-items can enqueue multiple blocks to a device queue(s).
+Work-items can enqueue multiple blocks to device queues.
 
 The *enqueue_kernel* built-in function returns `CLK_SUCCESS` if the block is
 enqueued successfully and returns `CLK_ENQUEUE_FAILURE` otherwise.
@@ -13406,6 +13411,7 @@ block:
     could not be allocated.
   * `CLK_OUT_OF_RESOURCES` if there is a failure to queue the block in
     _queue_ because of insufficient resources needed to execute the kernel.
+--
 
 Below are some examples of how to enqueue a block.
 
@@ -13720,15 +13726,30 @@ execution.
 |====
 | Built-in Function | Description
 | uint *get_kernel_work_group_size*(void (^block)(void)) +
-  uint *get_kernel_work_group_size*(void (^block)(local {localArgType} *, ...))
+  uint *get_kernel_work_group_size*(void (^block)(local void *, ...))
+
+ifdef::cl_khr_device_enqueue_local_arg_types[]
+  If the {cl_khr_device_enqueue_local_arg_types_EXT} extension macro is supported:
+
+  uint *get_kernel_work_group_size*(void (^block)(local gentype *, ...))
+endif::cl_khr_device_enqueue_local_arg_types[]
+
     | This provides a mechanism to query the maximum work-group size that
       can be used to execute a block on a specific device given by _device_.
 
       _block_ specifies the block to be enqueued.
 | uint *{get_kernel_preferred_work_group_size_multiple}*(
   void (^block)(void)) +
   uint *{get_kernel_preferred_work_group_size_multiple}*(
-  void (^block)(local {localArgType} *, ...))
+  void (^block)(local void *, ...))
+
+ifdef::cl_khr_device_enqueue_local_arg_types[]
+  If the {cl_khr_device_enqueue_local_arg_types_EXT} extension macro is supported:
+
+  uint *{get_kernel_preferred_work_group_size_multiple}*(
+  void (^block)(local gentype *, ...))
+endif::cl_khr_device_enqueue_local_arg_types[]
+
     | Returns the preferred multiple of work-group size for launch.
       This is a performance hint.
       Specifying a work-group size that is not a multiple of the value

scripts/clconventions.py

@@ -210,6 +210,7 @@ def extra_refpage_headers(self):
             'include::{config}/version-full-links.asciidoc[]\n' + \
             'include::{generated}/api/api-dictionary-no-links.asciidoc[]\n' + \
             'include::{generated}/api/ext-dictionary-no-links.asciidoc[]\n' + \
+            'include::{generated}/meta/c-function-dictionary.asciidoc[]\n' + \
             'include::{cspec}/feature-dictionary.asciidoc[]\n' + \
             'include::{apispec}/footnotes.asciidoc[]\n' + \
             'include::{cspec}/footnotes.asciidoc[]\n'