Resolve "Factory documentation"

Closes #299 (closed)

include/core/state_block/factory_state_block.h

 /*
- * factory_state_block.h
+ * \file factory_state_block.h
  *
  *  Created on: Apr 27, 2020
- *      Author: jsola
+ *      \author: jsola
  */
 
 #ifndef STATE_BLOCK_FACTORY_STATE_BLOCK_H_
@@ -14,13 +14,107 @@
 namespace wolf
 {
 
-// State blocks factory
+/** \brief StateBlock factory class
+ *
+ * This factory can create  objects of class StateBlock and classes deriving from StateBlock.
+ *
+ * Specific object creation is invoked by create(TYPE, state, fixed),
+ * and the TYPE of state block is identified with a string.
+ * For example, the following processor types are implemented,
+ *   - "StateBlock"         for StateBlock
+ *   - "StateQuaternion"    for StateQuaternion
+ *   - "StateAngle"         for StateAngle
+ *   - "StateHomogeneous3d" for StateHomogeneous3d
+ *
+ * The factory also creates state blocks according to the block key used in to identify state blocks in each Wolf node.
+ * These keys are single-letter strings. The following letters are implemented
+ *   - "O"  for 2d orientation, creates StateAngle
+ *   - "O"  for 3d orientation, creates StateQuaternion
+ *   - "H"  crestes StateHomogeneous3d
+ *
+ * Any other letter creates the base StateBlock.
+ *
+ * Find general Factory documentation in class Factory:
+ *   - Access the factory
+ *   - Register/unregister creators
+ *   - Invoke object creation
+ *
+ * This documentation shows you how to use the FactoryStateBlock specifically:
+ *   - Write a state block creator
+ *   - Create state blocks
+ *
+ * #### Write state block creators
+ * StateBlock creators have the following API:
+ *
+ *     \code
+ *     static StateBlockPtr create(const Eigen::VectorXd& _state, bool _fixed);
+ *     \endcode
+ *
+ * They follow the general implementation shown below:
+ *
+ *     \code
+ *      static StateBlockPtr create(const Eigen::VectorXd& _state, bool _fixed)
+ *      {
+ *          return std::make_shared<StateBlockDerived>(_state, _fixed);
+ *      }
+ *     \endcode
+ *
+ * #### Creating processors
+ * Note: Prior to invoking the creation of a processor of a derived type,
+ * you must register the creator for this type into the factory.
+ *
+ * Note: State blocks of the base type do not need to be registered.
+ *
+ * To create a StateQuaternion, you type:
+ *
+ *     \code
+ *     auto sq_ptr = FactoryStateBlock::get().create("StateQuaternion", Vector4d(1,0,0,0), false);
+ *     \endcode
+ *
+ * If your problem has dimension 3 (e.g. is 3D), you can use the key "O" to create a StateQuaternion,
+ *
+ *     \code
+ *     auto sq_ptr = FactoryStateBlock::get().create("O", Vector4d(1,0,0,0), false);
+ *     \endcode
+ *
+ * However if your problem has dimension 2 (e.g. is 2D), the key "O" will create a StateAngle,
+ *
+ *     \code
+ *     auto sa_ptr = FactoryStateBlock::get().create("O", Vector1d(angle_in_radians), false);
+ *     \endcode
+ *
+ * Note: It is an error to provide state vectors of the wrong size (4 for 3D orientation, 1 for 2D).
+ *
+ * To create StateBlocks to store 2D position and velocity, you type:
+ *
+ *     \code
+ *     auto sp2_ptr = FactoryStateBlock::get().create("StateBlock", Vector2d(1,2), false);
+ *     auto sv2_ptr = FactoryStateBlock::get().create("StateBlock", Vector2d(1,2), false);
+ *     \endcode
+ *
+ * To create StateBlocks to store 2D position and velocity, you can also use the key letters:
+ *
+ *     \code
+ *     auto sp2_ptr = FactoryStateBlock::get().create("P", Vector2d(1,2), false);
+ *     auto sv2_ptr = FactoryStateBlock::get().create("V", Vector2d(1,2), false);
+ *     \endcode
+ *
+ * To create StateBlocks to store 3D position and velocity, you type:
+ *
+ *     \code
+ *     auto sp3_ptr = FactoryStateBlock::get().create("P", Vector3d(1,2,3), false);
+ *     auto sv3_ptr = FactoryStateBlock::get().create("V", Vector3d(1,2,3), false);
+ *     \endcode
+ *
+ * Note: for base state blocks, the size is determined by the size of the provided vector parameter `VectorXd& _state`.
+ */
 typedef Factory<StateBlock, const Eigen::VectorXd&, bool> FactoryStateBlock;
 template<>
 inline std::string FactoryStateBlock::getClass() const
 {
     return "FactoryStateBlock";
 }
+
 template<>
 inline StateBlockPtr FactoryStateBlock::create(const std::string& _type, const Eigen::VectorXd& _state, bool _fixed)
 {