comment code

Author: Simon Ninon

includes/cpp_reflection/callable.hpp

@@ -9,6 +9,13 @@ namespace cpp_reflection {
 template <typename T>
 class callable;
 
+//! callable class
+//! contains an std::function corresponding to the class template
+//!
+//! simple wrapper of std::function, but inheriting from callable_base
+//! useful for storing std::function of different types in the same container
+//!
+//! uses partial template specialization for std::function like syntax (callable<void(int)>)
 template <typename ReturnType, typename... Params>
 class callable<ReturnType(Params...)> : public callable_base {
 public:
@@ -19,6 +26,7 @@ class callable<ReturnType(Params...)> : public callable_base {
     callable& operator=(const callable&) = default;
 
 public:
+    //! functor for calling internal std::function
     ReturnType operator()(Params... params) {
         return m_fct(params...);
     }

includes/cpp_reflection/callable_base.hpp

@@ -2,6 +2,8 @@
 
 namespace cpp_reflection {
 
+//! callable_base class
+//! empty base class inherited by callable class
 class callable_base {
 public:
     virtual ~callable_base(void) = default;

includes/cpp_reflection/cpp_reflection.hpp

@@ -10,6 +10,14 @@ namespace cpp_reflection {
 template <typename T>
 struct make_reflection;
 
+//! partial template specialization is not available for functions
+//! so we can't have an std::function like syntax for reflection_manager::make_reflection<>
+//! we must make reflection_manager::make_reflection<void, int, int> and can't do reflection_manager::make_reflection<void(int, int)>
+//! this is not really convenient...
+//!
+//! we get around of this limitation by wrapping this function call inside a simple struct
+//! this struct is partially specialized
+//! this way, we can do make_reflection<void(int, int)>::call(...)
 template <typename ReturnType, typename... Params>
 struct make_reflection<ReturnType(Params...)> {
     static ReturnType call(const std::string& class_name, const std::string& function_name, Params... params) {

includes/cpp_reflection/reflectable.hpp

@@ -16,6 +16,11 @@
 
 namespace cpp_reflection {
 
+//! reflectable class
+//! contains information about registered class (class name, member functions name and member functions pointers)
+//! inherits from reflectable_base in order to store reflectables of different types in the same container
+//!
+//! This class registered itself in the reflection_manager and is used by the manager during reflection
 template <typename Type>
 class reflectable : public reflectable_base {
 public:
@@ -34,14 +39,17 @@ class reflectable : public reflectable_base {
     reflectable& operator=(const reflectable& reflectable) = default;
 
 public:
-    // TO DO: COMMENT
+    //! unpack Fcts... variadic template
     template <typename Fct, typename... Fcts>
     void register_member_function(const std::pair<std::string, Fct> fct, Fcts... fcts) {
         register_member_function(fct);
         register_member_function(fcts...);
     }
 
-    // TO DO: COMMENT
+    //! register_member_function
+    //! in order to have an equivalent of std::bind with default std::placeholders, we use closures
+    //! this closure has the same signature than the registered function and simply forwards its parameters to the function
+    //! the closure is stored inside a callable<> object
     template <typename ReturnType, typename... Params>
     void register_member_function(const std::pair<std::string, ReturnType (Type::*)(Params...)> fct) {
         m_member_functions[fct.first] = std::make_shared<callable<ReturnType(Params...)>>([=] (Params... params) -> ReturnType {
@@ -73,11 +81,12 @@ class reflectable : public reflectable_base {
     std::string m_name;
 
     //! list of functions for this object
+    //! associate function name to a callable<> object
     std::map<std::string, std::shared_ptr<callable_base>> m_member_functions;
 };
 
 //! this define creates a static reflectable
-//! REGISTER_REFLECTABLE(type, (fct)) will generates a static reflectable<type> reflectable_int("type", { { "fct", &type::fct } }) var
+//! REGISTER_REFLECTABLE(type, (fct)(other_fct)) will generates a static reflectable<type> reflectable_int("type", { "fct", &type::fct }, { "other_fct", &type::other_fct }) var
 //! since it is static, the type is registered at program startup
 #define TO_STRING(val) #val
 #define MAKE_REGISTERABLE_FUNCTION(r, type, i, function) BOOST_PP_COMMA_IF(i) std::make_pair( std::string(TO_STRING(function)), &type::function )

includes/cpp_reflection/reflectable_base.hpp

@@ -6,6 +6,8 @@
 
 namespace cpp_reflection {
 
+//! reflectable<> base class
+//! used for storing reflectable<> of different types in the same container
 class reflectable_base {
 public:
     //! ctor & dotr

includes/cpp_reflection/reflection_manager.hpp

@@ -41,21 +41,31 @@ class reflection_manager {
     //! implementation
     void _register_reflectable(const reflectable_base* reflectable);
 
-    //! TODO: COMMENT
+    //! _make_reflection
+    //! this is where the reflection is done
     template <typename ReturnType, typename... Params>
     ReturnType _make_reflection(const std::string& class_name, const std::string& function_name, Params... params) {
+        //! we first search for the reflectable object matching the class name
         auto it = std::find_if(m_types.begin(), m_types.end(), [class_name](const auto& type) {
             return type->get_name() == class_name;
         });
 
+        //! if nothing is found, class is not registered
         if (it == m_types.end())
             throw reflection_exception("Class " + class_name + " is not registered as reflectable.");
 
+        //! we ask the reflectable object for a callable<> object matching the function name
+        //! get_function will throw a reflection_exception if function is not registered
+        //!
+        //! it also returns a generic std::shared_ptr<callable_base>
+        //! we dynamically cast this pointer to a callable<> object templated on the expected function signature
         auto fct = std::dynamic_pointer_cast<callable<ReturnType(Params...)>>((*it)->get_function(function_name));
 
+        //! if dynamic_cast failed, it means that the registered function has a different signature than the expected signature
         if (not fct)
             throw reflection_exception("invalid function signature for " + class_name + "::" + function_name);
 
+        //! if everything is ok, we call the function
         return (*fct)(params...);
     }