Se mejora la documentación.

[z.facultad/75.42/calculadora.git] / dllist.h

diff --git a/dllist.h b/dllist.h
index dc2621440e848eda06f5c52d3d99e7f45ddde27a..432e742a804dd573a5b1d63f801e6c7f0c470de5 100644 (file)
--- a/dllist.h
+++ b/dllist.h
@@ -37,27 +37,28 @@ struct DLNodeStruct {
     DLNode* next;
 };
 
     DLNode* next;
 };
 

-/** Lista doblemente enlazada. */
-typedef struct DLListStruct DLList;
-
-/** Lista doblemente enlazada. */
-struct DLListStruct {
+/**
+ * Lista doblemente enlazada.
+ *
+ * \see DLList_init(), DLList_empty(), DLList_begin(), DLList_end(),
+ *      DLList_have_more(), DLList_current(), DLList_next(), DLList_prev(),
+ *      DLList_unshift(), DLList_push(), DLList_shift(), DLList_pop()
+ */
+typedef struct {

     /** Puntero al primer nodo. */
     DLNode* first;
     /** Puntero al nodo actual. */
     DLNode* current;
     /** Puntero al último nodo. */
     DLNode* last;
     /** Puntero al primer nodo. */
     DLNode* first;
     /** Puntero al nodo actual. */
     DLNode* current;
     /** Puntero al último nodo. */
     DLNode* last;

-};
+} DLList;

 
 /**
  * Inicializa la DLList.
 
 /**
  * Inicializa la DLList.

- * Se crea (alocando memoria) e inicializa la DLList.

  *
  * \param   list DLList a inicializar.
  *
  *
  * \param   list DLList a inicializar.
  *

- * \return  TRUE si se inicializó bien, FALSE si hay error.
- * \post    Se crea una nueva DLList, reservando una porción de memoria.
+ * \return  \ref TRUE si se inicializó bien, \ref FALSE si hay error.

  */
 bool DLList_init(DLList* list);
 
  */
 bool DLList_init(DLList* list);
 


@@ -66,33 +67,67 @@ bool DLList_init(DLList* list);
  *
  * \param   list DLList a verificar.
  *
  *
  * \param   list DLList a verificar.
  *

- * \return  TRUE si está vacía, FALSE si no.
+ * \return  \ref TRUE si está vacía, \ref FALSE si no.

  * \pre     La DLList debe estar \ref DLList_init "inicializada".
  */
 bool DLList_empty(DLList* list);
 
 /**
  * \pre     La DLList debe estar \ref DLList_init "inicializada".
  */
 bool DLList_empty(DLList* list);
 
 /**

- * Reinicia la DLList devolviendo el primer elemento.
- * Hace que el elemento actual de la DLList vuelva a ser el primero.
- * Siempre que se quiera recorrer la DLList debería usarse esta función
- * primero. Por ejemplo:
+ * Apunta al primer elemento de la DLList devolviendolo.
+ * Hace que el elemento actual de la DLList sea el primero y devuelve su valor.
+ * Si está vacía, devuelve NULL.
+ * Siempre que se quiera recorrer la DLList de izquierda a derecha debería
+ * usarse esta función primero. Por ejemplo:

  * \code
  * \code

- * DLList* list;
- * NodeType*   node;
+ * DLList* l;
+ * char*   data;

  * ...
  * ...

- * for (node = DLList_reset(list); node; node = DLList_next(list)) {
- *      printf("Uso el elemento actual aquí.\\n");
+ * for (data = DLList_begin(l); DLList_have_more(l); data = DLList_next(l)) {
+ *      printf("El elemento actual es '%s'.\\n", data);

  * }
  * \endcode
  *
  * }
  * \endcode
  *

- * \param   list DLList de la cual obtener el siguiente elemento.
+ * \param   list DLList de la cual obtener el primer elemento.

  *
  *

- * \return  Puntero al primer elemento o NULL si está vacía.
- * \see     DLList_current()
- * \see     DLList_next()
+ * \return  Primer elemento o NULL si está vacía.
+ * \see     DLList_have_more(), DLList_next(), DLList_end(), DLList_prev()

  * \pre     La DLList debe estar \ref DLList_init "inicializada".
  */
  * \pre     La DLList debe estar \ref DLList_init "inicializada".
  */

-void* DLList_reset(DLList* list);
+void* DLList_begin(DLList* list);
+
+/**
+ * Apunta al último elemento de la DLList devolviendolo.
+ * Hace que el elemento actual de la DLList sea el último y devuelve su valor.
+ * Si está vacía, devuelve NULL.
+ * Siempre que se quiera recorrer la DLList de derecha a izquierda debería
+ * usarse esta función primero. Por ejemplo:
+ * \code
+ * DLList* l;
+ * char*   data;
+ * ...
+ * for (data = DLList_end(l); DLList_have_more(l); data = DLList_prev(l)) {
+ *      printf("El elemento actual es '%s'.\\n", data);
+ * }
+ * \endcode
+ *
+ * \param   list DLList de la cual obtener el último elemento.
+ *
+ * \return  Último elemento o NULL si está vacía.
+ * \see     DLList_have_more(), DLList_prev(), DLList_begin(), DLList_next()
+ * \pre     La DLList debe estar \ref DLList_init "inicializada".
+ */
+void* DLList_end(DLList* list);
+
+/**
+ * Indica si se puede obtener otro elemento de la lista en una iteración.
+ *
+ * \param   list DLList a verificar.
+ *
+ * \return  \ref TRUE si se puede obtener otro elemento, \ref FALSE si no.
+ * \see     DLList_begin(), DLList_end(), DLList_prev(), DLList_next()
+ * \pre     La DLList debe estar \ref DLList_init "inicializada".
+ */
+bool DLList_have_more(DLList* list);

 
 /**
  * Obtiene el elemento actual de la DLList.
 
 /**
  * Obtiene el elemento actual de la DLList.


@@ -100,8 +135,7 @@ void* DLList_reset(DLList* list);
  * \param   list DLList de la cual obtener el elemento actual.
  *
  * \return  Elemento actual o NULL si se terminó de recorrer o está vacía.
  * \param   list DLList de la cual obtener el elemento actual.
  *
  * \return  Elemento actual o NULL si se terminó de recorrer o está vacía.

- * \see     DLList_reset()
- * \see     DLList_next()
+ * \see     DLList_prev(), DLList_next(), DLList_have_more()

  * \pre     La DLList debe estar \ref DLList_init "inicializada".
  */
 void* DLList_current(DLList* list);
  * \pre     La DLList debe estar \ref DLList_init "inicializada".
  */
 void* DLList_current(DLList* list);


@@ -111,24 +145,33 @@ void* DLList_current(DLList* list);
  *
  * \param   list DLList de la cual obtener el siguiente elemento.
  *
  *
  * \param   list DLList de la cual obtener el siguiente elemento.
  *

- * \return  Puntero al próximo elemento o NULL si es el último.
- * \see     DLList_reset()
- * \see     DLList_current()
+ * \return  Siguiente elemento o NULL si es el último.
+ * \see     DLList_begin(), DLList_have_more(), DLList_current(), DLList_prev()

  * \pre     La DLList debe estar \ref DLList_init "inicializada".
  */
 void* DLList_next(DLList* list);
 
  * \pre     La DLList debe estar \ref DLList_init "inicializada".
  */
 void* DLList_next(DLList* list);
 

+/**
+ * Obtiene el elemento anterior de la DLList.
+ *
+ * \param   list DLList de la cual obtener el elemento anterior.
+ *
+ * \return  Elemento anterior o NULL si es el primero.
+ * \see     DLList_begin(), DLList_have_more(), DLList_current(), DLList_next()
+ * \pre     La DLList debe estar \ref DLList_init "inicializada".
+ */
+void* DLList_prev(DLList* list);
+

 /**
  * Agrega un elemento al inicio de la DLList.
  *
  * \param   list DLList a la cual agregar el elemento.
  * \param   data Elemento a agregar.
  *
 /**
  * Agrega un elemento al inicio de la DLList.
  *
  * \param   list DLList a la cual agregar el elemento.
  * \param   data Elemento a agregar.
  *

- * \return  TRUE si se agregó, FALSE si no hay más memoria.
- * \see     DLList_push()
- * \see     DLList_pop()
- * \see     DLList_unshift()
+ * \return  \ref TRUE si se agregó, \ref FALSE si no hay más memoria.
+ * \see     DLList_push(), DLList_pop(), DLList_unshift()

  * \pre     La DLList debe estar \ref DLList_init "inicializada".
  * \pre     La DLList debe estar \ref DLList_init "inicializada".

+ * \post    El puntero interno de la DLList apunta al nuevo elemento.

  */
 bool DLList_unshift(DLList* list, void* data);
 
  */
 bool DLList_unshift(DLList* list, void* data);
 


@@ -138,11 +181,10 @@ bool DLList_unshift(DLList* list, void* data);
  * \param   list DLList a la cual agregar el elemento.
  * \param   data Elemento a agregar.
  *
  * \param   list DLList a la cual agregar el elemento.
  * \param   data Elemento a agregar.
  *

- * \return  TRUE si se agregó, FALSE si no hay más memoria.
- * \see     DLList_pop()
- * \see     DLList_shift()
- * \see     DLList_unshift()
+ * \return  \ref TRUE si se agregó, \ref FALSE si no hay más memoria.
+ * \see     DLList_pop(), DLList_shift(), DLList_unshift()

  * \pre     La DLList debe estar \ref DLList_init "inicializada".
  * \pre     La DLList debe estar \ref DLList_init "inicializada".

+ * \post    El puntero interno de la DLList apunta al nuevo elemento.

  */
 bool DLList_push(DLList* list, void* data);
 
  */
 bool DLList_push(DLList* list, void* data);
 


@@ -153,11 +195,10 @@ bool DLList_push(DLList* list, void* data);
  * \param   list DLList de la cual sacar el elemento.
  *
  * \return  Primer elemento de la DLList.
  * \param   list DLList de la cual sacar el elemento.
  *
  * \return  Primer elemento de la DLList.

- * \see     DLList_push()
- * \see     DLList_shift()
- * \see     DLList_unshift()
+ * \see     DLList_push(), DLList_shift(), DLList_unshift()

  * \pre     La DLList debe estar \ref DLList_init "inicializada" y no
  *          \ref DLList_empty "vacía".
  * \pre     La DLList debe estar \ref DLList_init "inicializada" y no
  *          \ref DLList_empty "vacía".

+ * \post    El puntero interno de la DLList apunta primer elemento.

  */
 void* DLList_shift(DLList* list);
 
  */
 void* DLList_shift(DLList* list);
 


@@ -168,11 +209,10 @@ void* DLList_shift(DLList* list);
  * \param   list DLList de la cual sacar el elemento.
  *
  * \return  último elemento de la DLList.
  * \param   list DLList de la cual sacar el elemento.
  *
  * \return  último elemento de la DLList.

- * \see     DLList_push()
- * \see     DLList_shift()
- * \see     DLList_unshift()
+ * \see     DLList_push(), DLList_shift(), DLList_unshift()

  * \pre     La DLList debe estar \ref DLList_init "inicializada" y no
  *          \ref DLList_empty "vacía".
  * \pre     La DLList debe estar \ref DLList_init "inicializada" y no
  *          \ref DLList_empty "vacía".

+ * \post    El puntero interno de la DLList apunta último elemento.

  */
 void* DLList_pop(DLList* list);
 
  */
 void* DLList_pop(DLList* list);