[DOC] add a basic sample with all assiciated doc and tutorial

doc/mainpage.md

@@ -1,8 +1,10 @@
 ESIGNAL library                                {#mainpage}
 ===============
 
-What is ESIGNAL, and how can I use it?
-----------------------------------
+@tableofcontents
+
+What is ESIGNAL, and how can I use it?         {#esignal_mainpage_what}
+======================================
 
 ESIGNAL, or Ewol signal engine is a simple messaging layer, managing multiple connection and manage disconnection
 
@@ -12,20 +14,20 @@ ESIGNAL is designed for
   - Manage versatil connection/disconnection
 
 
-What languages are supported?
------------------------------
+What languages are supported?                   {#esignal_mainpage_language}
+=============================
 
 ESIGNAL is written in C++.
 
 
-Are there any licensing restrictions?
--------------------------------------
+Are there any licensing restrictions?           {#esignal_mainpage_restriction}
+=====================================
 
 ESIGNAL is **FREE software** and _all sub-library are FREE and staticly linkable !!!_
 
 
-License (APACHE-2.0)
---------------------
+License (APACHE-2.0)                            {#esignal_mainpage_license}
+====================
 
 Copyright esignal Edouard DUPIN
 

doc/tutorial.md

@@ -0,0 +1,112 @@
+Tutorial                                         {#esignal_tutorial}
+========
+
+@tableofcontents
+
+Declare a Signal:                                {#esignal_declare}
+=================
+
+Declaring a signal is really simple, just include the esignal file:
+
+@snippet sampleAll.cpp esignal_sample_declare
+
+You can now declare your signals. We have basicly declare some basic signal type:
+  - void
+  - bool
+  - std::string / std::u32string
+  - int8_t / int16_t / int32_t / int64_t
+  - uint8_t / uint16_t / uint32_t / uint64_t
+  - float / double
+  - vec2 / bvec2 / ivec2 / uivec2
+  - vec3 / bvec3 / ivec3 / uivec3
+  - etk::Color<unsigned char,4>
+  - etk::Color<unsigned char,3>
+  - etk::Color<float,4>
+  - etk::Color<float,3>
+
+To declare a signal with 'void' type:
+@snippet sampleAll.cpp esignal_sample_declare_void
+
+To declare a signal with 'int32_t' type:
+@snippet sampleAll.cpp esignal_sample_declare_int
+
+To declare a signal with 'string' type:
+@snippet sampleAll.cpp esignal_sample_declare_string
+
+
+Connecting on a signal                           {#esignal_connection}
+======================
+
+We have some way to connect on a signals depending on where we do the connection.
+
+Connection and basic emition                     {#esignal_connection_base}
+----------------------------
+
+Declare the signal:
+@snippet sampleAll.cpp esignal_sample_connection_simple_connection_declare
+
+Declare a generic fuction:
+@snippet sampleAll.cpp esignal_sample_connection_simple_extern_function
+
+Connect a generic function:
+@snippet sampleAll.cpp esignal_sample_connection_simple_connection_function
+
+Or simply connect a lambda function:
+@snippet sampleAll.cpp esignal_sample_connection_simple_connection_lambda
+
+And now, we can emit a simple signal:
+@snippet sampleAll.cpp esignal_sample_connection_simple_emit
+
+You can see that all connection return a esignal::Connection value. This is an handle that can not be copiable, but only movable, While this handle is alive, the connection is allive too.
+The to remove a connection, we only need to remive the handle or call the esignal::Connection::disconnect fucntion.
+
+To disconnect a signal, it is very simple:
+@snippet sampleAll.cpp esignal_sample_connection_simple_disconnect
+
+
+This Will generate this simple sample code:
+@snippet sampleAll.cpp esignal_sample_connection_simple
+
+
+Connection on class member function                     {#esignal_connection_class}
+-----------------------------------
+
+Declare class fuction:
+@snippet sampleAll.cpp esignal_sample_class_connection_callback
+
+For direct connection, you need to have a 'const ref' on the parameter (internal helper design) to bind on the signal
+
+Now you can nonnect the functions:
+@snippet sampleAll.cpp esignal_sample_class_connection_callback_connect
+
+This Will generate this simple sample code:
+@snippet sampleAll.cpp esignal_sample_class_connection
+
+Connection on std::shared_ptr<class> member function                     {#esignal_connection_shared}
+----------------------------------------------------
+
+std::hared_ptr have intrinsec knoledge of alive pointer, then, if you do not need to remove connection while the shared_ptr is alive, just connect it like:
+@snippet sampleAll.cpp esignal_sample_shared_connection
+
+Create new Signal                           {#esignal_create}
+=================
+
+If the signal is not in the list: @ref esignal_declare, you need to declare it yourself. This is due to optimise the compilation time,
+in C++ when we inserte many template with all the implementation, the compilation time increase, the we decide to optimise the build time.
+
+Create a new custum signal:
+@snippet sampleAll.cpp esignal_sample_new_declare
+
+Connect on the Signal:
+@snippet sampleAll.cpp esignal_sample_new_lambda
+
+Emit a Signal:
+@snippet sampleAll.cpp esignal_sample_new_emit
+
+This might work good, but at this point the compilation is OK, but not the linking ==> we need to declare the implementation of the signal:
+@snippet sampleAll.cpp esignal_sample_new_register
+
+
+
+This Will generate this simple sample code:
+@snippet sampleAll.cpp esignal_sample_new

doxy_esignal.py

@@ -14,6 +14,9 @@ def create(target, module_name):
 	    module_name,
 	    "doc"
 	    ])
+	my_module.add_sample_path([
+	    "sample"
+	    ])
 	my_module.add_module_depend([
 	    'etk',
 	    'ememory'

esignal/Base.cpp

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved

esignal/Base.h

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved
@@ -17,6 +17,9 @@
 #include <mutex>
 #include <esignal/LockSharedPtrRef.h>
 
+/**
+ * @brief esignal global interface for all signal implementation
+ */
 namespace esignal {
 	/**
 	 * @brief Base signal interface for esignal::Signal (permit to create abstract list of signals...)
@@ -30,13 +33,19 @@ namespace esignal {
 			static int64_t s_uidSignalEmit; //!< global id to emit counting
 			ObserverConnection m_connectionObserver; //!< propriétéry of the connection handle basic
 		public:
-			//! @brief Basic constructor:
+			/**
+			 * @brief Basic constructor:
+			 * @param[in] _countObs Observer on the number of connection availlable
+			 */
 			Base(ObserverConnection _countObs = nullptr);
 			//! @brief Copy constructor:
 			Base(const Base&) = delete;
 			//! @brief Move constructor
-			Base(Base&& _obj) = delete;
-			
+			Base(Base&&) = delete;
+			/**
+			 * @brief Virtualize the destructor
+			 * @internal
+			 */
 			virtual ~Base();
 			/**
 			 * @brief Disconnect the shared_ptr form the Signal

esignal/Connection.cpp

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved

esignal/Connection.h

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved
@@ -22,21 +22,42 @@ namespace esignal {
 	 */
 	class Connection {
 		public:
-			//! @brief Constructor (no link)
+			/**
+			 * @brief Constructor (no link)
+			 */
 			Connection();
-			//! @brief Constructor (link)
+			/**
+			 * @brief Constructor (link)
+			 * @param[in] _ref Reference ID of the Signal extern handle
+			 * @param[in] _id Id of the Connection handle
+			 */
 			Connection(const esignal::LockSharedPtrRef<esignal::Base>& _ref, size_t _id);
-			//! @brief Move Constructor
+			/**
+			 * @brief Move Constructor
+			 * @param[in] _obj Connection Object to move
+			 */
 			Connection(Connection&& _obj);
-			//! @brief Move operator.
+			/**
+			 * @brief Move operator.
+			 * @param[in] _obj Connection Object to move
+			 * @return Local reference on the local object (moved)
+			 */
 			Connection& operator=(Connection&& _obj);
-			//! @brief Copy constructor (REMOVED)
+			/**
+			 * @brief Copy constructor (REMOVED)
+			 */
 			Connection(const Connection&) = delete;
-			//! @brief Copy operator (REMOVED)
+			/**
+			 * @brief Copy operator (REMOVED)
+			 */
 			Connection& operator=(const Connection&) = delete;
-			//! @brief Destructor.
+			/**
+			 * @brief Destructor.
+			 */
 			~Connection();
-			//! @brief Disconnect the signal.
+			/**
+			 * @brief Disconnect the signal.
+			 */
 			void disconnect();
 			/**
 			 * @brief Check if the connection is alive or signal removed

esignal/ISignal.h

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved
@@ -14,9 +14,6 @@
 #include <esignal/Signal.h>
 #include <esignal/Interface.h>
 
-#undef __class__
-#define __class__ "ISignal<T_ARGS>"
-
 namespace esignal {
 	/**
 	 * @brief Sigla same as @ref esignal::Signal withe a name and a description to manage a list of signals.
@@ -74,6 +71,3 @@ esignal::ISignal<T_ARGS...>::ISignal(CLASS_TYPE* _class,
 	}
 }
 
-
-#undef __class__
-#define __class__ nullptr

esignal/Interface.h

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved
@@ -14,7 +14,7 @@
 namespace esignal {
 	/**
 	 * @brief Interface to collect the Signal list (for abstarction connection)
-	 * It create a simple "signal" member that permit to access at the signalproperties.
+	 * It create a simple "signals" member that permit to access at the signalproperties.
 	 */
 	class Interface {
 		public:

esignal/InterfaceData.cpp

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved

esignal/InterfaceData.h

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved

esignal/LockSharedPtrRef.h

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved

esignal/RefCount.h

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved

esignal/Signal.h

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved
@@ -19,9 +19,6 @@
 #include <utility>
 #include <mutex>
 
-#undef __class__
-#define __class__ "Signal<T_ARGS>"
-
 namespace esignal {
 	/**
 	 * @brief Basic signal base
@@ -254,6 +251,3 @@ esignal::Signal<T_ARGS...>::Signal(CLASS_TYPE* _class,
   m_callInProgress(0) {
 	// nothing to do
 }
-
-#undef __class__
-#define __class__ nullptr

esignal/debug.cpp

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved

esignal/debug.h

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved

esignal/details/ISignal.cpp

@@ -11,8 +11,6 @@
 #include <etk/math/Vector3D.h>
 #include <etk/Color.h>
 
-#undef __class__
-#define __class__ "ISignal<void>"
 // void generic signal
 template class esignal::ISignal<>;
 // std generic signal

esignal/details/ISignal.hxx

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved

esignal/details/LockSharedPtrRef.cpp

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved

esignal/details/LockSharedPtrRef.hxx

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved

esignal/details/RefCount.cpp

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved

esignal/details/RefCount.hxx

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved

esignal/details/Signal.cpp

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved
@@ -11,8 +11,6 @@
 #include <etk/math/Vector3D.h>
 #include <etk/Color.h>
 
-#undef __class__
-#define __class__ "Signal<void>"
 // void generic signal
 template class esignal::Signal<>;
 // std generic signal

esignal/details/Signal.hxx

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved

lutin_esignal-sample.py

@@ -0,0 +1,34 @@
+#!/usr/bin/python
+import lutin.module as module
+import lutin.tools as tools
+import datetime
+
+def get_type():
+	return "BINARY"
+
+def get_sub_type():
+	return "SAMPLE"
+
+def get_desc():
+	return "e-signal sample 1"
+
+def get_licence():
+	return "APACHE-2"
+
+def get_compagny_type():
+	return "com"
+
+def get_compagny_name():
+	return "atria-soft"
+
+def get_maintainer():
+	return ["Mr DUPIN Edouard <yui.heero@gmail.com>"]
+
+def create(target, module_name):
+	my_module = module.Module(__file__, module_name, get_type())
+	my_module.add_src_file([
+		'sample/sampleAll.cpp'
+		])
+	my_module.add_module_depend(['esignal', 'test-debug'])
+	return my_module
+

sample/sampleAll.cpp

@@ -0,0 +1,156 @@
+/** @file
+ * @author Edouard DUPIN
+ * 
+ * @copyright 2016, Edouard DUPIN, all right reserved
+ * 
+ * @license APACHE v2.0 (see license file)
+ */
+#include <etk/etk.h>
+#include <test-debug/debug.h>
+
+//! [esignal_sample_declare]
+#include <esignal/Signal.h>
+//! [esignal_sample_declare]
+
+void declareSignals() {
+	//! [esignal_sample_declare_int]
+	esignal::Signal<int32_t> signalInt;
+	//! [esignal_sample_declare_int]
+	
+	//! [esignal_sample_declare_void]
+	esignal::Signal<> signalVoid;
+	//! [esignal_sample_declare_void]
+	
+	//! [esignal_sample_declare_string]
+	esignal::Signal<std::string> signalString;
+	//! [esignal_sample_declare_string]
+}
+
+//! [esignal_sample_connection_simple]
+//! [esignal_sample_connection_simple_extern_function]
+void localCallBack(int32_t _val) {
+	TEST_PRINT("Callback Local the value is : " << _val);
+}
+//! [esignal_sample_connection_simple_extern_function]
+
+void basicConnection() {
+	// Create the signal
+	//! [esignal_sample_connection_simple_connection_declare]
+	esignal::Signal<int32_t> signalValue;
+	//! [esignal_sample_connection_simple_connection_declare]
+	// Connect the signal function
+	//! [esignal_sample_connection_simple_connection_function]
+	esignal::Connection con1 = signalValue.connect(&localCallBack);
+	//! [esignal_sample_connection_simple_connection_function]
+	// Connect the signal Lambda
+	//! [esignal_sample_connection_simple_connection_lambda]
+	esignal::Connection con2 = signalValue.connect(
+	    [](int32_t _val) {
+	    	TEST_PRINT("Callback 1 the value is : " << _val);
+	    });
+	//! [esignal_sample_connection_simple_connection_lambda]
+	// Emit the signal
+	//! [esignal_sample_connection_simple_emit]
+	signalValue.emit(1001001);
+	//! [esignal_sample_connection_simple_emit]
+	// Disconnect the connection n°1
+	//! [esignal_sample_connection_simple_disconnect]
+	con1.disconnect();
+	//! [esignal_sample_connection_simple_disconnect]
+	// Second emit to check disconnection
+	signalValue.emit(2002002);
+}
+//! [esignal_sample_connection_simple]
+
+//*********************************************************************************************
+
+//! [esignal_sample_class_connection]
+//! [esignal_sample_class_connection_callback]
+class TmpClass {
+	public:
+		void localCallBack(const int32_t& _val) {
+			TEST_PRINT("Callback Local the value is : " << _val);
+		}
+		void localCallBackSecond(const int32_t& _val, const std::string& _otherValue) {
+			TEST_PRINT("Callback 2 Local the value is : " << _val << " with perso: '" << _otherValue << "'");
+		}
+};
+//! [esignal_sample_class_connection_callback]
+
+void classConnection() {
+	// Create the signal
+	esignal::Signal<int32_t> signalValue;
+	// Declare the class
+	TmpClass myClass;
+	// Connect signals
+	//! [esignal_sample_class_connection_callback_connect]
+	esignal::Connection con1 = signalValue.connect(&myClass, &TmpClass::localCallBack);
+	esignal::Connection con2 = signalValue.connect(&myClass, &TmpClass::localCallBackSecond, "Hello, HowAreYou");
+	//! [esignal_sample_class_connection_callback_connect]
+	// Emit sample signals
+	signalValue.emit(4004004);
+}
+
+//! [esignal_sample_class_connection]
+
+
+//! [esignal_sample_shared_connection]
+
+void sharedConnection() {
+	// Create the signal
+	esignal::Signal<int32_t> signalValue;
+	// Declare the class
+	std::shared_ptr<TmpClass> myClassShared = std::make_shared<TmpClass>();
+	// Connect signals
+	signalValue.connect(myClassShared, &TmpClass::localCallBack);
+	// Emit sample signals
+	signalValue.emit(7007007);
+}
+//! [esignal_sample_shared_connection]
+
+
+//! [esignal_sample_new]
+
+void newSignal() {
+	// Declare new signal
+	//! [esignal_sample_new_declare]
+	esignal::Signal<int32_t, std::string> signalCustum;
+	//! [esignal_sample_new_declare]
+	// Connect a lambda
+	//! [esignal_sample_new_lambda]
+	esignal::Connection con2 = signalCustum.connect(
+	    [](int32_t _val, std::string _val2) {
+	    	TEST_PRINT("lambda callback: " << _val << " vel2=" << _val2);
+	    });
+	//! [esignal_sample_new_lambda]
+	// Example emit
+	//! [esignal_sample_new_emit]
+	signalCustum.emit(1001001, "plop");
+	//! [esignal_sample_new_emit]
+}
+
+// do it in a single C++: Implementation of signal
+//! [esignal_sample_new_register]
+#include <esignal/details/Signal.hxx>
+template class esignal::Signal<int32_t, std::string>;
+//! [esignal_sample_new_register]
+
+//! [esignal_sample_new]
+
+
+int main(int _argc, const char *_argv[]) {
+	etk::init(_argc, _argv);
+	TEST_INFO("declare [START] ***************************");
+	declareSignals();
+	TEST_INFO("declare [STOP]  ***************************");
+	TEST_INFO("Basic connection [START] ***************************");
+	basicConnection();
+	TEST_INFO("Basic connection [STOP] ***************************");
+	TEST_INFO("class connection [START] ***************************");
+	classConnection();
+	TEST_INFO("class connection [STOP] ***************************");
+	TEST_INFO("shared_ptr connection [START] ***************************");
+	sharedConnection();
+	TEST_INFO("shared_ptr connection [STOP] ***************************");
+	return 0;
+}

test/main.cpp

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved
@@ -12,9 +12,6 @@
 #include <test-debug/debug.h>
 #include <gtest/gtest.h>
 
-#undef __class__
-#define __class__	"esignal-test"
-
 int main(int _argc, const char *_argv[]) {
 	::testing::InitGoogleTest(&_argc, const_cast<char **>(_argv));
 	etk::init(_argc, _argv);

test/test_isignal.cpp

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved
@@ -14,9 +14,6 @@
 #include <test-debug/debug.h>
 
 
-#undef __class__
-#define __class__ "test_isignal"
-
 class testISignal : public esignal::Interface {
 	public:
 		esignal::ISignal<int32_t> m_signalInt;

test/test_signal_class_func.cpp

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved
@@ -13,9 +13,6 @@
 #include <memory>
 #include <test-debug/debug.h>
 
-
-#undef __class__
-#define __class__ "test_signal_class_func"
 class testCallback {
 	public:
 		int32_t m_int32;

test/test_signal_counter.cpp

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved
@@ -13,9 +13,6 @@
 #include <memory>
 #include <test-debug/debug.h>
 
-
-#undef __class__
-#define __class__ "test_signal_counter"
 class testCounter {
 	public:
 		esignal::Signal<std::string> m_signal;

test/test_signal_recursive.cpp

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved
@@ -13,10 +13,6 @@
 #include <memory>
 #include <test-debug/debug.h>
 
-
-#undef __class__
-#define __class__ "test_signal_static_func"
-
 static esignal::Signal<int32_t>* signalll;
 static int32_t tmpRetInt32 = 0;
 

test/test_signal_shared_ptr_func.cpp

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved
@@ -13,9 +13,6 @@
 #include <memory>
 #include <test-debug/debug.h>
 
-
-#undef __class__
-#define __class__ "test_signal_class_func"
 class testCallbackShared : public std::enable_shared_from_this<testCallbackShared> {
 	public:
 		int32_t m_int32;

test/test_signal_static_func.cpp

@@ -1,4 +1,4 @@
-/**
+/** @file
  * @author Edouard DUPIN
  * 
  * @copyright 2016, Edouard DUPIN, all right reserved
@@ -13,10 +13,6 @@
 #include <memory>
 #include <test-debug/debug.h>
 
-
-#undef __class__
-#define __class__ "test_signal_static_func"
-
 static int32_t tmpRetInt32 = 0;
 static std::string tmpRetString = "";
 static bool tmpRetVoid = false;