Various doc string updates to C API files. (#372)

* Various doc string updates to C API files.

Author: Diptorup Deb

dpctl-capi/helper/include/dpctl_vector_macros.h

@@ -18,8 +18,9 @@
 //
 //===----------------------------------------------------------------------===//
 ///
-/// \file These macros are used in dpctl_vector_templ.cpp. They help build the
-/// function signatures for the functions defined in dpctl_vector_templ.cpp.
+/// \file
+/// A set of macros used inside dpctl_vector_templ.cpp. The macros help build
+/// the function signatures for the functions defined in dpctl_vector_templ.cpp.
 ///
 //===----------------------------------------------------------------------===//
 

dpctl-capi/include/Support/MemOwnershipAttrs.h

@@ -21,20 +21,14 @@
 /// \file
 /// This file defines a group of macros that serve as attributes indicating the
 /// type of ownership of a pointer. The macros are modeled after similar
-/// attributes defines in Integer Set Library (isl) and serve the purpose of
+/// attributes defined in Integer Set Library (isl) and serve the purpose of
 /// helping a programmer understand the semantics of a dpctl function.
 ///
 //===----------------------------------------------------------------------===//
 
 #pragma once
 
 /**
- * @defgroup MEM_MGMT_ATTR_MACROS Memory management attributes.
- *
- * @{
- */
-
-/*!
  * @def __dpctl_give
  * @brief The __dpctl_give attribute indicates that a new object is returned and
  * the caller now owns the object.
@@ -44,7 +38,6 @@
  * free the object, he/she should make sure to use it exactly once as a value
  * for a __dpctl_take argument. However, the user is free to use the object as
  * he/she likes as a value to __dpctl_keep arguments.
- *
  */
 #ifndef __dpctl_give
 #define __dpctl_give
@@ -60,27 +53,22 @@
  * function. If the pointer annotated with __dpctl_take is NULL then it is
  * treated as an error, since it may prevent the normal behavior of the
  * function.
- *
  */
 #ifndef __dpctl_take
 #define __dpctl_take
 #endif
+#ifndef __dpctl_keep
 /*!
  * @def __dpctl_keep
  * @brief The __dpctl_keep attribute indicates that the function only uses the
  * object and does not destroy it before returning.
- *
  */
-#ifndef __dpctl_keep
 #define __dpctl_keep
 #endif
 /*!
  * @def __dpctl_null
  * @brief The __dpctl_null attribute indicates that a NULL value is returned.
- *
  */
 #ifndef __dpctl_null
 #define __dpctl_null
 #endif
-
-/** @} */

dpctl-capi/include/dpctl_sycl_context_interface.h

@@ -37,6 +37,10 @@
 
 DPCTL_C_EXTERN_C_BEGIN
 
+/**
+ * @defgroup ContextInterface Context class C wrapper
+ */
+
 /*!
  * @brief Constructs a new SYCL context for the given SYCL device using the
  * optional async error handler and properties bit flags.
@@ -49,6 +53,7 @@ DPCTL_C_EXTERN_C_BEGIN
  *                          context properties. Currently, dpctl does not use
  *                          this argument.
  * @return   A new opaque pointer wrapping a SYCL context.
+ * @ingroup ContextInterface
  */
 DPCTL_API
 __dpctl_give DPCTLSyclContextRef
@@ -69,6 +74,7 @@ DPCTLContext_Create(__dpctl_keep const DPCTLSyclDeviceRef DRef,
  *                          context properties. Currently, dpctl does not use
  *                          this argument.
  * @return   A new opaque pointer wrapping a SYCL context.
+ * @ingroup ContextInterface
  */
 DPCTL_API
 __dpctl_give DPCTLSyclContextRef
@@ -83,6 +89,7 @@ DPCTLContext_CreateFromDevices(__dpctl_keep const DPCTLDeviceVectorRef DVRef,
  * @param    CtxRef1       First opaque pointer to the sycl context.
  * @param    CtxRef2       Second opaque pointer to the sycl context.
  * @return   True if the underlying sycl::context are same, false otherwise.
+ * @ingroup ContextInterface
  */
 DPCTL_API
 bool DPCTLContext_AreEq(__dpctl_keep const DPCTLSyclContextRef CtxRef1,
@@ -94,6 +101,7 @@ bool DPCTLContext_AreEq(__dpctl_keep const DPCTLSyclContextRef CtxRef1,
  * @param    CRef           DPCTLSyclContextRef object to be copied.
  * @return   A new DPCTLSyclContextRef created by copying the passed in
  * DPCTLSyclContextRef object.
+ * @ingroup ContextInterface
  */
 DPCTL_API
 __dpctl_give DPCTLSyclContextRef
@@ -105,6 +113,7 @@ DPCTLContext_Copy(__dpctl_keep const DPCTLSyclContextRef CRef);
  *
  * @param    CRef           DPCTLSyclContexRef object to query.
  * @return   A positive count on success or zero on error.
+ * @ingroup ContextInterface
  */
 DPCTL_API
 size_t DPCTLContext_DeviceCount(__dpctl_keep const DPCTLSyclContextRef CRef);
@@ -115,6 +124,7 @@ size_t DPCTLContext_DeviceCount(__dpctl_keep const DPCTLSyclContextRef CRef);
  *
  * @param    CRef           DPCTLSyclContexRef object to query.
  * @return   A DPCTLDeviceVectorRef with devices associated with given CRef.
+ * @ingroup ContextInterface
  */
 DPCTL_API
 __dpctl_give DPCTLDeviceVectorRef
@@ -125,6 +135,7 @@ DPCTLContext_GetDevices(__dpctl_keep const DPCTLSyclContextRef CRef);
  *
  * @param    CtxRef        An opaque pointer to a sycl::context.
  * @return   True if the SYCL context is a host context, else False.
+ * @ingroup ContextInterface
  */
 DPCTL_API
 bool DPCTLContext_IsHost(__dpctl_keep const DPCTLSyclContextRef CtxRef);
@@ -135,6 +146,7 @@ bool DPCTLContext_IsHost(__dpctl_keep const DPCTLSyclContextRef CtxRef);
  * @param    CtxRef         An opaque pointer to a sycl::context.
  * @return   The sycl backend for the DPCTLSyclContextRef returned as
  * a DPCTLSyclBackendType enum type.
+ * @ingroup ContextInterface
  */
 DPCTL_API
 DPCTLSyclBackendType
@@ -144,6 +156,7 @@ DPCTLContext_GetBackend(__dpctl_keep const DPCTLSyclContextRef CtxRef);
  * @brief Delete the pointer after casting it to sycl::context
  *
  * @param    CtxRef        The DPCTLSyclContextRef pointer to be deleted.
+ * @ingroup ContextInterface
  */
 DPCTL_API
 void DPCTLContext_Delete(__dpctl_take DPCTLSyclContextRef CtxRef);