docs: Describe behavior for user type Value specializations

lib/luwra/types.hpp

@@ -25,14 +25,12 @@ using State = lua_State;
 using CFunction = lua_CFunction;
 
 /**
- * Wrapper for a stack value
- * \note This generic version behaves like its specialization for `T&`, except that it will
- *       always copy from and to the stack (instead of referencing).
+ * User type
  */
 template <typename T>
 struct Value {
 	/**
-	 * Retrieve a value from the stack.
+	 * Copy a user type value from the stack.
 	 * \param state Lua state
 	 * \param index Position of the value
 	 */
@@ -42,9 +40,9 @@ struct Value {
 	}
 
 	/**
-	 * Push a value onto the stack.
+	 * Copy a user type value onto the stack.
 	 * \param state Lua state
-	 * \param value The value you want to push
+	 * \param value Value you want to push
 	 * \returns Number of values pushed
 	 */
 	static

lib/luwra/usertypes.hpp

@@ -115,21 +115,33 @@ namespace internal {
 }
 
 /**
- * User type T.
- * Instances created using this specialization are allocated and constructed as full user data
- * types in Lua. The default garbage-collecting hook will destruct the user type, once it has
- * been marked.
+ * User type
  */
 template <typename U>
 struct Value<U&> {
 	using T = internal::StripUserType<U>;
 
+	/**
+	 * Reference a user type value on the stack.
+	 * \param state Lua state
+	 * \param n     Stack index
+	 * \returns Reference to the user type value
+	 */
 	static inline
 	U& read(State* state, int n) {
 		// T is unqualified, therefore conversion from T& to U& is allowed
 		return *internal::check_user_type<T>(state, n);
 	}
 
+	/**
+	 * Construct a user type value on the stack.
+	 * \note Instances created using this specialization are allocated and constructed as full user
+	 *       data types in Lua. The default garbage-collecting hook will destruct the user type,
+	 *       once it has been marked.
+	 * \param state Lua state
+	 * \param args  Constructor arguments
+	 * \returns Number of values that have been pushed onto the stack
+	 */
 	template <typename... A> static inline
 	size_t push(State* state, A&&... args) {
 		void* mem = lua_newuserdata(state, sizeof(T));
@@ -150,18 +162,31 @@ struct Value<U&> {
 };
 
 /**
- * User type T.
+ * User type
  */
 template <typename U>
 struct Value<U*> {
 	using T = internal::StripUserType<U>;
 
+	/**
+	 * Reference a user type value on the stack.
+	 * \param state Lua state
+	 * \param n     Stack index
+	 * \returns Pointer to the user type value.
+	 */
 	static inline
 	U* read(State* state, int n) {
 		// T is unqualified, therefore conversion from T* to U* is allowed
 		return internal::check_user_type<T>(state, n);
 	}
 
+	/**
+	 * Copy a value onto the stack. This function behaves exactly as if you would call
+	 * `Value<U&>::push(state, *ptr)`.
+	 * \param state Lua state
+	 * \param ptr   Pointer to the user type value
+	 * \returns Number of values that have been pushed
+	 */
 	static
 	size_t push(State* state, const T* ptr) {
 		return Value<T&>::push(state, *ptr);