diff --git a/traits.hpp b/traits.hpp
index 471e8c1..8665470 100644
--- a/traits.hpp
+++ b/traits.hpp
@@ -27,8 +27,9 @@
 
 
 namespace cruft::vk {
+    ///////////////////////////////////////////////////////////////////////////
     /// describes the corresponding value for sType in native structures
-    template <typename T>
+    template <typename>
     struct structure_type {};
 
 
@@ -62,7 +63,10 @@ namespace cruft::vk {
 
 
     ///////////////////////////////////////////////////////////////////////////
-    template <typename T>
+    /// describes the parameter struct used to create a given vulkan type.
+    ///
+    /// explicitly does not operate on vk-cruft types, only native types.
+    template <typename>
     struct create_info { };
 
 
@@ -84,7 +88,8 @@ namespace cruft::vk {
 
 
     ///////////////////////////////////////////////////////////////////////////
-    template <typename T> struct id_traits { };
+    /// describes the native type that corresponds to a given vk-cruft type.
+    template <typename> struct id_traits { };
 
 
     //-------------------------------------------------------------------------
@@ -114,6 +119,10 @@ namespace cruft::vk {
 
 
     ///////////////////////////////////////////////////////////////////////////
+    /// describes the native type that owns a given native type, and hence
+    /// forms part of the create/destroy process.
+    ///
+    /// undefined for types that aren't `owned' types.
     template <typename> struct owner_traits {};
 
     template <> struct owner_traits<queue> { using type = device; };
@@ -124,8 +133,16 @@ namespace cruft::vk {
 
 
     ///////////////////////////////////////////////////////////////////////////
-    template <typename T> struct life_traits { };
+    /// lists the `create' and `destroy' methods for a given native type.
+    ///
+    /// XXX: if such a function does not exist anywhere then we currently use
+    /// tuple::ignore to simplify implementation elsewhere. we should probably
+    /// investigate std::is_detected for these cases though.
+    template <typename>
+    struct life_traits { };
 
+
+    //-------------------------------------------------------------------------
     template <> struct life_traits<instance> {
         static constexpr auto create  = vkCreateInstance;
         static constexpr auto destroy = vkDestroyInstance;
@@ -228,15 +245,12 @@ namespace cruft::vk {
 
 
     ///////////////////////////////////////////////////////////////////////////
-    template <typename T> struct enum_traits { };
+    /// describes the functions required to enumerate native types
+    template <typename> struct enum_traits { };
 
     template <> struct enum_traits<physical_device> {
         static constexpr auto enumerate = vkEnumeratePhysicalDevices;
     };
-
-
-    ///////////////////////////////////////////////////////////////////////////
-    template <typename T> struct format_traits {};
 }
 
 #endif