Add implementation comments

Signed-off-by: Larsen, Steffen <[email protected]>

Author: steffenlarsen

sycl/include/sycl/ext/oneapi/weak_object.hpp

@@ -29,6 +29,11 @@ template <int Dims> static range<Dims> createDummyRange() {
 }
 } // namespace detail
 
+// The weak_object class.
+// Since we use std::shared_ptr to implementations as a way to handle common
+// reference semantics in SYCL classes, the implementation of the weak_object
+// class holds a weak_ptr to the implementations. The weak_ptr is in the
+// weak_object_base class.
 template <typename SYCLObjT>
 class weak_object : public detail::weak_object_base<SYCLObjT> {
 public:
@@ -138,6 +143,7 @@ class weak_object<buffer<T, Dimensions, AllocatorT>>
   }
 
 private:
+  // Additional members required for recreating buffers.
   range<Dimensions> MRange;
   size_t MOffsetInBytes;
   bool MIsSubBuffer;

sycl/include/sycl/ext/oneapi/weak_object_base.hpp

@@ -52,6 +52,7 @@ template <typename SYCLObjT> class weak_object_base {
   }
 
 protected:
+  // Store a weak variant of the impl in the SYCLObjT.
   typename std::invoke_result_t<
       decltype(sycl::detail::getSyclObjImpl<SYCLObjT>), SYCLObjT>::weak_type
       MObjWeakPtr;