logger: more cleaning

logger/logger_header.c

@@ -96,8 +96,8 @@ void header_change_offset_direction(struct header *h, int new_value) {
 /**
  * @brief read the logger header
  *
- * @param h out: header
- * @param map file mapping
+ * @param h out: The #header.
+ * @param dump The #logger_dump.
  */
 void header_read(struct header *h, struct logger_dump *dump) {
   size_t offset = 0;
@@ -110,7 +110,6 @@ void header_read(struct header *h, struct logger_dump *dump) {
   offset = io_read_data(map, LOGGER_VERSION_SIZE, &h->version, offset);
 
   /* read offset direction */
-  h->offset_direction = -1;
   offset = io_read_data(map, LOGGER_NUMBER_SIZE, &h->offset_direction, offset);
 
   if (!header_is_forward(h) && !header_is_backward(h) &&
@@ -118,11 +117,9 @@ void header_read(struct header *h, struct logger_dump *dump) {
     error("Wrong offset value in the header (%i)", h->offset_direction);
 
   /* read offset to first data */
-  h->offset_first = 0;
   offset = io_read_data(map, LOGGER_OFFSET_SIZE, &h->offset_first, offset);
 
   /* read name size */
-  h->name_length = 0;
   offset = io_read_data(map, LOGGER_NUMBER_SIZE, &h->name_length, offset);
 
   /* check if value defined in this file is large enough */
@@ -131,7 +128,6 @@ void header_read(struct header *h, struct logger_dump *dump) {
   }
 
   /* read number of masks */
-  h->number_mask = 0;
   offset = io_read_data(map, LOGGER_NUMBER_SIZE, &h->number_mask, offset);
 
   /* allocate memory */
@@ -142,17 +138,16 @@ void header_read(struct header *h, struct logger_dump *dump) {
     /* read mask name */
     offset = io_read_data(map, h->name_length, h->masks[i].name, offset);
 
-    /* get mask value */
+    /* set mask value */
     h->masks[i].mask = 1 << i;
 
     /* read mask data size */
-    h->masks[i].size = 0;
     offset = io_read_data(map, LOGGER_NUMBER_SIZE, &h->masks[i].size, offset);
   }
 
   if (offset != h->offset_first) {
     header_print(h);
-    error("Wrong header size (in header %li, current %li)", h->offset_first,
+    error("Wrong header size (in header %zi, current %zi)", h->offset_first,
           offset);
   }
 };

logger/logger_header.h

@@ -48,13 +48,13 @@ struct logger_dump;
 /**
  * @brief This structure contains everything from the file header.
  *
- * This structure is initialized by @header_read and need to be freed
- * with @header_free.
+ * This structure is initialized by #header_read and need to be freed
+ * with #header_free.
  *
  * The information contained by the header can be easily access with
- * the functions @header_get_mask_size and @header_get_field_index.
+ * the functions #header_get_mask_size and #header_get_field_index.
  *
- * The only function that modify the file is @header_change_offset_direction.
+ * The only function that modify the file is #header_change_offset_direction.
  */
 struct header {
   /* Logger version. */
@@ -73,7 +73,7 @@ struct header {
   struct mask_data *masks;
 
   /* Direction of the offset in the chunks. */
-  int offset_direction;
+  enum logger_offset_direction offset_direction;
 
   /* The corresponding dump */
   struct logger_dump *dump;

logger/logger_io.c

@@ -42,7 +42,7 @@ size_t io_get_file_size(int fd) {
 /**
  * @brief Map a file.
  *
- * @io_munmap_file should be called to unmap the file.
+ * #io_munmap_file should be called to unmap the file.
  *
  * @param filename file to read.
  * @param file_size (out) size of the file.

logger/logger_particle.c

@@ -67,7 +67,7 @@ void logger_particle_init(struct logger_particle *part) {
  * @brief Read a single field for a particle.
  *
  * @param part The #logger_particle to update.
- * @param data Pointer to the data to read.
+ * @param map The mapped data.
  * @param offset position to read.
  * @param field field to read.
  * @param size number of bits to read.

logger/logger_particle.h

@@ -39,11 +39,11 @@ struct logger_reader;
  * As we need only a single particle, no need to keep
  * it small.
  *
- * The particle is initialized with @logger_particle_init
- * and can be updated with a chunk through @logger_particle_read.
+ * The particle is initialized with #logger_particle_init
+ * and can be updated with a chunk through #logger_particle_read.
  *
- * In @logger_particle_read, we use @logger_particle_read_field on
- * each field and @logger_particle_interpolate if a linear
+ * In #logger_particle_read, we use #logger_particle_read_field on
+ * each field and #logger_particle_interpolate if a linear
  * interpolation is required.
  */
 struct logger_particle {

logger/logger_python_wrapper.c

@@ -33,10 +33,11 @@
 /**
  * @brief load data from the offset without any interpolation
  *
- * @param offset PyArrayObject list of offset for each particle
- * @param filename string filename of the dump file
- * @param verbose Verbose level
- * @return dictionnary containing the data read
+ * <b>offset</b> PyArrayObject list of offset for each particle
+ * <b>filename</b> string filename of the dump file
+ * <b>verbose</b> Verbose level
+ *
+ * <b>returns</b> dictionnary containing the data read
  */
 static PyObject *loadFromIndex(__attribute__((unused)) PyObject *self,
                                PyObject *args) {
@@ -229,8 +230,8 @@ static PyObject *loadFromIndex(__attribute__((unused)) PyObject *self,
 /**
  * @brief Reverse offset in dump file
  *
- * @param filename string filename of the dump file
- * @param verbose Verbose level
+ * <b>filename</b> string filename of the dump file
+ * <b>verbose</b> Verbose level
  */
 static PyObject *pyReverseOffset(__attribute__((unused)) PyObject *self,
                                  PyObject *args) {

logger/logger_reader.h

@@ -17,8 +17,27 @@
  *
  ******************************************************************************/
 /**
- * @brief This file contains the C function shown to the external user.
+ * @file logger_reader.h
+ * @brief This file contains the C functions shown to the external user.
+ *
+ * Here is a quick summary of our different elements:
+ *
+ * The logger is a time adaptive way to write snapshots.
+ * It consists of a set of files: the log file, the parameter file and the index files.
+ *
+ * The <b>parameter file</b> contains all the information related to the code (e.g. boxsize).
+ *
+ * The <b>index files</b> are not mandatory files that indicates the position of the particles in
+ * the log file at a given time step. They are useful to speedup the reading.
+ *
+ * The <b>log file</b> consists in a large file where the particles are logged one after the other.
+ * It contains a <b>log file header</b> at the beginning of the file and a large collection of <b>records</b>.
+ *
+ * The records are logged one after the other and each contains a <b>record header</b> and then a list of <b>named entries</b>.
+ * In the record header, a <b>mask</b> is provided that corresponds to the type of named entries present in this record.
+ * It also contains the <b>offset</b> to the previous or next record for this particle.
  */
+
 #ifndef __LOGGER_LOGGER_READER_H__
 #define __LOGGER_LOGGER_READER_H__
 

logger/logger_time.c

@@ -89,7 +89,6 @@ size_t time_first_timestamp(const struct header *h) {
  * @brief Initialize an empty time array.
  *
  * @param t #time_array to initialize.
- * @param dump The #logger_dump.
  */
 void time_array_init_to_zero(struct time_array *t) {
   t->next = NULL;
@@ -221,7 +220,7 @@ void time_array_print(const struct time_array *t) {
   for(size_t i = 1; i < n; i++) {
     /* The last time_array does not have a next */
     if (!t->next)
-      error("Next pointer not initialized %li", i);
+      error("Next pointer not initialized %zi", i);
 
     t = t->next;
     if (i < threshold || i > up_threshold)

logger/logger_time.h

@@ -34,15 +34,15 @@ struct logger_reader;
  * this structure is required. It contains all the time step
  * with their timestamp and position in the file.
  *
- * This structure is initialized with @time_array_init and
- * freed with @time_array_free.
+ * This structure is initialized with #time_array_init and
+ * freed with #time_array_free.
  *
  * The time step of an offset can be obtained with
- * @time_array_get_integertime, @time_array_get_time and
- * @time_array_get_time_array.
+ * #time_array_get_integertime, #time_array_get_time and
+ * #time_array_get_time_array.
  *
  * The size of the time array can be accessed with
- * @time_array_count.
+ * #time_array_count.
  */
 struct time_array {
   /* Pointer to next element */

logger/logger_tools.c

@@ -110,7 +110,7 @@ int _tools_get_next_chunk_backward(const struct header *h, void *map,
  * From current chunk, switch side of the offset of the previous one.
  * @param h #header structure of the file.
  * @param map file mapping.
- * @param position of the record.
+ * @param offset position of the record.
  *
  * @return position after the record.
  */