From e93ef236af7d84db53814b950d37b79cabdbe651 Mon Sep 17 00:00:00 2001 From: Mathew Sutcliffe Date: Fri, 14 Feb 2014 00:49:49 +0000 Subject: [PATCH] refs #140 doxygen, comment, and include tweaks --- src/blackmisc/tuple.h | 42 ++++++++++++++++++++++++++--------- src/blackmisc/tuple_private.h | 31 +++++++++++++++----------- 2 files changed, 49 insertions(+), 24 deletions(-) diff --git a/src/blackmisc/tuple.h b/src/blackmisc/tuple.h index de12b77be..48419cd41 100644 --- a/src/blackmisc/tuple.h +++ b/src/blackmisc/tuple.h @@ -12,11 +12,16 @@ #include "tuple_private.h" +/*! + * \defgroup Tuples + */ + /*! * \brief Macro to make a class available to TupleConverter. - * \details Put this macro anywhere in a class declaration to make it usable in TupleConverter. + * \details Put this macro anywhere in the private section of a class declaration to make it usable in TupleConverter. * \param T The name of the class. * \hideinitializer + * \ingroup Tuples */ #define BLACK_ENABLE_TUPLE_CONVERSION(T) \ public: typedef std::true_type EnabledTupleConversion; \ @@ -35,6 +40,7 @@ * \endcode * \see BLACK_DECLARE_TUPLE_CONVERSION_TEMPLATE If T is a template, use this instead. * \hideinitializer + * \ingroup Tuples */ #define BLACK_DECLARE_TUPLE_CONVERSION(T, MEMBERS) \ namespace BlackMisc \ @@ -58,6 +64,7 @@ /*! * \brief Same as BLACK_DECLARE_TUPLE_CONVERSION(), but T can be a class template. * \hideinitializer + * \ingroup Tuples */ #define BLACK_DECLARE_TUPLE_CONVERSION_TEMPLATE(T, MEMBERS) \ namespace BlackMisc \ @@ -85,28 +92,37 @@ namespace BlackMisc * \brief Class template for converting class objects to tuples * \details If a class T uses the BLACK_ENABLE_TUPLE_CONVERSION() and BLACK_DECLARE_TUPLE_CONVERSION() macros, and object * is an instance of T, then TupleConverter::toTuple(object) will return a std::tuple representing object. - * \remarks The toTuple() function is a private member of TupleConverter, and the class T is declared to be a friend. + * This tuple can then be passed to a generic function like one of those listed under See Also: + * \see BlackMisc::compare(), BlackMisc::qHash(), BlackMisc::operator<<(), BlackMisc::operator>>(), std::operator==(). + * \remarks The toTuple() function is a private member of TupleConverter, and the class T is declared to be its friend. * \nosubgrouping + * \ingroup Tuples */ template class TupleConverter { + // BLACK_DECLARE_TUPLE_CONVERSION generates an explicit specialization of TupleConverter, + // so this unspecialized template will only be used if the macro is missing. It is also + // a good place to put Doxygen comments to document the API of the macro-generated specializations. public: - //! \name Static Private Member Functions - //! @{ /*! + * \name Static Private Member Functions * \brief Returns a tuple of references to object's data members as they were declared in BLACK_DECLARE_TUPLE_CONVERSION(). * Can be used like std::tie . */ + //! @{ static std::tuple<> toTuple(const T &object) { - // BLACK_DECLARE_TUPLE_CONVERSION creates an explicit specialization of TupleConverter, - // so this unspecialized template will only be used if the macro is missing. - static_assert(std::is_void::value, // always false; is_void<> trick is just to make the condition dependent on the template parameter T "Missing BLACK_DECLARE_TUPLE_CONVERSION macro for T"); - Q_UNUSED(object); - return std::tuple<>(); // suppress "no return statement" warning + return std::tuple<>(); + } + static std::tuple<> toTuple(T &object) + { + static_assert(std::is_void::value, // always false; is_void<> trick is just to make the condition dependent on the template parameter T + "Missing BLACK_DECLARE_TUPLE_CONVERSION macro for T"); + Q_UNUSED(object); + return std::tuple<>(); } //! @} }; @@ -122,6 +138,7 @@ namespace BlackMisc * \brief Lexicographical tuple comparison function which is CValueObject-aware. * \details Tuple members which are CValueObjects are compared using the compare() friend function of CValueObject; * other tuple members are compared using operator< and operator>. + * \ingroup Tuples */ template int compare(std::tuple a, std::tuple b) @@ -131,6 +148,7 @@ namespace BlackMisc /*! * \brief Marshall the elements of a tuple into a QDBusArgument. + * \ingroup Tuples */ template QDBusArgument &operator <<(QDBusArgument &arg, std::tuple tu) @@ -139,7 +157,8 @@ namespace BlackMisc } /*! - * \brief Demarshall a QDBusArgument into the elements of a tuple. + * \brief Unmarshall a QDBusArgument into the elements of a tuple. + * \ingroup Tuples */ template const QDBusArgument &operator >>(const QDBusArgument &arg, std::tuple tu) @@ -149,9 +168,10 @@ namespace BlackMisc /*! * \brief Generate a hash value from the elements of a tuple. + * \ingroup Tuples */ template - uint qHash(std::tuple tu) + uint qHash(std::tuple tu) { return Private::TupleHelper::hash(tu); } diff --git a/src/blackmisc/tuple_private.h b/src/blackmisc/tuple_private.h index 3f50369b8..246267386 100644 --- a/src/blackmisc/tuple_private.h +++ b/src/blackmisc/tuple_private.h @@ -13,6 +13,7 @@ #include #include +#include #include #include @@ -24,39 +25,40 @@ namespace BlackMisc namespace Private { + // Using SFINAE to help detect missing BLACK_ENABLE_TUPLE_CONVERSION macro in static_assert //! \private + //! @{ + std::false_type hasEnabledTupleConversionHelper(...); + template typename T::EnabledTupleConversion hasEnabledTupleConversionHelper(T *); - //! \private - std::false_type hasEnabledTupleConversionHelper(...); - - //! \private template struct HasEnabledTupleConversion { typedef decltype(hasEnabledTupleConversionHelper(static_cast(nullptr))) type; }; + //! @} + // Using tag dispatch to select which implementation of compare() to use //! \private + //! @{ template - int compareHelper(const T &a, const T &b, std::true_type isCValueObject) + int compareHelper(const T &a, const T &b, std::true_type isCValueObjectTag) { - Q_UNUSED(isCValueObject); + Q_UNUSED(isCValueObjectTag); return compare(a, b); } - //! \private template - int compareHelper(const T &a, const T &b, std::false_type isCValueObject) + int compareHelper(const T &a, const T &b, std::false_type isCValueObjectTag) { - Q_UNUSED(isCValueObject); + Q_UNUSED(isCValueObjectTag); if (a < b) { return -1; } if (a > b) { return 1; } return 0; } - //! \private template int compareHelper(const Tu &a, const Tu &b) { @@ -65,14 +67,17 @@ namespace BlackMisc typename std::decay< typename std::tuple_element::type >::type - >::type isCValueObject; + >::type isCValueObjectTag; - return compareHelper(std::get(a), std::get(b), isCValueObject()); + return compareHelper(std::get(a), std::get(b), isCValueObjectTag()); } + //! @} #ifdef Q_COMPILER_VARIADIC_TEMPLATES + // Applying operations to all elements in a tuple, using recursion //! \private + //! @{ template struct TupleHelper { @@ -103,7 +108,6 @@ namespace BlackMisc } }; - //! \private template <> struct TupleHelper<0> { @@ -116,6 +120,7 @@ namespace BlackMisc template static uint hash(const Tu &) { return 0; } }; + //! @} #endif // Q_COMPILER_VARIADIC_TEMPLATES