Environment redesign and test/examples review. English API revisions

[anna.git] / include / anna / comm / ReceiverFactory.hpp

diff --git a/include/anna/comm/ReceiverFactory.hpp b/include/anna/comm/ReceiverFactory.hpp
index 19578e5..3b44c8e 100644 (file)
--- a/include/anna/comm/ReceiverFactory.hpp
+++ b/include/anna/comm/ReceiverFactory.hpp
@@ -52,10 +52,9 @@ namespace comm {
 class Receiver;
 
 /**
-   Interfaz que deben cumplir las factorias de receptores.
+   Interface for receivers factories.
 
-   Es muy aconsejable que la implementacion particular de esta clase que use nuestra
-   aplicacion este basada en el uso de #Recycler<T>. Como muestra el siguiente ejemplo:
+   Is recommended (performance  issues) to use #Recycler<T> as in the following example:
 
    \code
 
@@ -74,8 +73,7 @@ class Receiver;
 
    \endcode
 
-   En la mayoria de los casos seria aconsejable usar un instancia de comm::ReceiverFactoryImpl
-   instanciado con el tipo de receptor usado por nuestra aplicacion.
+   In most of cases, is recommended to use an comm::ReceiverFactoryImpl instance with the receiver type used in our application.
 
    \see Receiver
    \see ReceiverFactoryImpl
@@ -83,32 +81,30 @@ class Receiver;
 class ReceiverFactory : public Mutex {
 public:
   /**
-     Devuelve el nombre logico de este gestor de receptores.
-     \return el nombre logico de este gestor de receptores.
+     Returns the logical name for this receiver factory. 
+     @return logical name for this receiver factory. 
   */
   const std::string& getName() const throw() { return a_name; }
 
   /**
-     Crea una instancia del receptor asociado a esta factoria, realiza las comprobaciones
-     necesarias para optimizar el reuso de instancias de la clase Receiver.
+     Creates a receiver instance for this factory. Reuse resources when needed.
 
-     \return La instancia de un nuevo receiver.
-     \warning Cada uno de los receptores obtenidos debera ser liberado invocando a #release.
+     \return The new receiver instance.
+     \warning All the receivers obtained shall be released by mean #release.
   */
   Receiver* create() throw(RuntimeException);
 
   /**
-     Libera la instancia del receptor recibido como parametro. Realiza las comprobaciones
-     necesarias para optimizar el reuso de instancias de la clase Receiver.
+     Release the receiver instance provided.
 
-     \param receiver Instancia del receiver a liberar.
-     \warning El transporte recibido como parametro debera haberse obtenido mediante #create.
+     \return The receiver instance to be released.
+     \warning The parameter should have been obtained by mean #create.
   */
   void release(Receiver* receiver) throw();
 
   /**
-     Devuelve una cadena con la informacion relevante sobre esta instancia.
-     \return una cadena con la informacion relevante sobre esta instancia.
+     Returns a string with relevant information for this instance.
+     @return string with relevant information for this instance.
   */
   std::string asString() const
   throw() {
@@ -118,44 +114,33 @@ public:
   }
 
   /**
-     Devuelve un documento XML con la informacion relevante sobre esta instancia.
-     \param parent Nodo XML del que debe depender el documento generado.
-     \return un documento XML con la informacion relevante sobre esta instancia.
+     Returns a XML document with relevant information for this instance.
+     \param parent XML node from which created data will depend on.
+     @return a XML document with relevant information for this instance.
   */
   xml::Node* asXML(xml::Node* parent) const throw();
 
 protected:
   /**
-     Constructor
-     \param name Nombre logico de esta factoria de receptores.
+     Constructor.
+     \param name Logical name for this receivers factory. 
   */
   ReceiverFactory(const char* name);
 
   /**
-     Crea realmente la instancia del receptor asociado a esta factoria, solo sera invocado
-     en caso de que no haya ninguna otra instancia disponible que pueda ser reusada.
+     Creates the receiver instance if no other reusable instance is found. This method is
+     called from a critical section activated for this instance.
 
-     La invocacion a este metodo se realiza desde una seccion critica activada sobre esta
-     instancia.
-
-     Es muy aconsejable que la implementacion particular de este metodo este basada en el
-     uso de #Recycler<T>.
-
-     \return La instancia de un nuevo receiver.
-     \warning Cada uno de los receptores obtenidos debera ser liberado invocando a #release.
+     \return The new receiver instance.
+     \warning All the receivers obtained shall be released by mean #release.
   */
   virtual Receiver* do_create() throw() = 0;
 
   /**
-     Libera realmente la instancia del receptor recibido como parametro.
-
-     Es muy aconsejable que la implementacion particular de este metodo este basada en el
-     uso de #Recycler<T>.
-
-     La invocacion a este metodo se realiza desde una seccion critica activada sobre esta
-     instancia.
+     Release the receiver provided. This method is called from a critical section activated
+     for this instance.
 
-     \param receiver Instancia del receiver a liberar.
+     \param The receiver instance to be released.
   */
   virtual void do_release(Receiver* receiver) throw() = 0;