[SYCL][Doc] Deploy documentation for PI (#1318)

Signed-off-by: Alexander Batashev <[email protected]>

Author: Alexander Batashev

sycl/doc/doxygen.cfg.in

@@ -171,7 +171,9 @@ STRIP_FROM_PATH        = @abs_srcdir@/..
 # specify the list of include paths that are normally passed to the compiler
 # using the -I flag.
 
-STRIP_FROM_INC_PATH    = @abs_srcdir@/../include
+STRIP_FROM_INC_PATH    = @abs_srcdir@/../include \
+                         @abs_srcdir@/../source \
+                         @abs_srcdir@/../plugins
 
 # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but
 # less readable) file names. This can be useful is your file systems doesn't
@@ -791,7 +793,8 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.
 
 INPUT                  = @abs_srcdir@/../include \
-                         @abs_srcdir@/../source
+                         @abs_srcdir@/../source \
+                         @abs_srcdir@/../plugins
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1062,7 +1065,7 @@ SOURCE_TOOLTIPS        = YES
 # The default value is: NO.
 # This tag requires that the tag SOURCE_BROWSER is set to YES.
 
-USE_HTAGS              = YES
+USE_HTAGS              = NO
 
 # If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a
 # verbatim copy of the header file for each class for which an include is

sycl/include/CL/sycl/detail/pi.h

@@ -5,13 +5,20 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
-//
-// This is the definition of a generic offload Plugin Interface (PI), which is
-// used by the SYCL implementation to connect to multiple device back-ends,
-// e.g. to OpenCL. The interface is intentionally kept C-only for the
-// purpose of having full flexibility and interoperability with different
-// environments.
-//
+
+/// \defgroup sycl_pi The Plugin Interface
+// TODO: link to sphinx page
+
+/// \file Main Plugin Interface header file.
+///
+/// This is the definition of a generic offload Plugin Interface (PI), which is
+/// used by the SYCL implementation to connect to multiple device back-ends,
+/// e.g. to OpenCL. The interface is intentionally kept C-only for the
+/// purpose of having full flexibility and interoperability with different
+/// environments.
+///
+/// \ingroup sycl_pi
+
 #ifndef _PI_H_
 #define _PI_H_
 

sycl/include/CL/sycl/detail/pi.hpp

@@ -6,8 +6,11 @@
 //
 //===----------------------------------------------------------------------===//
 
-// C++ wrapper of extern "C" PI interfaces
-//
+/// \file pi.hpp
+/// C++ wrapper of extern "C" PI interfaces
+///
+/// \ingroup sycl_pi
+
 #pragma once
 
 #include <CL/sycl/detail/common.hpp>

sycl/plugins/cuda/pi_cuda.cpp

@@ -6,6 +6,11 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// \file pi_cuda.cpp
+/// Implementation of CUDA Plugin.
+///
+/// \ingroup sycl_pi_cuda
+
 #include <CL/sycl/backend/cuda.hpp>
 #include <CL/sycl/detail/pi.hpp>
 #include <pi_cuda.hpp>

sycl/plugins/cuda/pi_cuda.hpp

@@ -6,9 +6,14 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// This source is the definition of the SYCL Plugin Interface
-/// (PI). It is the interface between the device-agnostic SYCL runtime layer
-/// and underlying "native" runtimes such as OpenCL.
+/// \defgroup sycl_pi_cuda CUDA Plugin
+/// \ingroup sycl_pi
+
+/// \file pi_cuda.hpp
+/// Definition of CUDA Plugin. It is the interface between the device-agnostic
+/// SYCL runtime layer and underlying CUDA runtime.
+///
+/// \ingroup sycl_pi_cuda
 
 #ifndef PI_CUDA_HPP
 #define PI_CUDA_HPP

sycl/plugins/opencl/pi_opencl.cpp

@@ -5,6 +5,16 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
+
+/// \defgroup sycl_pi_ocl OpenCL Plugin
+/// \ingroup sycl_pi
+
+/// \file pi_opencl.cpp
+/// Implementation of OpenCL Plugin. It is the interface between device-agnostic
+/// SYCL runtime layer and underlying OpenCL runtime.
+///
+/// \ingroup sycl_pi_ocl
+
 #include "CL/opencl.h"
 #include <CL/sycl/detail/pi.h>
 

sycl/source/detail/pi.cpp

@@ -5,6 +5,12 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
+
+/// \file pi.cpp
+/// Implementation of C++ wrappers for PI interface.
+///
+/// \ingroup sycl_pi
+
 #include <CL/sycl/detail/common.hpp>
 #include <CL/sycl/detail/pi.hpp>
 #include <detail/plugin.hpp>

sycl/source/detail/plugin.hpp

@@ -15,6 +15,10 @@ __SYCL_INLINE_NAMESPACE(cl) {
 namespace sycl {
 namespace detail {
 
+/// The plugin class provides a unified interface to the underlying low-level
+/// runtimes for the device-agnostic SYCL runtime.
+///
+/// \ingroup sycl_pi
 class plugin {
 public:
   plugin() = delete;
@@ -25,21 +29,24 @@ class plugin {
 
   ~plugin() = default;
 
-  // Utility function to check return from PI calls.
-  // Throws if pi_result is not a PI_SUCCESS.
-  // Exception - The type of exception to throw if PiResult of a call is not
-  // PI_SUCCESS. Default value is cl::sycl::runtime_error.
+  /// Checks return value from PI calls.
+  ///
+  /// \throw Exception if pi_result is not a PI_SUCCESS.
   template <typename Exception = cl::sycl::runtime_error>
   void checkPiResult(RT::PiResult pi_result) const {
     CHECK_OCL_CODE_THROW(pi_result, Exception);
   }
 
-  // Call the PiApi, trace the call and return the result.
-  // To check the result use checkPiResult.
-  // Usage:
-  // PiResult Err = plugin.call<PiApiKind::pi>(Args);
-  // Plugin.checkPiResult(Err); <- Checks Result and throws a runtime_error
-  // exception.
+  /// Calls the PiApi, traces the call, and returns the result.
+  ///
+  /// Usage:
+  /// \code{cpp}
+  /// PiResult Err = plugin.call<PiApiKind::pi>(Args);
+  /// Plugin.checkPiResult(Err); // Checks Result and throws a runtime_error
+  /// // exception.
+  /// \endcode
+  ///
+  /// \sa plugin::checkPiResult
   template <PiApiKind PiApiOffset, typename... ArgsT>
   RT::PiResult call_nocheck(ArgsT... Args) const {
     RT::PiFuncInfo<PiApiOffset> PiCallInfo;
@@ -56,8 +63,9 @@ class plugin {
     return R;
   }
 
-  // Call the API, trace the call, check the result and throw
-  // a runtime_error Exception
+  /// Calls the API, traces the call, checks the result
+  ///
+  /// \throw cl::sycl::runtime_exception if the call was not successful.
   template <PiApiKind PiApiOffset, typename... ArgsT>
   void call(ArgsT... Args) const {
     RT::PiResult Err = call_nocheck<PiApiOffset>(Args...);