Se documenta con doxygen lo que faltaba.

diff --git a/emufs/external_sort/mergefile.h b/emufs/external_sort/mergefile.h
index bab305bd756481298f19c05033e808f45785097b..6cbf74802114c7a2d062ed297d27bb6263bc0582 100644 (file)
--- a/emufs/external_sort/mergefile.h
+++ b/emufs/external_sort/mergefile.h
@@ -40,26 +40,59 @@
 
 #include <stdio.h>
 
+/** Archivo temporal con un fragmento ordenado.
+ *  Es una especie de cola almacenada en un archivo temporal. El modo de
+ *  utilización es el siguiente: primero \ref mergefile_push "se lo llena" ,
+ *  luego \ref mergefile_switch_to_input "lo pasa a modo de lectura" y
+ *  finalmente se van \ref mergefile_pop "obteniendo los valores" en el mismo
+ *  órden en que se los insertó. A diferencia de una cola regular, primero se
+ *  insertan todos los valores y luego se los extrae.
+ */
 typedef struct
 {
-       FILE*  fp;
-       size_t reg_size;
-       void*  next;
+       FILE*  fp; /**< Puntero al archivo donde almacenar los datos. */
+       size_t reg_size; /**< Tamaño del registro a almacenar. */
+       void*  next; /**< Buffer con el próximo dato a obtener. */
 }
 MERGEFILE;
 
+/** Crea un nuevo archivo temporal para ordenamiento externo. */
 MERGEFILE* mergefile_new(size_t reg_size);
 
+/** Libera un archivo temporal para ordenamiento externo. */
 void mergefile_delete(MERGEFILE* mf);
 
+/** Pasa a modo lectura el archivo.
+ *  Antes de efectuar cualquier tipo de lectura (mergefile_pop() o
+ *  mergefile_peek()) hay que llamar a esta función.
+ *  \return 0 si hubo error.
+ */
 int mergefile_switch_to_input(MERGEFILE* mf);
 
+/** Inserta un nuevo dato en el archivo.
+ *  \return 0 si hubo error.
+ */
 int mergefile_push(MERGEFILE* mf, void* data);
 
+/** Obtiene el próximo dato en el archivo, sacándolo de éste.
+ *  \pre mergefile_switch_to_input() fue ejecutada.
+ *  \return 0 si hubo error, si no, un puntero al próximo dato que debe ser
+ *          liberado después de usado.
+ */
 void* mergefile_pop(MERGEFILE* mf);
 
+/** <em>Espía</em> el próximo dato en el archivo sin sacarlo.
+ *  \pre mergefile_switch_to_input() fue ejecutada.
+ *  \return 0 si hubo error, si no, un puntero al próximo dato que no debe ser
+ *          liberado hasta que se quite el dato del archivo con mergefile_pop()
+ *          definitivamente.
+ */
 void* mergefile_peek(MERGEFILE* mf);
 
+/** Verifica si quedan más datos para leer en el archivo.
+ *  \pre mergefile_switch_to_input() fue ejecutada.
+ *  \return 0 si no hay más.
+ */
 int mergefile_has_more(MERGEFILE* mf);
 
 #endif /* _EXTSORT_MERGEFILE_H_ */

diff --git a/emufs/external_sort/mergepool.h b/emufs/external_sort/mergepool.h
index 43503f0fc2c23f5ec801cc84358dbe1fb282cee8..d571dd31e3922cb2cd7a8c8b7751051ffde4489a 100644 (file)
--- a/emufs/external_sort/mergepool.h
+++ b/emufs/external_sort/mergepool.h
@@ -42,24 +42,49 @@
 #include "mergefile.h"
 #include <stdlib.h>
 
+/** <em>Pool</em> de archivos temporales para hacer un ordenamiento externo.
+ *  La forma de uso general es, de forma similar al MERGEFILE,
+ *  \ref mergepool_add_file "crear un archivo temporal" ,
+ *  \ref mergepool_append_data "agregarle datos" (repitiendo el proceso varias
+ *  veces creando un lote de archivos temporales) y finalmente ir
+ *  \ref mergepool_pop_min "obteniendo el mínimo valor del lote" hasta que no
+ *  haya más datos.
+ *  \warning Una vez obtenido un dato con mergepool_pop_min() no se pueden
+ *           agregar más archivos temporales ni datos al lote.
+ */
 typedef struct
 {
-       MERGEFILE**            pool;
-       size_t                 size;
-       size_t                 reg_size;
-       CMP_FUNC               cmp;
-       enum { INPUT, OUTPUT } mode;
+       MERGEFILE**            pool; /**< Arreglo de archivos temporales. */
+       size_t                 size; /**< Cantidad de archivos que tiene el lote. */
+       size_t                 reg_size; /**< Tamaño del tipo de dato que guarda. */
+       CMP_FUNC               cmp; /**< Función de comparación. */
+       enum { INPUT, OUTPUT } mode; /**< Modo. */
 }
 MERGEPOOL;
 
+/** Crea un nuevo lote de archivos temporales para ordenamiento externo. */
 MERGEPOOL* mergepool_new(size_t reg_size, CMP_FUNC cmp);
 
+/** Libera un lote de archivos temporales para ordenamiento externo. */
 void mergepool_delete(MERGEPOOL* mp);
 
+/** Agrega un nuevo archivo temporal al lote.
+ *  \return puntero al nuevo archivo temporal o 0 si hubo error.
+ */
 MERGEFILE* mergepool_add_file(MERGEPOOL* mp);
 
+/** Agrega un nuevo dato al lote que se almacena en el último archivo creado.
+ *  \pre mergepool_add_file() fue ejecutada (es decir, hay al menos un archivo
+ *       temporal en el lote.
+ *  \return 0 si hubo error.
+ */
 int mergepool_append_data(MERGEPOOL* mp, void* data);
 
+/** Obtiene el mínimo dato en el lote, sácandolo de éste.
+ *  \post No se pueden ingresar más archivos o datos al lote.
+ *  \return 0 si hubo error, si no, un puntero al mínimo dato del lote que debe
+ *          ser liberado después de usado.
+ */
 void* mergepool_pop_min(MERGEPOOL* mp);
 
 #endif /* _EXTSORT_MERGEPOOL_H_ */