More documentation

include/gp/iterator.hpp

@@ -4,6 +4,7 @@
 #include <cstdint>
 
 // BUG: none of this is in a namespace
+// TODO: Specify the concept of an iterator
 
 /**
  * @brief An enumeration that may be used to determine iterator categories

include/gp/quotient_filter.hpp

@@ -11,7 +11,11 @@
 
 namespace gp {
 
+	// TODO: Specify the concept of a skipstone
 
+	/**
+	 * @brief An abstraction for exploring and picking in a list sequencially
+	 */
 	struct linear_skipstone {
 		constexpr static size_t ccbits = 1;
 		constexpr static size_t cclast = 1;
@@ -24,6 +28,9 @@ namespace gp {
 		}
 	};
 
+	/**
+	 * @brief An abstraction for exploring and picking in a list in a non sequencial but still relatively cache friendly way
+	 */
 	struct stepcache_skipstone {
 		constexpr static size_t ccbits = 7;
 		constexpr static size_t cclast = 127;
@@ -73,6 +80,15 @@ namespace gp {
 		}
 	};
 
+	/**
+	 * @brief A datastructure to accurately check belonging in a set in a probabilistic way.
+	 * More precise than a bloomfilter, less space efficient, can allow deletion (handle with care)
+	 * 
+	 * @tparam hash_type the type of hash storage type
+	 * @tparam magnitude the size of the filter as a power of 2
+	 * @tparam remainder the number of bits of remainder of the quotient \f$\frac{h}{m}\f$ where \f$h\f$ is a hash and \f$m\f$ the magnitude of the set, can throw away bits
+	 * @tparam skipstone_t the type of sequence exploration to perform
+	 */
 	template<typename hash_type = uint32_t, uint8_t magnitude = 20, uint8_t remainder = (8*sizeof(hash_type))-magnitude, typename skipstone_t = linear_skipstone>
 	class quotient_filter {
 		constexpr static size_t phys_size = (1 << magnitude) / 32;

include/gp/rendering/bmp_viewport.hpp

@@ -10,6 +10,12 @@
 #include <iostream>
 
 namespace gp{
+	/**
+	 * @brief A bmp format viewport that can be used to generate and export bmp file contents
+	 * 
+	 * @tparam lazy if true, will expect the source to be a function, else would expect it to be a buffer
+	 * @tparam color_type the type that represents the color. as of now only gp::vec4_g<uint8_t> is supported
+	 */
 	template<bool lazy, typename color_type>
 	class bmp_viewport {
 	public:

include/gp/rendering/renderer.hpp

@@ -33,6 +33,10 @@ struct render_point{
 using sdf_t = gp::function<render_point(vec3&)>;
 using material_t = gp::function<color_t(vec3&)>;
 
+
+/**
+ * @brief A pure ray-marching renderer. Prints pixels on order.
+ */
 class renderer {
 	using g_t = gp_config::rendering::default_type;
 	constexpr static auto epsilon = gp_config::rendering::epsilon;

include/gp/variant.hpp

@@ -15,6 +15,11 @@
 
 namespace gp{
 
+	/**
+	 * @brief A form of variant that expect only classes whose size is strictly defined at compile time
+	 * 
+	 * @tparam T The list of types accepted by the variant
+	 */
 	template<typename ...T>
 	class fixed_variant final {
 		std::size_t index = std::numeric_limits<std::size_t>::max();
@@ -29,6 +34,12 @@ namespace gp{
 		: fixed_variant(typename first_of<T...>::type{})
 		{}
 
+		/**
+		 * @brief Construct a new fixed variant from an object that is legal in it
+		 * 
+		 * @tparam U A type that belongs in the list of types the variant supports
+		 * @param value The copied value
+		 */
 		template<typename U, std::enable_if_t<list_contains_class<gp::remove_cvref_t<U>,T...>::value,int> = 0>
 		fixed_variant(U& value)
 		: index{r_index_of<gp::remove_cvref_t<U>, T...>::value}
@@ -52,6 +63,12 @@ namespace gp{
 		static_assert(list_contains_class<int, char, int, char>::value, "list_contains_class doesn't work properly");
 		static_assert(!list_contains_class<int, char, char>::value, "list_contains_class doesn't work properly");
 
+		/**
+		 * @brief Construct a new fixed variant from an object that is legal in it by moving said object
+		 * 
+		 * @tparam U A type that belongs in the list of types the variant supports
+		 * @param value The moved value
+		 */
 		template<typename U, std::enable_if_t<list_contains_class<gp::remove_cvref_t<U>,T...>::value,int> = 0>
 		fixed_variant(U&& value)
 		: index{r_index_of<gp::remove_cvref_t<U>, T...>::value}
@@ -97,11 +114,24 @@ namespace gp{
 			mvtor(oth.buffer, buffer);
 		}
 
+		/**
+		 * @brief Gives an alternative (value usable in a switch statement) representing the given type
+		 * 
+		 * @tparam U the type to match against
+		 * @return constexpr size_t a value that can be used in the case part of a switch case statement
+		 * @see type()
+		 */
 		template<typename U>
 		constexpr static size_t alt() {
 			return r_index_of<U, T...>::value;
 		}
 
+		/**
+		 * @brief Gives the type as can be matched in a switch statement using alternatives
+		 * 
+		 * @return size_t a value that can be used in the switch part of a switch case statement
+		 * @see alt()
+		 */
 		size_t type() const {
 			return index;
 		}
@@ -170,6 +200,13 @@ namespace gp{
 			}
 		}
 
+		/**
+		 * @brief Brutally decay the variant into the given type. 
+		 Will throw (@see bad_variant_access) if exceptions are enabled, else behaviour is undefined.
+		 * 
+		 * @tparam U the type to decay towards
+		 * @return constexpr U& a decayed reference to the variant
+		 */
 		template<typename U>
 		constexpr U& value()
 		{
@@ -183,6 +220,13 @@ namespace gp{
 			return *reinterpret_cast<U*>(buffer);
 		}
 
+		/**
+		 * @brief Tests if the variant is of a particular type.
+		 * 
+		 * @tparam U the type to match against
+		 * @return true if the types match 
+		 * @return false if the types don't match
+		 */
 		template<typename U>
 		constexpr bool is_a()
 		{

include/gp/vector.hpp

@@ -6,6 +6,12 @@
 #include <initializer_list>
 
 namespace gp{
+	/**
+	 * @brief A vector type most similar to that of the standard library
+	 * Always uses polymorphic allocation, no small value optimization
+	 *
+	 * @tparam T 
+	 */
 	template<typename T>
 	class vector final {
 		T* ary = nullptr;
@@ -116,11 +122,26 @@ namespace gp{
 			}
 		}
 
+		/**
+		 * @brief Ensures the vector can hold at least 1 more element
+		 * 
+		 * @return true if it is at least now possible to fit one more element
+		 * @return false if fiting one more element is not possible even now
+		 */
 		bool grow() {
 			if(sz == cap) return reserve(1 + sz + (sz >> 1));
 			return true;
 		}
 
+		/**
+		 * @brief Reserves space so that the capacity is at least equal to the provided value.
+		 * 
+		 * This will never shrink the datastructure
+		 *
+		 * @param new_cap the new capacity
+		 * @return true on success
+		 * @return false on failure
+		 */
 		bool reserve(size_t new_cap) {
 			if(new_cap <= cap) return true;
 
@@ -147,6 +168,13 @@ namespace gp{
 
 		constexpr const T& operator[] (size_t off) const
 		{
+			if constexpr (gp_config::has_buffer_bounds)
+			{
+				gp_config::assertion(
+					off < sz,
+					"Array bounds infringed"
+				);
+			}
 			return ary[off];
 		}
 
@@ -160,6 +188,13 @@ namespace gp{
 			return cap;
 		}
 
+		/**
+		 * @brief Adds the provided value to the vector
+		 * 
+		 * @param value 
+		 * @return true on success
+		 * @return false on failure
+		 */
 		constexpr bool push_back(T& value) {
 			if(grow()) {
 				new(ary+sz) T(value);
@@ -169,6 +204,14 @@ namespace gp{
 			return false;
 		}
 
+
+		/**
+		 * @brief Moves the provided value to the vector
+		 * 
+		 * @param value 
+		 * @return true on success
+		 * @return false on failure
+		 */
 		constexpr bool push_back(T&& value) {
 			if(grow()) {
 				new(ary+sz) T(gp::move(value));
@@ -178,6 +221,13 @@ namespace gp{
 			return false;
 		}
 
+		/**
+		 * @brief Constructs a new element at the end of the vector
+		 * 
+		 * @param value the parameters to be sent to the constructor of T
+		 * @return true on success
+		 * @return false on failure
+		 */
 		template<typename ...U>
 		constexpr bool emplace_back(U&&... value) {
 			if(grow()) {
@@ -188,6 +238,11 @@ namespace gp{
 			return false;
 		}
 
+		/**
+		 * @brief moves the last element of the vector out if it exists, returning an optional.
+		 * 
+		 * @return constexpr gp::optional<T> contains a value if it existed, else it is empty
+		 */
 		constexpr gp::optional<T> pop_back() {
 			if(sz == 0) return gp::nullopt;
 			sz--;
@@ -253,6 +308,12 @@ namespace gp{
 			return !(*this == oth);
 		}
 
+		/**
+		 * @brief Provides a span access to the vector
+		 * 
+		 * @return A buffer of the vector. 
+		 * It is invalidated by any operation that may change the size of the vector.
+		 */
 		gp::buffer<T> as_buffer()
 		{
 			return gp::buffer<T>{(T*)ary, (T*)ary+sz};