docs: Extend documentation

lib/luwra/generic.hpp

@@ -53,9 +53,19 @@ namespace internal {
 
 LUWRA_NS_END
 
+/**
+ * Generate a `lua_CFunction` wrapper for a field, method or function.
+ * \returns Wrapped entity as `lua_CFunction`
+ */
 #define LUWRA_WRAP(entity) \
 	(&luwra::internal::GenericWrapper<decltype(&entity)>::template invoke<&entity>)
 
+/**
+ * Generate a user type member manifest (pair).
+ * \param type Qualified struct/class name
+ * \param name Member name
+ * \returns `std::pair<const char*, CFunction>` which can be used to register a user type member
+ */
 #define LUWRA_MEMBER(type, name) \
 	{__STRING(name), LUWRA_WRAP(type::name)}
 

lib/luwra/stack.hpp

@@ -73,22 +73,24 @@ namespace internal {
  *
  * \tparam S Signature in the form of `R(A...)` where `A` is a sequence of types, which shall be
  *           retrieved from the stack, and `R` the return type of `hook`
- * \tparam F An instance of `Callable` which accepts parameters `A...` and returns `R`
+ * \tparam F An instance of `Callable` which accepts parameters `X..., A...` and returns `R`
  *           (this parameter should be inferable and can be omitted)
+ * \tparam X Extra argument types
  *
  * \param state Lua state instance
  * \param pos   Index of the first value
  * \param hook  Callable value
+ * \param args  Extra arguments which shall be be passed to `hook` before the stack values
  *
  * \returns Result of calling `hook`
  */
-template <typename S, typename F, typename... A> static inline
-typename internal::Layout<S>::ReturnType direct(State* state, int pos, F&& hook, A&&... args) {
+template <typename S, typename F, typename... X> static inline
+typename internal::Layout<S>::ReturnType direct(State* state, int pos, F&& hook, X&&... args) {
 	return internal::Layout<S>::direct(
 		state,
 		pos,
 		std::forward<F>(hook),
-		std::forward<A>(args)...
+		std::forward<X>(args)...
 	);
 }
 
@@ -106,7 +108,7 @@ typename internal::Layout<S>::ReturnType direct(State* state, F&& hook, A&&... a
 }
 
 /**
- * Synonym for `direct` with a function pointer which lets you omit all template parameters.
+ * Synonym for [direct](@ref direct) with a function pointer which lets you omit all template parameters.
  * The stack layout will be inferred using the signature of the given function pointer.
  */
 template <typename R, typename... A> static inline
@@ -123,7 +125,7 @@ R apply(State* state, R (* fun)(A...)) {
 }
 
 /**
- * Synonym for `direct` with a function object which lets you omit all template parameters.
+ * Synonym for [direct](@ref direct) with a function object which lets you omit all template parameters.
  * The stack layout will be inferred using the template parameter to your `std::function` object.
  */
 template <typename R, typename... A> static inline
@@ -180,7 +182,7 @@ namespace internal {
 }
 
 /**
- * Similiar to `direct` but pushes the result of the given `Callable` onto the stack.
+ * Similiar to [direct](@ref direct) but pushes the result of the given `Callable` onto the stack.
  * \returns Number of values pushed
  */
 template <typename S, typename F, typename... A> static inline

lib/luwra/types.hpp

@@ -24,7 +24,11 @@ using State = lua_State;
 using CFunction = lua_CFunction;
 
 /**
- * A value on the stack
+ * Wrapper for a stack value
+ * \note This generic version should not be used since it does not implement anything.
+ *       It is not always obvious whether you have used this generic instance or not. Therefore this
+ *       class produces an error message when it is being used. Look for `Parameter to Value is not
+ *       supported` in your compiler output.
  */
 template <typename T>
 struct Value {
@@ -32,8 +36,24 @@ struct Value {
 		sizeof(T) == -1,
 		"Parameter to Value is not supported"
 	);
-};
 
+	/**
+	 * Retrieve a value from the stack.
+	 * \param state Lua state
+	 * \param index Position of the value
+	 */
+	static
+	T read(State* state, int index);
+
+	/**
+	 * Push a value onto the stack.
+	 * \param state Lua state
+	 * \param value The value you want to push
+	 * \returns Number of values pushed
+	 */
+	static
+	int push(State* state, T value);
+};
 
 // Nil
 template <>
@@ -52,7 +72,7 @@ struct Value<std::nullptr_t> {
 };
 
 /**
- * Convenient wrapped for `Value<T>::push`.
+ * Convenient wrapped for [Value<T>::push](@ref Value<T>::push).
  */
 template <typename T> static inline
 int push(State* state, T value) {
@@ -60,7 +80,7 @@ int push(State* state, T value) {
 }
 
 /**
- * Convenient wrapper for `Value<T>::read`.
+ * Convenient wrapper for [Value<T>::read](@ref Value<T>::read).
  */
 template <typename T> static inline
 T read(State* state, int index) {

lib/luwra/usertypes.hpp

@@ -173,8 +173,16 @@ struct Value<U*> {
 
 /**
  * Register the metatable for user type `T`. This function allows you to register methods
- * which are shared across all instances of this type. A garbage-collector hook is also inserted.
- * Meta-methods can be added and/or overwritten aswell.
+ * which are shared across all instances of this type.
+ *
+ * By default a garbage-collector hook and string representation function are added as meta methods.
+ * Both can be overwritten.
+ *
+ * \tparam U User type struct or class
+ *
+ * \param state        Lua state
+ * \param methods      Map of methods
+ * \param meta_methods Map of meta methods
  */
 template <typename U> static inline
 void registerUserType(
@@ -239,7 +247,7 @@ namespace internal {
 }
 
 /**
- * Same as other `registerUserType` but registers the construtor as well. Also template parameter
+ * Same as the other `registerUserType` but registers the construtor as well. The template parameter
  * is a signature `U(A...)` where `U` is the user type and `A...` its constructor parameters.
  */
 template <typename T> static inline