Errores que hay evitar al redactar especificaciones
===================================================

(***) En la especificación se habla del QUÉ
SI==> /// Ordena el vector \c "V[]" de dimensión \c "n"
      void Sort( unsigned n, T V[] );

(***) Es un error hablar del CÓMO en la especificación
NO==> /// Intercambia los valores hasta que ya no están desordenados
      void Sort( unsigned n, T V[] );



(***) En la especificación no se habla del Rep
NO==> /// Agrega el nodo al final
      void list::push_back( const T& v );

(***) Es un error hablar del Rep cuando se redacta la especificación

NO==> /// Si <code> m_last!=0 </code> borra el nodo del frente
      void list::pop_front();

SI==> /// Elimina el primer valor del contenedor
      /// \pre <code> !empty() </code>
      void list::pop_front();

(***) Si la clase "lista" contiene "nodos" en su parte privada es incorrecto
      hablar de "nodos" en la especificación.
(***) Si la clase "lista" usa "punteros" en su parte privada es incorrecto
      hablar de "punteros" en la especificación.



(***) Es un error hablar de la implementación cuando se redacta la especificación

NO==> /// Usa cirugía de punteros para poner al último nodo de primero
      void list::z_splice();

SI==> /// Traslada el último valor de \c "*this" y lo coloca de primero
      /// \remark No copia el valor
      /// \pre <code> !empty() </code>
      void list::z_splice();


(***) Es incorrecto omitir información que el programador cliente necesita
      para poder usar la clase, método o función.
(***) Debe incluir suficiente información para que el programador cliente
      pueda usar la clase, método o función.

NO==> /// Esta función traslada valores de la lista
      /// void z_splice();

SI==> /// Traslada el último valor de \c "*this" y lo coloca de primero
      /// \remark No copia el valor
      /// \pre <code> !empty() </code>
      void list::z_splice();



(***) Es incorrecto mencionar los campos privados del Rep de una clase
      en la especificación de cualquiera de sus métodos.

NO==> /// Si <code> m_first!=0 </code> borra el nodo del frente
      void list::pop_front();

SI==> /// Elimina el primer valor del contenedor
      /// \pre <code> !empty() </code>
      void list::pop_front();


(***) Es un error omitir los parámetros al hacer la especificación
NO==> /// Agrega valores a la lista
      void push_back( list& L, T v );

(***) Es obligatorio incluir los parámetros en la especificación
SI==> /// Agrega una copia del valor \c "v" al final de \c "L"
      void push_back( list& L, const T& v );



(***) Es un error omitir el prototipo al hacer la especificación
(***) Es obligatorio incluir el prototipo en la especificación
NO==> /// Agrega una copia del valor \c "v" al final de \c "L"

SI==> /// Agrega una copia del valor \c "v" al final de \c "L"
      void push_back( list& L, const T& v );



(***) Es un error confundir métodos y funciones
NO==> /// \remark push_back() es una función...
      void list::push_back( const T& v );
SI==> /// \remark push_back() es un método...
      void list::push_back( const T& v );

NO==> /// \remark push_back() es un método...
      void push_back( list& L, const T& v );
SI==> /// \remark push_back() es una función...
      void push_back( list& L, const T& v );


(***) Las funciones no son métodos porque no tienen un parámetro "this"
(***) Los métodos no son funciones porque si tienen su parámetro "this"


(***) En las especificaciones sí es conveniente incluir un ejemplo de uso

/** Calcula el Máximo Común Divisor de los números \c "x" y \c "y".
    - <code> mcd(x,y) >= 1 </code> siempre.
    - MCD <==> GCD: <em> Greatest Common Divisor </em>.

    \pre
    <code> (y != 0) </code>

    \remark
    Se usa el algoritmo de Euclides para hacer el cálculo.

    \par Ejemplo:
    \code
    2*3*5 == mcd( 2*2*2*2 * 3*3 * 5*5, 2*3*5 )
       30 == mcd( 3600, 30 )
    \endcode
*/
long mcd(long x, long y);