Se documenta con doxygen lo que faltaba.

[z.facultad/75.06/emufs.git] / emufs / external_sort / mergefile.h

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_ */