Review user manual, API code comments and main page

Doxyfile.in

@@ -821,13 +821,13 @@ STRIP_CODE_COMMENTS    = YES
 # then for each documented function all documented
 # functions referencing it will be listed.
 
-REFERENCED_BY_RELATION = YES
+REFERENCED_BY_RELATION = NO
 
 # If the REFERENCES_RELATION tag is set to YES
 # then for each documented function all documented entities
 # called/used by that function will be listed.
 
-REFERENCES_RELATION    = YES
+REFERENCES_RELATION    = NO
 
 # If the REFERENCES_LINK_SOURCE tag is set to YES (the default)
 # and SOURCE_BROWSER tag is set to YES, then the hyperlinks from

README.md

@@ -26,23 +26,21 @@ Features
 * OpenCL version independent
 * Integrated profiling
 
+Documentation
+=============
+
+* [Examples](http://fakenmc.github.io/cf4ocl/docs/latest/examples.html)
+* [User guide and API](http://fakenmc.github.io/cf4ocl/docs/latest/)
+* [Download, build and install](https://github.com/FakenMC/cf4ocl/wiki/Download,-build-and-install)
+
 Feeback
 =======
 
-Clone, build and install the code, the a look at the
-[examples](https://github.com/FakenMC/cf4ocl/tree/master/src/examples)
-and the [v2.0.0-alpha API](http://fakenmc.github.io/cf4ocl/docs/v2.0.0-alpha).
+Clone, build and install the code, take a look at the
+[examples](http://fakenmc.github.io/cf4ocl/docs/latest/examples.html)
+and the [user guide and API](http://fakenmc.github.io/cf4ocl/docs/latest/).
 The API may change until the beta release. Any feedback is appreciated.
 
-Soon
-====
-
-* Simple and clear example
-* Links to GitHub wiki pages with other information and examples
-* Dependencies
-* Downloads, installing
-* More?
-
 Not yet implemented
 ===================
 

README.mdpp

@@ -26,23 +26,21 @@ Features
 * OpenCL version independent
 * Integrated profiling
 
+Documentation
+=============
+
+* [Examples](http://fakenmc.github.io/cf4ocl/docs/latest/examples.html)
+* [User guide and API](http://fakenmc.github.io/cf4ocl/docs/latest/)
+* [Download, build and install](https://github.com/FakenMC/cf4ocl/wiki/Download,-build-and-install)
+
 Feeback
 =======
 
-Clone, build and install the code, the a look at the
-[examples](https://github.com/FakenMC/cf4ocl/tree/master/src/examples)
-and the [v2.0.0-alpha API](http://fakenmc.github.io/cf4ocl/docs/v2.0.0-alpha).
+Clone, build and install the code, take a look at the
+[examples](http://fakenmc.github.io/cf4ocl/docs/latest/examples.html)
+and the [user guide and API](http://fakenmc.github.io/cf4ocl/docs/latest/).
 The API may change until the beta release. Any feedback is appreciated.
 
-Soon
-====
-
-* Simple and clear example
-* Links to GitHub wiki pages with other information and examples
-* Dependencies
-* Downloads, installing
-* More?
-
 Not yet implemented
 ===================
 

src/cf4ocl2/buffer_wrapper.h

@@ -47,10 +47,10 @@ typedef struct ccl_image CCLImage;
  * clCreateSubBuffer() but assumes that the sub-buffer will represent a
  * specific region in the original buffer (which is the only sub-buffer
  * type, up to OpenCL 2.0).
- * 
- * Buffer wrapper objects can be directly pass as kernel arguments to
+ *
+ * Buffer wrapper objects can be directly passed as kernel arguments to
  * functions such as ::ccl_kernel_set_args_and_enqueue_ndrange() or
- * ::ccl_kernel_set_args_v(). 
+ * ::ccl_kernel_set_args_v().
  *
  * Information about buffer objects can be fetched using the
  * @ref ug_getinfo "info macros" from the
@@ -70,18 +70,22 @@ typedef struct ccl_image CCLImage;
  * cl_float host_data[BSIZE];
  * size_t buf_size = BSIZE * sizeof(cl_float);
  * @endcode
+ *
  * @code{.c}
  * buf = ccl_buffer_new(
  *     context, CL_MEM_READ_WRITE, buf_size, NULL, NULL);
  * @endcode
+ *
  * @code{.c}
  * ccl_buffer_enqueue_write(queue, buf, CL_TRUE, 0, buf_size,
  *     host_data, NULL, NULL);
  * @endcode
+ *
  * @code{.c}
  * ccl_buffer_enqueue_read(queue, buf, CL_TRUE, 0, buf_size,
  *     host_data, NULL, NULL);
  * @endcode
+ *
  * @code{.c}
  * ccl_buffer_destroy(buf);
  * @endcode

src/cf4ocl2/context_wrapper.h

@@ -57,17 +57,13 @@
  * @ref DEVICE_SELECTOR "device selection module" section.
  * 3. Using one of the several convenience constructors, which contain
  * predefined filters, such as ::ccl_context_new_gpu(),
- * ::ccl_context_new_any or ::ccl_context_new_from_menu().
+ * ::ccl_context_new_any() or ::ccl_context_new_from_menu().
  *
  * Instantiation and destruction of context wrappers follows the
  * _cf4ocl_ @ref ug_new_destroy "new/destroy" rule; as such, context
  * wrapper objects must be released with the ::ccl_context_destroy()
  * function.
  *
- * Additional functions allow to get the device wrappers associated
- * with the the context wrapper object, as well as to obtain the
- * OpenCL version supported by the underlying OpenCL platform.
- *
  * Information about context objects can be fetched using the
  * context @ref ug_getinfo "info macros":
  *
@@ -216,7 +212,7 @@ CCLContext* ccl_context_new_wrap(cl_context context);
 		ccl_devsel_indep_type_accel, NULL, err)
 
 /**
- * Creates a context wrapper for the fist found device(s).
+ * Creates a context wrapper for the first found device(s).
  *
  * The first found device is used. More than one device might be used if
  * all devices belong to the same platform.

src/cf4ocl2/device_query.h

@@ -38,9 +38,9 @@
 /**
  * @defgroup DEVICE_QUERY Device query
  *
- * Classes and functions to facilitate the querying of OpenCL devices.
- * This module primarily supports the @ref devinfo utility, but may
- * also be of use to client code.
+ * This module facilitates the querying of OpenCL devices. It primarily
+ * supports the @ref devinfo utility, but may also be of use to client
+ * code.
  *
  * @{
  */

src/cf4ocl2/device_selector.h

@@ -45,7 +45,7 @@
  * The ::ccl_context_new_from_filters_full() context wrapper constructor
  * (and the ::ccl_context_new_from_filters() macro) accepts a
  * ::CCLDevSelFilters object containing a set of filters. These filters
- * define which devices will be used in the context. Instances of
+ * define which devices can be used in the context. Instances of
  * ::CCLDevSelFilters must be initialized to NULL:
  *
  * @dontinclude device_filter.c

src/cf4ocl2/device_wrapper.h

@@ -51,7 +51,7 @@ typedef struct ccl_platform CCLPlatform;
  * @ref CCLDevContainer "device container" objects such as
  * ::CCLPlatform* or ::CCLContext* instances. As such, and in accordance
  * with the _cf4ocl_ @ref ug_new_destroy "new/destroy" rule, the
- * ::ccl_device_destroy() destructor function will also be rarely used.
+ * ::ccl_device_destroy() destructor function will rarely be used.
  *
  * Information about device objects can be fetched using the
  * device @ref ug_getinfo "info macros":

src/cf4ocl2/errors.h

@@ -33,18 +33,20 @@
  *
  * This module offers a function to convert OpenCL error codes into
  * human-readable strings. It is widely used by other _cf4ocl_
- * modules, but may also be useful to client code.
+ * modules, but may also be useful to client code which directly uses
+ * OpenCL functions.
  *
  * _Example:_
  *
  * @code{.c}
- *
- * buf = ccl_buffer_new(ctx, flags, size, host_ptr, &err);
- * if ((err) && (err->domain == CCL_OCL_ERROR)) {
- *     fprintf(
- *         stderr, "OpenCL error %d: %s", err->code, cl_err(err->code));
+ * cl_int status;
+ * cl_event event;
+ * @endcode
+ * @code{.c}
+ * status = clWaitForEvents(1, &event);
+ * if (status != CL_SUCCESS) {
+ *     fprintf(stderr, "OpenCL error %d: %s", status, ccl_err(status));
  * }
- *
  * @endcode
  *
  * @{

src/cf4ocl2/event_wrapper.h

@@ -45,22 +45,22 @@ typedef struct ccl_queue CCLQueue;
  * handling of OpenCL event objects.
  *
  * Typical event wrappers are not directly created by client code. They
- * are returned by several functions which wrap OpenCL code which fires
- * events (such as ::ccl_image_enqueue_write(), which wraps the
- * clEnqueueWriteImage() OpenCL function). As such, and in accordance
- * with the @ref ug_new_destroy "new/destroy" rule, regular event
- * wrappers objects should not be destroyed by client code. They are
+ * are returned by event producing functions (such as
+ * ::ccl_image_enqueue_write(), which wraps the clEnqueueWriteImage()
+ * OpenCL function). As such, and in accordance with the
+ * @ref ug_new_destroy "new/destroy" rule, regular event wrappers
+ * objects should not be destroyed by client code. They are
  * automatically released when the command queue wrapper where the event
- * took place is destroyed. The only exception is with user events
- * (OpenCL >= 1.1), created with the ::ccl_user_event_new() constructor.
- * These are special events which allow applications to enqueue commands
- * that wait on user-controlled scenarios before the command is executed
- * by the device. These events should be destroyed with
+ * took place is destroyed. User events (OpenCL >= 1.1), created with
+ * the ::ccl_user_event_new() constructor, are the only exception. These
+ * are special events which allow applications to enqueue commands that
+ * wait on user-controlled situations before the command is executed by
+ * the device. These events should be destroyed with
  * ::ccl_event_destroy().
  *
- * The @ref EVENT_WAIT_LIST "event wait list module" provides additional
- * information on how to use events to synchronize the execution of
- * OpenCL commands. Events are also used by the
+ * The @ref EVENT_WAIT_LIST "event wait list section" provides
+ * additional information on how to use events to synchronize the
+ * execution of OpenCL commands. Events are also used by the
  * @ref PROFILER "profiler module", although indirectly via ::CCLQueue*
  * wrappers, to profile and benchmark applications.
  *

src/cf4ocl2/image_wrapper.h

@@ -54,19 +54,19 @@ typedef struct ccl_buffer CCLBuffer;
  * @ref ug_new_destroy "new/destroy" rule; as such, images should be
  * freed with the ::ccl_image_destroy() destructor.
  *
- * Image wrapper objects can be directly pass as kernel arguments to
+ * Image wrapper objects can be directly passed as kernel arguments to
  * functions such as ::ccl_program_enqueue_kernel() or
  * ::ccl_kernel_set_arg().
  *
- * Information about image objects can be fetched using the
+ * Information about image objects can be fetched using the image
  * @ref ug_getinfo "info macros":
  *
  * * ::ccl_image_get_info_scalar()
  * * ::ccl_image_get_info_array()
  * * ::ccl_image_get_info()
  *
  * If the information to be fetched is relative to the memory object
- * super-class (e.g. `CL_MEM_TYPE` or `CL_MEM_FLAGS`), then the
+ * parent class (e.g. `CL_MEM_TYPE` or `CL_MEM_FLAGS`), then the
  * @ref MEMOBJ_WRAPPER "memory object module" info macros should be used
  * instead:
  *

src/cf4ocl2/kernel_wrapper.h

@@ -59,12 +59,11 @@ typedef struct ccl_program CCLProgram;
  * in accordance with the _cf4ocl_ @ref ug_new_destroy "new/destroy"
  * rule.
  *
- * While the first approach might be more convenient in many situations,
- * it will not work properly if the same kernel function is to be
- * handled and executed by different threads. In these cases, use the
- * second approach to create distinct kernel wrapper instances (wrapping
- * distinct OpenCL kernel objects) for the same kernel function, one for
- * each thread.
+ * While the first approach might be more convenient, it will not work
+ * properly if the same kernel function is to be handled and executed by
+ * different threads. In these cases, use the second approach to create
+ * distinct kernel wrapper instances (wrapping distinct OpenCL kernel
+ * objects) for the same kernel function, one for each thread.
  *
  * This module offers several functions which simplify kernel execution.
  * For example, the ccl_kernel_set_args_and_enqueue_ndrange() function

src/cf4ocl2/platforms.h

@@ -40,11 +40,10 @@
  * The platforms module provides functionality for managing the OpenCL
  * platforms available in the system.
  *
- * The ::ccl_platforms_new() function returns the set of platforms
+ * The ::ccl_platforms_new() function returns a list of platforms
  * available in the system. The ::ccl_platforms_count() can be used to
- * get the number of platforms in that set, while the
- * ::ccl_platforms_get() will return the @f$i^{th}@f$ platform in the
- * system.
+ * get the number of platforms in the list, while the
+ * ::ccl_platforms_get() will return the @f$i^{th}@f$ platform.
  *
  *  _Example:_
  *
@@ -57,17 +56,17 @@
  * @skipline GError* err = NULL;
  *
  * @skipline Get all platforms in system
- * @until platf_set = ccl_platforms_new(&err);
+ * @until platf_list = ccl_platforms_new(&err);
  *
  * @skipline Get number of platforms in system
- * @until num_platfs = ccl_platforms_count(platf_set);
+ * @until num_platfs = ccl_platforms_count
  *
  * @skipline Cycle through platforms
- * @until platf = ccl_platforms_get(platf_set, i);
+ * @until platf = ccl_platforms_get
  *
  * @skipline Cycle platforms
  * @until ccl_platforms_destroy
- * 
+ *
  * @example list_devices.c
  * @{
  */

src/cf4ocl2/program_wrapper.h

@@ -156,6 +156,9 @@
  * _Example:_
  *
  * @dontinclude canon.c
+ * @skipline #define KERNEL_NAME
+ * @until "}\n"
+ *
  * @skipline Wrappers.
  * @until c_dev
  * @skipline CCLEvent* evt_exec
@@ -296,7 +299,7 @@ cl_bool ccl_program_build(
 cl_bool ccl_program_build_full(CCLProgram* prg,
 	cl_uint num_devices, CCLDevice* const* devs, const char* options,
 	ccl_program_callback pfn_notify, void* user_data, GError** err);
-	
+
 /* Get build log for most recent build, compile or link. */
 const char* ccl_program_get_build_log(CCLProgram* prg);
 

src/cf4ocl2/sampler_wrapper.h

@@ -58,7 +58,7 @@
  * ::ccl_sampler_destroy() function, in accordance with the
  * _cf4ocl_ @ref ug_new_destroy "new/destroy" rule.
  *
- * Sampler wrapper objects can be directly pass as kernel arguments to
+ * Sampler wrapper objects can be directly passed as kernel arguments to
  * functions such as ::ccl_kernel_set_args_and_enqueue_ndrange() or
  * ::ccl_kernel_set_args().
  *

src/samples/canon.c

@@ -173,7 +173,9 @@ int main(int argc, char** argv) {
 	/* Execute program kernel, waiting for the two transfer events
 	 * to terminate (this will empty the event wait list). */
 	evt_exec = ccl_program_enqueue_kernel(prg, KERNEL_NAME, queue, 1,
-		NULL, &gws, &lws, &ewl, &err, a_dev, b_dev, c_dev,
+		NULL, &gws, &lws, &ewl, &err,
+		/* Kernel arguments. */ 
+		a_dev, b_dev, c_dev, 
 		ccl_arg_priv(d_host, cl_uint), ccl_arg_priv(buf_n, cl_uint),
 		NULL);
 	HANDLE_ERROR(err);

src/samples/device_filter.c

@@ -70,7 +70,7 @@ int main(int argc, char* argv[]) {
 	ccl_devsel_add_indep_filter(
 		&filters, ccl_devsel_indep_type_cpu, NULL);
 
-	/* Add same platform dependent filter. This filter should always
+	/* Add "same platform" dependent filter. This filter should always
 	 * be added (usually in last position) for context creation, because
 	 * all devices in a context must belong to the same platform. */
 	ccl_devsel_add_dep_filter(&filters, ccl_devsel_dep_platform, NULL);