Core/Flags: Add documentation

include/Nazara/Core/Flags.inl

@@ -10,71 +10,150 @@ namespace Nz
 	/*!
 	* \ingroup core
 	* \class Nz::Flags
-	* \brief Core class that represents a set of bits
-	*
-	* This class meets the requirements of Container, AllocatorAwareContainer, SequenceContainer
+	* \brief Core class used to combine enumeration values into flags bitfield
 	*/
 
+    /*!
+    * \brief Constructs a Flags object using a bitfield
+    *
+    * \param value Bitfield to be used
+	*
+	* Uses a bitfield to builds the flag value. (e.g. if bit 0 is active, then Enum value 0 will be set as active).
+    */
 	template<typename E>
 	constexpr Flags<E>::Flags(UInt32 value) :
 	m_value(value)
 	{
 	}
 
+	/*!
+	* \brief Constructs a Flags object using an Enum value
+	*
+	* \param value enumVal
+	*
+	* Setup a Flags object with only one flag active (corresponding to the enum value passed as argument).
+	*/
 	template<typename E>
 	constexpr Flags<E>::Flags(E enumVal) :
 	Flags(GetFlagValue(enumVal))
 	{
 	}
 
+	/*!
+	* \brief Tests a Flags
+	* \return True if any flag is enabled.
+	*
+	* This will convert to a boolean value allowing to check if any flag is set.
+	*/
 	template<typename E>
 	constexpr Flags<E>::operator bool() const
 	{
 		return m_value != 0;
 	}
 
+	/*!
+	* \brief Converts to a bitfield
+	* \return Enabled flags as a bitfield.
+	*
+	* This will convert to a bitfield value.
+	*/
 	template<typename E>
 	constexpr Flags<E>::operator UInt32() const
 	{
 		return m_value;
 	}
 
+	/*!
+	* \brief Reverse flag states
+	* \return Opposite enabled flags
+	*
+	* This will returns a copy of the Flags object with reversed flags states.
+	*/
 	template<typename E>
 	constexpr Flags<E> Flags<E>::operator~() const
 	{
 		return Flags(~m_value);
 	}
 
+	/*!
+	* \brief Compare flag states
+	* \return Shared flags
+	*
+	* \param rhs Flags to compare with.
+	*
+	* This will returns a copy of the Flags object with only enabled flags in common with the parameter
+	*/
 	template<typename E>
 	constexpr Flags<E> Flags<E>::operator&(Flags rhs) const
 	{
 		return Flags(m_value & rhs.m_value);
 	}
 
+	/*!
+	* \brief Combine flag states
+	* \return Combined flags
+	*
+	* This will returns a copy of the Flags object with combined flags from the parameter.
+	*
+	* \param rhs Flags to combine with.
+	*/
 	template<typename E>
 	constexpr Flags<E> Flags<E>::operator|(Flags rhs) const
 	{
 		return Flags(m_value | rhs.m_value);
 	}
 
+	/*!
+	* \brief XOR flag states
+	* \return XORed flags.
+	*
+	* \param rhs Flags to XOR with.
+	*
+	* This performs a XOR (Exclusive OR) on a copy of the flag object.
+	* This will returns a copy of the object with disabled common flags and enabled unique ones.
+	*/
 	template<typename E>
 	constexpr Flags<E> Flags<E>::operator^(Flags rhs) const
 	{
 		return Flags(m_value ^ rhs.m_value);
 	}
 
+	/*!
+	* \brief Check equality with flag object
+	* \return True if both flags objects have the same states.
+	*
+	* \param rhs Flags to compare with.
+	*
+	* Compare two Flags object and returns true if the flag states are identical.
+	*/
 	template<typename E>
 	constexpr bool Flags<E>::operator==(Flags rhs) const
 	{
 		return m_value == rhs.m_value;
 	}
 
+	/*!
+	* \brief Check inequality with flag object
+	* \return True if both flags objects have different states.
+	*
+	* \param rhs Flags to compare with.
+	*
+	* Compare two Flags object and returns true if the flag states are identical.
+	*/
 	template<typename E>
 	constexpr bool Flags<E>::operator!=(Flags rhs) const
 	{
 		return !operator==(rhs);
 	}
 
+	/*!
+	* \brief Combine flag states
+	* \return A reference to the object.
+	*
+	* \param rhs Flags to combine with.
+	*
+	* This will enable flags which are enabled in parameter object and not in Flag object.
+	*/
 	template<typename E>
 	/*constexpr*/ Flags<E>& Flags<E>::operator|=(Flags rhs)
 	{
@@ -83,6 +162,14 @@ namespace Nz
 		return *this;
 	}
 
+	/*!
+	* \brief Compare flag states
+	* \return A reference to the object.
+	*
+	* \param rhs Flags to compare with.
+	*
+	* This will disable flags which are disabled in parameter object and enabled in Flag object (and vice-versa).
+	*/
 	template<typename E>
 	/*constexpr*/ Flags<E>& Flags<E>::operator&=(Flags rhs)
 	{
@@ -91,6 +178,15 @@ namespace Nz
 		return *this;
 	}
 
+	/*!
+	* \brief XOR flag states
+	* \return A reference to the object.
+	*
+	* \param rhs Flags to XOR with.
+	*
+	* This performs a XOR (Exclusive OR) on the flag object.
+	* This will disable flags enabled in both Flags objects and enable those enabled in only one of the Flags objects.
+	*/
 	template<typename E>
 	/*constexpr*/ Flags<E>& Flags<E>::operator^=(Flags rhs)
 	{
@@ -99,6 +195,14 @@ namespace Nz
 		return *this;
 	}
 
+	/*!
+	* \brief Returns a bitfield corresponding to an enum value.
+	* \return Bitfield representation of the enum value
+	*
+	* \param enumValue Enumeration value to get as a bitfield.
+	*
+	* Internally, every enum option is turned into a bit, this function allows to get a bitfield with only the bit of the enumeration value enabled.
+	*/
 	template<typename E>
 	constexpr UInt32 Flags<E>::GetFlagValue(E enumValue)
 	{
@@ -106,24 +210,61 @@ namespace Nz
 	}
 
 
+	/*!
+	* \brief Override binary NOT operator on enum to turns into a Flags object.
+	* \return A Flags object with reversed bits.
+	*
+	* \param lhs Enumeration value to reverse.
+	*
+	* Returns a Flags object with all state enabled except for the enum one.
+	*/
 	template<typename E>
 	constexpr std::enable_if_t<EnableFlagsOperators<E>::value, Flags<E>> operator~(E lhs)
 	{
 		return ~Flags<E>(lhs);
 	}
 
+	/*!
+	* \brief Override binary OR operator on enum to turns into a Flags object.
+	* \return A Flags object with combined enum states.
+	*
+	* \param lhs First enumeration value to combine.
+	* \param rhs Second enumeration value to combine.
+	*
+	* Returns a Flags object with combined states from the two enumeration values.
+	*/
 	template<typename E>
 	constexpr std::enable_if_t<EnableFlagsOperators<E>::value, Flags<E>> operator|(E lhs, E rhs)
 	{
 		return Flags<E>(lhs) | rhs;
 	}
 
+	/*!
+	* \brief Override binary AND operator on enum to turns into a Flags object.
+	* \return A Flags object with compare enum states.
+	*
+	* \param lhs First enumeration value to compare.
+	* \param rhs Second enumeration value to compare.
+	*
+	* Returns a Flags object with compared states from the two enumeration values.
+	* In this case, only one flag will be enabled if both enumeration values are the same.
+	*/
 	template<typename E>
 	constexpr std::enable_if_t<EnableFlagsOperators<E>::value, Flags<E>> operator&(E lhs, E rhs)
 	{
 		return Flags<E>(lhs) & rhs;
 	}
 
+	/*!
+	* \brief Override binary XOR operator on enum to turns into a Flags object.
+	* \return A Flags object with XORed enum states.
+	*
+	* \param lhs First enumeration value to compare.
+	* \param rhs Second enumeration value to compare.
+	*
+	* Returns a Flags object with XORed states from the two enumeration values.
+	* In this case, two flags will be enabled if both the enumeration values are different.
+	*/
 	template<typename E>
 	constexpr std::enable_if_t<EnableFlagsOperators<E>::value, Flags<E>> operator^(E lhs, E rhs)
 	{