Update Factory documentation

include/core/common/factory.h

@@ -50,28 +50,28 @@ namespace wolf
  * - Examples of specific factories existing in Wolf are:
  *   \code
  *
- *   // SensorFactory
- *      typedef Factory<SensorBase,                     // Type of objects to be created: SensorBasePtr
- *                      const std::string&,             // Name of the sensor
- *                      const Eigen::VectorXd&,         // Sensor extrinsics
- *                      const ParamsSensorBasePtr>      // Sensor parameters
- *              SensorFactory;
- *
- *   // ProcessorFactory
- *      typedef Factory<ProcessorBase,                  // Type of object created: ProcessorBasePtr
- *                      const std::string&,             // Name of the processor
- *                      const ParamsProcessorBasePtr>   // Parameters for creating the processor
- *              ProcessorFactory;
+ *   // FactorySensor
+ *   typedef Factory<SensorBase,                     // Type of objects to be returned: SensorBasePtr
+ *                   const std::string&,             // Type of the sensor: name of the derived sensor class
+ *                   const Eigen::VectorXd&,         // Sensor extrinsics
+ *                   const ParamsSensorBasePtr>      // Sensor parameters
+ *           FactorySensor;
+ *
+ *   // FactoryProcessor
+ *   typedef Factory<ProcessorBase,                  // Type of object returned: ProcessorBasePtr
+ *                   const std::string&,             // Type of the processor: name of the derived processor class
+ *                   const ParamsProcessorBasePtr>   // Parameters for creating the processor
+ *           FactoryProcessor;
  *
  *   // AutoConfProcessorFactory
- *      typedef Factory<ProcessorBase,                  // Type of object created: ProcessorBasePtr
- *                      const std::string&,             // Name of the processor
- *                      const ParamsServer>             // Parameters for creating the processor
- *              AutoConfProcessorFactory;
+ *   typedef Factory<ProcessorBase,                  // Type of object returned: ProcessorBasePtr
+ *                   const std::string&,             // Type of the processor: name of the derived processor class
+ *                   const ParamsServer>             // Parameters for creating the processor
+ *           AutoConfProcessorFactory;
  *
  *   // Landmarks from YAML
- *   typedef Factory<LandmarkBase,                      // Type of node created: LandmarkBasePtr
- *                   const YAML::Node&>                 // YAML node with the lmk params
+ *   typedef Factory<LandmarkBase,                   // Type of node created: LandmarkBasePtr
+ *                   const YAML::Node&>              // YAML node with the lmk params
  *           LandmarkFactory;
  *   \endcode
  *
@@ -86,7 +86,7 @@ namespace wolf
  * > The specific type of landmark (e.g. LandmarkCorner2d, LandmarkAHP, LandmarkPolyline2d, etc) is indicated by a string that we call TYPE in this documentation.
  *
  * Specific object creation is invoked by the method ````create(TYPE, params ... )````, where
- *   - the TYPE of object to create is identified with a string
+ *   - the TYPE of object to create is identified with a string. This string matches the name of the derived class.
  *   - the params may be provided in different forms -- see TypeInput.
  *
  * The methods to create specific objects are called __creators__.
@@ -102,9 +102,11 @@ namespace wolf
  *
  * #### Define correct TYPE names
  * We use a std::string with literally the same text as the derived class name, e.g.:
- *   - ParamsSensorCamera  -> ````"ParamsSensorCamera"````
- *   - ParamsSensorLaser2d -> ````"ParamsSensorLaser2d"````
- *   - LandmarkPolyline2d  -> ````"LandmarkPolyline2d"````
+ *   - ParamsSensorCamera   -> ````"ParamsSensorCamera"````
+ *   - SensorCamera         -> ````"SensorCamera"````
+ *   - ParamsSensorLaser2d  -> ````"ParamsSensorLaser2d"````
+ *   - SensorLaser2d        -> ````"SensorLaser2d"````
+ *   - LandmarkPolyline2d   -> ````"LandmarkPolyline2d"````
  *   - etc.
  *
  * #### Access the factory
@@ -112,12 +114,18 @@ namespace wolf
  * The first thing to know is that we have defined typedefs for the templates that we are using. For example:
  *
  * \code
- * typedef Factory<ParamsSensorBase, std::string>        FactoryParamsSensor;
- * typedef Factory<ParamsProcessorBase, std::string>   FactoryParamsProcessor;
- * typedef Factory<LandmarkBase, YAML::Node>           FactoryLandmark;
+ * typedef Factory<ParamsSensorBase, std::string>       FactoryParamsSensor;
+ * typedef Factory<ParamsProcessorBase, std::string>    FactoryParamsProcessor;
+ * typedef Factory<LandmarkBase, YAML::Node>            FactoryLandmark;
+ * typedef Factory<SensorBase,
+ *                 const std::string&,
+ *                 const Eigen::VectorXd&,
+ *                 const ParamsSensorBasePtr>           FactorySensor;
+ *
  * \endcode
  *
- * Second to know, the Factory class is a <a href="http://stackoverflow.com/questions/1008019/c-singleton-design-pattern#1008289">singleton</a>: it can only exist once in your application.
+ * Second to know, the Factory class is a <a href="http://stackoverflow.com/questions/1008019/c-singleton-design-pattern#1008289">singleton</a>:
+ * it can only exist once in your application.
  * To access it, use the static method get(),
  *
  *     \code
@@ -150,7 +158,7 @@ namespace wolf
  *
  *      \code
  *      static ParamsSensorBasePtr create(const std::string& _intrinsics_dot_yaml)
- *      static LandmarkBasePtr   create(const YAML::Node& _lmk_yaml_node)
+ *      static LandmarkBasePtr     create(const YAML::Node&  _lmk_yaml_node)
  *      \endcode
  *
  * See further down for an implementation example.
@@ -164,7 +172,7 @@ namespace wolf
  * that knows how to create your specific object, e.g.:
  *
  *     \code
- *     FactoryLandmark::get().registerCreator("POLYLINE 2d", LandmarkPolyline2d::create);
+ *     FactoryLandmark::get().registerCreator("LandmarkPolyline2d", LandmarkPolyline2d::create);
  *     \endcode
  *
  * #### Automatic registration
@@ -172,7 +180,7 @@ namespace wolf
  * For example, in sensor_camera_yaml.cpp we find the line:
  *
  *     \code
- *     const bool registered_camera_intr = FactoryParamsSensor::get().registerCreator("CAMERA", createParamsSensorCamera);
+ *     const bool registered_camera_intr = FactoryParamsSensor::get().registerCreator("ParamsSensorCamera", createParamsSensorCamera);
  *     \endcode
  *
  * which is a static invocation (i.e., it is placed at global scope outside of the ParamsSensorCamera class).
@@ -183,7 +191,7 @@ namespace wolf
  * The method unregisterCreator() unregisters the ObjectXxx::create() method. It only needs to be passed the string of the object type.
  *
  *     \code
- *     Factory<MyTypeBase, MyTypeInput>::get().unregisterCreator("CAMERA");
+ *     Factory<MyTypeBase, MyTypeInput>::get().unregisterCreator("ParamsSensorCamera");
  *     \endcode
  *
  * #### Create objects using the factory
@@ -193,13 +201,13 @@ namespace wolf
  * To create e.g. a LandmarkPolyline2d from a YAML node you type:
  *
  *     \code
- *     LandmarkBasePtr lmk_ptr = Factory<LandmarkBasePtr, YAML::Node>::get().create("POLYLINE 2d", lmk_yaml_node);
+ *     LandmarkBasePtr lmk_ptr = Factory<LandmarkBasePtr, YAML::Node>::get().create("LandmarkPolyline2d", lmk_yaml_node);
  *     \endcode
  *
  * or even better, make use of the convenient typedefs:
  *
  *     \code
- *     LandmarkBasePtr lmk_ptr = FactoryLandmark::get().create("POLYLINE 2d", lmk_yaml_node);
+ *     LandmarkBasePtr lmk_ptr = FactoryLandmark::get().create("LandmarkPolyline2d", lmk_yaml_node);
  *     \endcode
  *
  * ### Examples
@@ -224,7 +232,7 @@ namespace wolf
  *    }
  *
  *    // Create a new landmark
- *    LandmarkBasePtr lmk_ptr = new LandmarkPolyline2d(points, first_defined, last_defined, first_id);
+ *    LandmarkBasePtr lmk_ptr = std::make_shared<LandmarkPolyline2d>(points, first_defined, last_defined, first_id);
  *    lmk_ptr->setId(id);
  *
  *    return lmk_ptr;
@@ -239,7 +247,7 @@ namespace wolf
  * // Register landmark creator (put the register code inside an unnamed namespace):
  *  namespace
  *  {
- *  const bool registered_lmk_polyline_2d = FactoryLandmark::get().registerCreator("POLYLINE 2d", LandmarkPolyline2d::create);
+ *  const bool registered_lmk_polyline_2d = FactoryLandmark::get().registerCreator("LandmarkPolyline2d", LandmarkPolyline2d::create);
  *  }
  *
  * \endcode