fix comments

Signed-off-by: Tikhomirova, Kseniya <kseniya.tikhomirova@intel.com>

Author: KseniyaTikhomirova

libsycl/include/sycl/__impl/backend.hpp

@@ -23,7 +23,7 @@
 
 _LIBSYCL_BEGIN_NAMESPACE_SYCL
 
-// SYCL 2020 4.1. Backends
+// SYCL 2020 4.1. Backends.
 enum class backend : unsigned char {
   opencl = 0,
   level_zero,
@@ -35,7 +35,7 @@ namespace detail {
 template <typename T> struct is_backend_info_desc : std::false_type {};
 } // namespace detail
 
-// SYCL 2020  4.5.1.1. Type traits backend_traits
+// SYCL 2020  4.5.1.1. Type traits backend_traits.
 template <backend Backend> class backend_traits;
 
 template <backend Backend, typename SyclType>

libsycl/include/sycl/__impl/detail/obj_utils.hpp

@@ -61,7 +61,7 @@ SyclObject createSyclObjFromImpl(From &&from) {
   return ImplUtils::createSyclObjFromImpl<SyclObject>(std::forward<From>(from));
 }
 
-// SYCL 2020 4.5.2. Common reference semantics (std::hash support)
+// SYCL 2020 4.5.2. Common reference semantics (std::hash support).
 template <typename T> struct HashBase {
   size_t operator()(const T &Obj) const {
     auto &Impl = sycl::detail::getSyclObjImpl(Obj);

libsycl/include/sycl/__impl/exception.hpp

@@ -44,16 +44,29 @@ enum class errc : int {
   backend_mismatch = 14,
 };
 
-/// Constructs an error code using E and sycl_category()
+/// Constructs an error code using sycl::errc and sycl_category().
+///
+/// \param E SYCL 2020 error code.
+///
+/// \returns constructed error code.
 _LIBSYCL_EXPORT std::error_code make_error_code(sycl::errc E) noexcept;
 
 /// Obtains a reference to the static error category object for SYCL errors.
+///
+/// This object overrides the virtual function error_category::name() to return
+/// a pointer to the string "sycl". When the implementation throws an
+/// sycl::exception object Ex with this category, the error code value contained
+/// by the exception (Ex.code().value()) is one of the enumerated values in
+/// sycl::errc.
+///
+/// \returns the error category object for SYCL errors.
 _LIBSYCL_EXPORT const std::error_category &sycl_category() noexcept;
 
-// Derive from std::exception so uncaught exceptions are printed in c++ default
-// exception handler.
-// Virtual inheritance is mandated by SYCL 2020.
-// SYCL 2020 4.13.2. Exception class interface
+/// \brief SYCL 2020 exception class (4.13.2.) for sync and async error handling
+/// in a SYCL application (host code).
+///
+/// Derived from std::exception so uncaught exceptions are printed in c++
+/// default exception handler. Virtual inheritance is mandated by SYCL 2020.
 class _LIBSYCL_EXPORT exception : public virtual std::exception {
 public:
   exception(std::error_code, const char *);
@@ -70,11 +83,26 @@ class _LIBSYCL_EXPORT exception : public virtual std::exception {
 
   virtual ~exception();
 
+  /// Returns the error code stored inside the exception.
+  ///
+  /// \returns the error code stored inside the exception.
   const std::error_code &code() const noexcept;
+
+  /// Returns the error category of the error code stored inside the exception.
+  ///
+  /// \returns the error category of the error code stored inside the exception.
   const std::error_category &category() const noexcept;
 
+  /// Returns string that describes the error that triggered the exception.
+  ///
+  /// \returns an implementation-defined non-null constant C-style string that
+  /// describes the error that triggered the exception.
   const char *what() const noexcept final;
 
+  /// Checks if the exception has an associated SYCL context.
+  ///
+  /// \returns true if this SYCL exception has an associated SYCL context and
+  /// false if it does not.
   bool has_context() const noexcept;
 
 private:
@@ -84,8 +112,7 @@ class _LIBSYCL_EXPORT exception : public virtual std::exception {
   std::error_code MErrC = make_error_code(sycl::errc::invalid);
 };
 
-/// Used as a container for a list of asynchronous exceptions
-///
+/// \brief Used as a container for a list of asynchronous exceptions.
 class _LIBSYCL_EXPORT exception_list {
 public:
   using value_type = std::exception_ptr;
@@ -95,10 +122,21 @@ class _LIBSYCL_EXPORT exception_list {
   using iterator = std::vector<std::exception_ptr>::const_iterator;
   using const_iterator = std::vector<std::exception_ptr>::const_iterator;
 
+  /// Returns the size of the list.
+  ///
+  /// \returns the size of the list.
   size_type size() const;
-  // first asynchronous exception
+
+  /// Returns an iterator to the beginning of the list of asynchronous
+  /// exceptions.
+  ///
+  /// \returns an iterator to the beginning of the list of asynchronous
+  /// exceptions.
   iterator begin() const;
-  // refer to past-the-end last asynchronous exception
+
+  /// Returns an iterator to the end of the list of asynchronous exceptions.
+  ///
+  /// \returns an iterator to the end of the list of asynchronous exceptions.
   iterator end() const;
 
 private:

libsycl/include/sycl/__impl/info/desc_base.hpp

@@ -7,7 +7,7 @@
 //===----------------------------------------------------------------------===//
 ///
 /// \file
-/// This file contains helpers for info descriptors
+/// This file contains helpers for info descriptors.
 ///
 //===----------------------------------------------------------------------===//
 

libsycl/include/sycl/__impl/info/platform.hpp

@@ -28,10 +28,10 @@ template <typename T>
 using is_platform_info_desc_t = typename is_info_desc<T, platform>::return_type;
 } // namespace detail
 
-// SYCL 2020 A.1. Platform information descriptors
+// SYCL 2020 A.1. Platform information descriptors.
 namespace info {
 namespace platform {
-// SYCL 2020 4.6.2.4. Information descriptors
+// SYCL 2020 4.6.2.4. Information descriptors.
 struct version : detail::info_desc_tag<version, sycl::platform> {
   using return_type = std::string;
 };

libsycl/include/sycl/__impl/platform.hpp

@@ -29,7 +29,8 @@ namespace detail {
 class platform_impl;
 } // namespace detail
 
-// SYCL 2020 4.6.2. Platform class
+/// \brief SYCL 2020 platform class (4.6.2.) encapsulating a single SYCL
+/// platform on which kernel functions may be executed.
 class _LIBSYCL_EXPORT platform {
 public:
   platform(const platform &rhs) = default;
@@ -46,7 +47,7 @@ class _LIBSYCL_EXPORT platform {
 
   /// Returns the backend associated with this platform.
   ///
-  /// \return the backend associated with this platform
+  /// \return the backend associated with this platform.
   backend get_backend() const noexcept;
 
   /// Queries this SYCL platform for info.

libsycl/src/detail/global_objects.hpp

@@ -21,9 +21,19 @@ _LIBSYCL_BEGIN_NAMESPACE_SYCL
 namespace detail {
 class platform_impl;
 
-// Offload topologies (one per backend) discovered from liboffload.
+/// Returns offload topologies (one per backend) discovered from liboffload.
+///
+/// This vector is populated only once at the first call of get_platforms().
+///
+/// \returns std::vector of all offload topologies.
 std::vector<detail::OffloadTopology> &getOffloadTopologies();
 
+/// Returns implementation class objects for all platforms discovered from
+/// liboffload.
+///
+/// This vector is populated only once at the first call of get_platforms().
+///
+/// \returns std::vector of implementation objects for all platforms.
 std::vector<std::unique_ptr<platform_impl>> &getPlatformCache();
 
 } // namespace detail

libsycl/src/detail/offload/offload_topology.cpp

@@ -34,14 +34,14 @@ void discoverOffloadDevices() {
         ol_platform_handle_t Plat = nullptr;
         ol_result_t Res = call_nocheck(
             olGetDeviceInfo, Dev, OL_DEVICE_INFO_PLATFORM, sizeof(Plat), &Plat);
-        // If error occures, ignore platform and continue iteration
+        // If error occurs, ignore platform and continue iteration
         if (Res != OL_SUCCESS)
           return true;
 
         ol_platform_backend_t OlBackend = OL_PLATFORM_BACKEND_UNKNOWN;
         Res = call_nocheck(olGetPlatformInfo, Plat, OL_PLATFORM_INFO_BACKEND,
                            sizeof(OlBackend), &OlBackend);
-        // If error occures, ignore platform and continue iteration
+        // If error occurs, ignore platform and continue iteration
         if (Res != OL_SUCCESS)
           return true;
 

libsycl/src/detail/offload/offload_topology.hpp

@@ -21,7 +21,7 @@ _LIBSYCL_BEGIN_NAMESPACE_SYCL
 
 namespace detail {
 
-// Minimal span-like view
+// Minimal span-like view.
 template <class T> struct range_view {
   T *ptr{};
   size_t len{};
@@ -34,28 +34,42 @@ template <class T> struct range_view {
 using PlatformWithDevStorageType =
     std::unordered_map<ol_platform_handle_t, std::vector<ol_device_handle_t>>;
 
-// Contiguous global storage of platform handlers and device handles (grouped by
-// platform) for a backend.
+/// Contiguous global storage of platform handlers and device handles (grouped
+/// by platform) for a backend.
 struct OffloadTopology {
   OffloadTopology() : MBackend(OL_PLATFORM_BACKEND_UNKNOWN) {}
   OffloadTopology(ol_platform_backend_t OlBackend) : MBackend(OlBackend) {}
 
+  /// Updates backend for this topology.
+  ///
+  /// \param B new backend value.
   void set_backend(ol_platform_backend_t B) { MBackend = B; }
 
-  // Platforms for this backend
+  /// Returns all platforms associated with this topology.
+  ///
+  /// \returns minimal span-like view to platforms associated with this
+  /// topology.
   range_view<const ol_platform_handle_t> platforms() const {
     return {MPlatforms.data(), MPlatforms.size()};
   }
 
-  // Devices for a specific platform (platform_id is index into Platforms)
+  /// Returns all devices associated with specific platform.
+  ///
+  /// \param PlatformId platform_id is index into Platforms.
+  ///
+  /// \returns minimal span-like view to devices associated with specified
+  /// platform.
   range_view<const ol_device_handle_t>
   devicesForPlatform(size_t PlatformId) const {
     if (PlatformId >= MDevRangePerPlatformId.size())
       return {nullptr, 0};
     return MDevRangePerPlatformId[PlatformId];
   }
 
-  // Register new platform and devices into this topology under that platform.
+  /// Register new platform and devices into this topology.
+  ///
+  /// \param PlatformsAndDev associative container with platforms & devices.
+  /// \param TotalDevCount total device count for the platform.
   void
   registerNewPlatformsAndDevices(PlatformWithDevStorageType &PlatformsAndDev,
                                  size_t TotalDevCount) {
@@ -77,6 +91,9 @@ struct OffloadTopology {
     assert(TotalDevCount == MDevices.size());
   }
 
+  /// Queries backend of this topology.
+  ///
+  /// \returns backend of this topology.
   ol_platform_backend_t backend() const { return MBackend; }
 
 private:

libsycl/src/detail/offload/offload_utils.cpp

@@ -11,8 +11,8 @@
 _LIBSYCL_BEGIN_NAMESPACE_SYCL
 namespace detail {
 
-const char *stringifyErrorCode(ol_errc_t error) {
-  switch (error) {
+const char *stringifyErrorCode(ol_errc_t Error) {
+  switch (Error) {
 #define _OFFLOAD_ERRC(NAME)                                                    \
   case NAME:                                                                   \
     return #NAME;