From 4f7e12951cf9a0b3179e3b4e03f5029722c2aee1 Mon Sep 17 00:00:00 2001
From: Danny Robson <danny@nerdcruft.net>
Date: Fri, 1 Sep 2017 12:33:41 +1000
Subject: [PATCH] object: add some top level comments

---
 object.hpp | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/object.hpp b/object.hpp
index 803922e..0320cc2 100644
--- a/object.hpp
+++ b/object.hpp
@@ -12,7 +12,7 @@
  * limitations under the License.
  *
  * Copyright:
- *      2016, Danny Robson <danny@nerdcruft.net>
+ *      2016-2017, Danny Robson <danny@nerdcruft.net>
  */
 
 #ifndef CRUFT_VK_OBJECT_HPP
@@ -25,6 +25,8 @@
 #include <vector>
 
 namespace cruft::vk {
+    /// the base class for all non-trivial vulkan objects requiring lifetime
+    /// management.
     template <typename T>
     struct object {
         using id_t = typename id_traits<T>::id_t;
@@ -41,6 +43,9 @@ namespace cruft::vk {
     };
 
 
+    /// a vulkan object that must be directly instantiated through
+    /// constructor arguments, rather than being enumerated and owned by
+    /// another object.
     template <typename T>
     struct instantiated : public object<T> {
         using id_t = typename object<T>::id_t;
@@ -67,6 +72,8 @@ namespace cruft::vk {
         }
     };
 
+
+    /// a vulkan object that is obtained by listings from a parent object.
     template <typename T>
     struct enumerated : public object<T> {
         using object<T>::object;
@@ -74,6 +81,11 @@ namespace cruft::vk {
         static std::vector<T> find (const instance&);
     };
 
+
+    /// a vulkan object that is directly owned by a parent object.
+    ///
+    /// typically implies that this object must be freed using a reference to
+    /// the parent object.
     template <typename T, typename O>
     struct owned : public object<T> { };
 }