Environment redesign and test/examples review. English API revisions

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

diff --git a/include/anna/comm/functions.hpp b/include/anna/comm/functions.hpp
index 315897a..73d53b5 100644 (file)
--- a/include/anna/comm/functions.hpp
+++ b/include/anna/comm/functions.hpp
@@ -52,114 +52,106 @@ class Server;
 class Service;
 
 /**
-   functions - Metodos y variables
+   functions - Methods and variables
 */
 struct functions : public anna::app::functions {
   /**
-     Devuelve el nombre de la maquina sobre la que estamos ejecutando.
-     \return El nombre de la maquina sobre la que estamos ejecutando.
+     Returns the host name over which we are executing our process.
+     @return host name over which we are executing our process.
   */
   static std::string getHostName() throw(RuntimeException);
 
 
   /**
-   * Helper de uso externo que resuelve el nombre de la maquina recibido como parametro y devuelve
-   * la primera IP resuelta por el sistema. Tracea los aliases y sus direcciones IP, asi como el
-   * nombre oficial de la maquina.
-   *
-   * \param hostname Nombre logico del servidor que sera usado para resolver. Podria ser una cadena
-   * de la forma www.gopher.net
-   *
-   * \return Primera direccion IP retornadas por el sistema
-   *
-   * \see man gethostbyname.
+     Resolves the host name provided with the first IP returned by the system.
+     Aliases and their addresses are traced as well as the official host name.
+
+     @param hostname Logical name for the server used to resolve (could be www.gopher.net i.e.).
+
+     @return First IP address returned by the system.
+   
+     \see man gethostbyname.
    */
-  static std::string resolveIP(const char* hostname) throw(RuntimeException);   // EDU Nov 2012
+  static std::string resolveIP(const char* hostname) throw(RuntimeException);
 
   /**
-     Devuelve la referencia de la instancia de nuestra aplicación para trabajar en la
-     capa anna.comm
-     @return La referencia de la instancia de nuestra aplicación para trabajar en la
-     capa anna.comm
+     Returns our application instance on anna.comm layer.
+     @return Reference to our application instance on anna.comm layer.
   */
   static comm::Application& getApp() throw(RuntimeException);
 
   /**
-      Codifica un entero de 32 bits en buffer que debe tener, al menos, 4 bytes de longitud.
-      @param result Buffer donde vamos a codificar el número.
-      @param n Nmero a codificar.
-      \return El buffer que contiene el número aplanado.
+     Encodes an integer number with 32 bits over a buffer with at least 4 bytes of length.
+     @param result Buffer where the number is encoded.
+     @param n Number to encode.
+     \return Buffer with the encoded number.
    */
   static const char* codeInteger(char* result, const int n) throw();
 
   /**
-     Codifica un entero de 16 bits en buffer que debe tener 2 bytes de longitud.
-     @param result Buffer donde vamos a codificar el número.
-     @param n Nmero a codificar.
-     \return El buffer que contiene el número aplanado.
+     Encodes an integer number with 16 bits over a buffer with at least 2 bytes of length.
+     @param result Buffer where the number is encoded.
+     @param n Number to encode.
+     \return Buffer with the encoded number.
   */
   static const char* codeShort(char* result, const short int n) throw();
 
   /**
-      Codifica un entero de 64 bits en buffer que debe tener, al menos, 8 bytes de longitud.
-      @param result Buffer donde vamos a codificar el numero.
-      @param n numero a codificar.
-      \return El buffer que contiene el numero aplanado.
+     Encodes an integer number with 64 bits over a buffer with at least 8 bytes of length.
+     @param result Buffer where the number is encoded.
+     @param n Number to encode.
+     \return Buffer with the encoded number.
    */
   static const char* codeInteger64(char* result, const Integer64 n) throw();
 
   /**
-   * Codifica un número en coma flotante de 32 bits según el estandard IEEE-754, en un buffer
-   * que debe tener, al menos, 4 bytes de longitud.
-   * @param result Buffer donde vamos a codificar el número.
-   * @param n Nmero a codificar.
-   * \return El buffer que contiene el número aplanado.
+     Encodes a floating number with 32 bits (according to the standard IEEE-754) over a buffer with at least 4 bytes of length.
+     @param result Buffer where the number is encoded.
+     @param n Number to encode.
+     \return Buffer with the encoded number.
    */
   static const char* codeFloat(char* result, const float n) throw();
 
   /**
-   * Codifica un número en coma flotante de 64 bits según el estandard IEEE-754, en un buffer
-   * que debe tener, al menos, 8 bytes de longitud.
-   * @param result Buffer donde vamos a codificar el número.
-   * @param n Nmero a codificar.
-   * \return El buffer que contiene el número aplanado.
+     Encodes a floating number with 64 bits (according to the standard IEEE-754) over a buffer with at least 8 bytes of length.
+     @param result Buffer where the number is encoded.
+     @param n Number to encode.
+     \return Buffer with the encoded number.
    */
   static const char* codeDouble(char* result, const double n) throw();
 
   /**
-     Decodifica un numero entero de 32 bits contenido en un buffer de 4 bytes.
-     @param data Buffer que contiene el numero aplanado.
-     @return El valor del numero contenido en el buffer.
+     Decodes an 32 bits integer number contained in a 4-bytes buffer.
+     @param data Buffer with the encoded number.
+     @return Value for the number contained in the buffer.
   */
   static int decodeInteger(const char* data)  throw();
 
   /**
-     Decodifica un numero entero de 16 bits contenido en un buffer de 2 bytes.
-     @param data Buffer que contiene el numero aplanado.
-     @return El valor del numero contenido en el buffer.
+     Decodes an 16 bits integer number contained in a 2-bytes buffer.
+     @param data Buffer with the encoded number.
+     @return Value for the number contained in the buffer.
   */
   static short int decodeShort(const char* data)  throw();
 
   /**
-     Decodifica un numero entero de 64 bits contenido en un buffer de 8 bytes.
-     @param data Buffer que contiene el numero aplanado.
-     @return El valor del numero contenido en el buffer.
+     Decodes an 64 bits integer number contained in a 8-bytes buffer.
+     @param data Buffer with the encoded number.
+     @return Value for the number contained in the buffer.
   */
   static Integer64 decodeInteger64(const char* data)  throw();
 
   /**
-     Decodifica un numero en coma flotante de 32 bits contenido en un buffer de 4 bytes, y codificado
-     según el estandard IEEE-754.
-     @param data Buffer que contiene el numero aplanado.
-     @return El valor del numero contenido en el buffer.
+     Decodes an 32 bits floating number (according to the standard IEEE-754) contained in a 4-bytes buffer.
+     @param data Buffer with the encoded number.
+     @return Value for the number contained in the buffer.
   */
   static float decodeFloat(const char* data)  throw();
 
   /**
-     Decodifica un numero en coma flotante de 64 bits contenido en un buffer de 8 bytes, y codificado
-     según el estandard IEEE-754.
-     @param data Buffer que contiene el numero aplanado.
-     @return El valor del numero contenido en el buffer.
+     Decodes an 64 bits floating number (according to the standard IEEE-754) contained in a 8-bytes buffer.
+     @param data Buffer with the encoded number.
+     @return Value for the number contained in the buffer.
   */
   static double decodeDouble(const char* data)  throw();
 };