Correct the existing documented T-API functions to match the doxygen format (opencv#8758)

krishraghuram · mshabunin · commit 9ea2f5211e1a · 2017-05-24T13:31:35.000+03:00
* Correct the existing documented T-API functions to match the doxygen format.

* docs: fix comments style

* T-API documentation: minor formatting changes
diff --git a/modules/core/include/opencv2/core/ocl.hpp b/modules/core/include/opencv2/core/ocl.hpp
@@ -278,55 +278,38 @@ class CV_EXPORTS Platform
     Impl* p;
 };
 
-/*
-//! @brief Attaches OpenCL context to OpenCV
-//
-//! @note Note:
-//    OpenCV will check if available OpenCL platform has platformName name,
-//    then assign context to OpenCV and call clRetainContext function.
-//    The deviceID device will be used as target device and new command queue
-//    will be created.
-//
-// Params:
-//! @param platformName - name of OpenCL platform to attach,
-//!                       this string is used to check if platform is available
-//!                       to OpenCV at runtime
-//! @param platfromID   - ID of platform attached context was created for
-//! @param context      - OpenCL context to be attached to OpenCV
-//! @param deviceID     - ID of device, must be created from attached context
+/** @brief Attaches OpenCL context to OpenCV
+@note
+  OpenCV will check if available OpenCL platform has platformName name, then assign context to
+  OpenCV and call `clRetainContext` function. The deviceID device will be used as target device and
+  new command queue will be created.
+@param platformName name of OpenCL platform to attach, this string is used to check if platform is available to OpenCV at runtime
+@param platformID ID of platform attached context was created for
+@param context OpenCL context to be attached to OpenCV
+@param deviceID ID of device, must be created from attached context
 */
 CV_EXPORTS void attachContext(const String& platformName, void* platformID, void* context, void* deviceID);
 
-/*
-//! @brief Convert OpenCL buffer to UMat
-//
-//! @note Note:
-//   OpenCL buffer (cl_mem_buffer) should contain 2D image data, compatible with OpenCV.
-//   Memory content is not copied from clBuffer to UMat. Instead, buffer handle assigned
-//   to UMat and clRetainMemObject is called.
-//
-// Params:
-//! @param  cl_mem_buffer - source clBuffer handle
-//! @param  step          - num of bytes in single row
-//! @param  rows          - number of rows
-//! @param  cols          - number of cols
-//! @param  type          - OpenCV type of image
-//! @param  dst           - destination UMat
+/** @brief Convert OpenCL buffer to UMat
+@note
+  OpenCL buffer (cl_mem_buffer) should contain 2D image data, compatible with OpenCV. Memory
+  content is not copied from `clBuffer` to UMat. Instead, buffer handle assigned to UMat and
+  `clRetainMemObject` is called.
+@param cl_mem_buffer source clBuffer handle
+@param step num of bytes in single row
+@param rows number of rows
+@param cols number of cols
+@param type OpenCV type of image
+@param dst destination UMat
 */
 CV_EXPORTS void convertFromBuffer(void* cl_mem_buffer, size_t step, int rows, int cols, int type, UMat& dst);
 
-/*
-//! @brief Convert OpenCL image2d_t to UMat
-//
-//! @note Note:
-//   OpenCL image2d_t (cl_mem_image), should be compatible with OpenCV
-//   UMat formats.
-//   Memory content is copied from image to UMat with
-//   clEnqueueCopyImageToBuffer function.
-//
-// Params:
-//! @param  cl_mem_image - source image2d_t handle
-//! @param  dst          - destination UMat
+/** @brief Convert OpenCL image2d_t to UMat
+@note
+  OpenCL `image2d_t` (cl_mem_image), should be compatible with OpenCV UMat formats. Memory content
+  is copied from image to UMat with `clEnqueueCopyImageToBuffer` function.
+@param cl_mem_image source image2d_t handle
+@param dst destination UMat
 */
 CV_EXPORTS void convertFromImage(void* cl_mem_image, UMat& dst);
 
@@ -569,14 +552,12 @@ class CV_EXPORTS Kernel
         i = set(i, a6); i = set(i, a7); i = set(i, a8); i = set(i, a9); i = set(i, a10); i = set(i, a11);
         i = set(i, a12); i = set(i, a13); i = set(i, a14); set(i, a15); return *this;
     }
-    /*
-    Run the OpenCL kernel.
+    /** @brief Run the OpenCL kernel.
     @param dims the work problem dimensions. It is the length of globalsize and localsize. It can be either 1, 2 or 3.
-    @param globalsize work items for each dimension.
-    It is not the final globalsize passed to OpenCL.
-    Each dimension will be adjusted to the nearest integer divisible by the corresponding value in localsize.
-    If localsize is NULL, it will still be adjusted depending on dims.
-    The adjusted values are greater than or equal to the original values.
+    @param globalsize work items for each dimension. It is not the final globalsize passed to
+      OpenCL. Each dimension will be adjusted to the nearest integer divisible by the corresponding
+      value in localsize. If localsize is NULL, it will still be adjusted depending on dims. The
+      adjusted values are greater than or equal to the original values.
     @param localsize work-group size for each dimension.
     @param sync specify whether to wait for OpenCL computation to finish before return.
     @param q command queue
@@ -711,22 +692,25 @@ class CV_EXPORTS Image2D
 public:
     Image2D();
 
-    // src:     The UMat from which to get image properties and data
-    // norm:    Flag to enable the use of normalized channel data types
-    // alias:   Flag indicating that the image should alias the src UMat.
-    //          If true, changes to the image or src will be reflected in
-    //          both objects.
+    /**
+    @param src UMat object from which to get image properties and data
+    @param norm flag to enable the use of normalized channel data types
+    @param alias flag indicating that the image should alias the src UMat. If true, changes to the
+        image or src will be reflected in both objects.
+    */
     explicit Image2D(const UMat &src, bool norm = false, bool alias = false);
     Image2D(const Image2D & i);
     ~Image2D();
 
     Image2D & operator = (const Image2D & i);
 
-    // Indicates if creating an aliased image should succeed.  Depends on the
-    // underlying platform and the dimensions of the UMat.
+    /** Indicates if creating an aliased image should succeed.
+    Depends on the underlying platform and the dimensions of the UMat.
+    */
     static bool canCreateAlias(const UMat &u);
 
-    // Indicates if the image format is supported.
+    /** Indicates if the image format is supported.
+    */
     static bool isFormatSupported(int depth, int cn, bool norm);
 
     void* ptr() const;
