logger: move docstring from .h to .c

logger/header.c

@@ -7,6 +7,9 @@
 #include <stdio.h>
 #include <stdlib.h>
 
+/**
+ * @brief print a header struct
+ */
 void header_print(const struct header *h) {
 #ifdef SWIFT_DEBUG_CHECKS
   printf("Debug checks enabled\n");
@@ -32,6 +35,9 @@ void header_print(const struct header *h) {
 
 };
 
+/**
+ * @brief free allocated memory
+ */
 void header_free(struct header *h) {
   for (size_t i = 0; i < h->nber_mask; i++) {
     free(h->masks_name[i]);
@@ -41,6 +47,12 @@ void header_free(struct header *h) {
   free(h->masks_size);
 };
 
+/**
+ * @brief check if field is present in header
+ *
+ * @param field name of the requested field
+ * @param ind (return value) indice of the requested field
+ */
 int header_is_present_and_get_index(const struct header *h, const char *field,
                                     size_t *ind) {
   for (size_t i = 0; i < h->nber_mask; i++) {
@@ -55,10 +67,23 @@ int header_is_present_and_get_index(const struct header *h, const char *field,
   return 0;
 };
 
+/**
+ * @brief check if field is present in header
+ *
+ * @param field name of the requested field
+ */
 int header_is_present(const struct header *h, const char *field) {
   return header_is_present_and_get_index(h, field, NULL);
 };
 
+/**
+ * @brief Inverse the offset direction
+ *
+ * @param h #header file structure
+ * @param map file mapping
+ *
+ * @return error code
+ */
 int header_change_offset_direction(struct header *h, void *map) {
   h->forward_offset = !h->forward_offset;
   size_t offset = LOGGER_VERSION_SIZE;
@@ -67,6 +92,12 @@ int header_change_offset_direction(struct header *h, void *map) {
                        &offset);
 }
 
+/**
+ * @brief read the logger header
+ *
+ * @param h out: header
+ * @param map file mapping
+ */
 int header_read(struct header *h, void *map) {
   size_t offset = 0;
 
@@ -127,6 +158,14 @@ int header_read(struct header *h, void *map) {
   return 0;
 };
 
+/**
+ * @brief count number of bits in a given mask
+ *
+ * @param h #header file structure
+ * @param mask mask to compute
+ *
+ * @return number of bits in mask
+ */
 size_t header_get_mask_size(const struct header *h, const size_t mask) {
   size_t count = 0;
   for (size_t i = 0; i < h->nber_mask; i++) {

logger/header.h

@@ -37,58 +37,13 @@ struct header {
   int forward_offset;
 };
 
-/**
- * @brief print a header struct
- */
 void header_print(const struct header *h);
-
-/**
- * @brief free allocated memory
- */
 void header_free(struct header *h);
-
-/**
- * @brief check if field is present in header
- *
- * @param field name of the requested field
- * @param ind (return value) indice of the requested field
- */
 int header_is_present_and_get_index(const struct header *h, const char *field,
                                     size_t *ind);
-
-/**
- * @brief check if field is present in header
- *
- * @param field name of the requested field
- */
 int header_is_present(const struct header *h, const char *field);
-
-/**
- * @brief read the logger header
- *
- * @param h out: header
- * @param map file mapping
- */
 int header_read(struct header *h, void *map);
-
-/**
- * @brief count number of bits in a given mask
- *
- * @param h #header file structure
- * @param mask mask to compute
- *
- * @return number of bits in mask
- */
 size_t header_get_mask_size(const struct header *h, const size_t mask);
-
-/**
- * @brief Inverse the offset direction
- *
- * @param h #header file structure
- * @param map file mapping
- *
- * @return error code
- */
 int header_change_offset_direction(struct header *h, void *map);
 
 #endif  // __LOGGER_HEADER_H__

logger/io.c

@@ -7,6 +7,14 @@
 #include "header.h"
 #include "logger_tools.h"
 
+/**
+ * @brief get the size of a file
+ *
+ * @param fd file id
+ * @param size out: file size
+ *
+ * @return error code
+ */
 int io_get_file_size(int fd, size_t *size) {
   struct stat s;
   int status = fstat(fd, &s);
@@ -16,6 +24,15 @@ int io_get_file_size(int fd, size_t *size) {
   return 0;
 }
 
+/**
+ * @brief Open a file and map it
+ *
+ * @param filename file to read
+ * @param fd out: file id
+ * @param map out: file mapping
+ *
+ * @return error code
+ */
 int io_open_file(char *filename, int *fd, void **map) {
   /* open file */
   *fd = open(filename, O_RDWR);
@@ -34,6 +51,14 @@ int io_open_file(char *filename, int *fd, void **map) {
   return 0;
 }
 
+/**
+ * @brief Close a file and unmap it
+ *
+ * @param fd file id
+ * @param map file mapping
+ *
+ * @return error code
+ */
 int io_close_file(int *fd, void **map) {
   /* get file size */
   size_t size = 0;
@@ -48,6 +73,18 @@ int io_close_file(int *fd, void **map) {
   return 0;
 }
 
+/**
+ * @brief read a maks with its offset
+ *
+ * @param h #header file structure
+ * @param map file mapping
+ * @param offset In: position in the file, Out: shifted by the mask + offset
+ * size
+ * @param mask mask read
+ * @param diff_offset offset difference to previous/next corresponding chunk
+ *
+ * @return error code
+ */
 int io_read_mask(const struct header *h, void *map, size_t *offset,
                  size_t *mask, size_t *diff_offset) {
   /* read mask */
@@ -67,6 +104,16 @@ int io_read_mask(const struct header *h, void *map, size_t *offset,
   return 0;
 }
 
+/**
+ * @brief read a single value in a file
+ *
+ * @param map file mapping
+ * @param size size of the chunk to read
+ * @param p pointer where to store the data
+ * @param offset In: position to read, Out: shifted by size
+ *
+ * @return error code
+ */
 int io_read_data(void *map, const size_t size, void *p, size_t *offset) {
   memcpy(p, map + *offset, size);
   *offset += size;
@@ -74,6 +121,16 @@ int io_read_data(void *map, const size_t size, void *p, size_t *offset) {
   return 0;
 };
 
+/**
+ * @brief write a single value in a file
+ *
+ * @param map file mapping
+ * @param size size of the chunk to write
+ * @param p pointer to the data
+ * @param offset In: position to write, Out: shifted by size
+ *
+ * @return error code
+ */
 int io_write_data(void *map, const size_t size, const void *p, size_t *offset) {
   memcpy(map + *offset, p, size);
   *offset += size;

logger/io.h

@@ -7,73 +7,11 @@
 #include <stdio.h>
 #include <stdlib.h>
 
-/**
- * @brief get the size of a file
- *
- * @param fd file id
- * @param size out: file size
- *
- * @return error code
- */
 int io_get_file_size(int fd, size_t *size);
-
-/**
- * @brief Open a file and map it
- *
- * @param filename file to read
- * @param fd out: file id
- * @param map out: file mapping
- *
- * @return error code
- */
 int io_open_file(char *filename, int *fd, void **map);
-
-/**
- * @brief Close a file and unmap it
- *
- * @param fd file id
- * @param map file mapping
- *
- * @return error code
- */
 int io_close_file(int *fd, void **map);
-
-/**
- * @brief read a single value in a file
- *
- * @param map file mapping
- * @param size size of the chunk to read
- * @param p pointer where to store the data
- * @param offset In: position to read, Out: shifted by size
- *
- * @return error code
- */
 int io_read_data(void *map, const size_t size, void *p, size_t *offset);
-
-/**
- * @brief write a single value in a file
- *
- * @param map file mapping
- * @param size size of the chunk to write
- * @param p pointer to the data
- * @param offset In: position to write, Out: shifted by size
- *
- * @return error code
- */
 int io_write_data(void *map, const size_t size, const void *p, size_t *offset);
-
-/**
- * @brief read a maks with its offset
- *
- * @param h #header file structure
- * @param map file mapping
- * @param offset In: position in the file, Out: shifted by the mask + offset
- * size
- * @param mask mask read
- * @param diff_offset offset difference to previous/next corresponding chunk
- *
- * @return error code
- */
 int io_read_mask(const struct header *h, void *map, size_t *offset,
                  size_t *mask, size_t *diff_offset);
 

logger/logger_tools.c

@@ -6,6 +6,16 @@
 
 #include <stdio.h>
 
+/**
+ * @brief get the offset of the next corresponding chunk
+ *
+ * @param h #header structure of the file
+ * @param map file mapping
+ * @param offset In: initial offset, Out: offset of the next chunk
+ * @param fd file id
+ *
+ * @return error code, -1 if no next chunk
+ */
 int tools_get_next_chunk(const struct header *h, void *map, size_t *offset,
                          int fd) {
   if (h->forward_offset)
@@ -14,6 +24,15 @@ int tools_get_next_chunk(const struct header *h, void *map, size_t *offset,
     return _tools_get_next_chunk_backward(h, map, offset, fd);
 }
 
+/**
+ * @brief internal function of #tools_get_next_chunk. Should not be used outside
+ *
+ * @param h #header structure of the file
+ * @param map file mapping
+ * @param offset In: initial offset, Out: offset of the next chunk
+ *
+ * @return error code, -1 if no next chunk
+ */
 int _tools_get_next_chunk_forward(const struct header *h, void *map,
                                   size_t *offset) {
   size_t diff_offset = 0;
@@ -29,6 +48,17 @@ int _tools_get_next_chunk_forward(const struct header *h, void *map,
   return 0;
 }
 
+/**
+ * @brief internal function of #tools_get_next_chunk. Should not be used (very
+ * slow)
+ *
+ * @param h #header structure of the file
+ * @param map file mapping
+ * @param offset In: initial offset, Out: offset of the next chunk
+ * @param fd file id
+ *
+ * @return error code, -1 if no next chunk
+ */
 int _tools_get_next_chunk_backward(const struct header *h, void *map,
                                    size_t *offset, int fd) {
 #ifndef SWIFT_DEBUG_CHECKS
@@ -60,6 +90,16 @@ int _tools_get_next_chunk_backward(const struct header *h, void *map,
   return -1;
 }
 
+/**
+ * @brief switch side offset
+ *
+ * From current chunk, switch side of the offset of the previous one.
+ * @param h #header structure of the file
+ * @param map file mapping
+ * @param offset In: initial offset, Out: offset of next chunk
+ *
+ * @return error code
+ */
 int tools_reverse_offset(const struct header *h, void *map, size_t *offset) {
   size_t mask = 0;
   size_t prev_offset = 0;
@@ -104,6 +144,17 @@ int tools_reverse_offset(const struct header *h, void *map, size_t *offset) {
   return 0;
 }
 
+/**
+ * @brief debugging function checking the offset of a chunk
+ *
+ * Compare the mask with the one pointed by the header.
+ * if the chunk is a particle, check the id too.
+ * @param h #header structure of the file
+ * @param map file mapping
+ * @param offset In: chunk offset, Out: offset after the chunk
+ *
+ * @return error code
+ */
 int tools_check_offset(const struct header *h, void *map, size_t *offset) {
 #ifndef SWIFT_DEBUG_CHECKS
   error(ENOTSUP, "Should not check in non debug mode");

logger/logger_tools.h

@@ -60,68 +60,13 @@ struct header;
            ##__VA_ARGS__);                                          \
   })
 
-/**
- * @brief get the offset of the next corresponding chunk
- *
- * @param h #header structure of the file
- * @param map file mapping
- * @param offset In: initial offset, Out: offset of the next chunk
- * @param fd file id
- *
- * @return error code, -1 if no next chunk
- */
 int tools_get_next_chunk(const struct header *h, void *map, size_t *offset,
                          int fd);
-
-/**
- * @brief internal function of #tools_get_next_chunk. Should not be used (very
- * slow)
- *
- * @param h #header structure of the file
- * @param map file mapping
- * @param offset In: initial offset, Out: offset of the next chunk
- * @param fd file id
- *
- * @return error code, -1 if no next chunk
- */
 int _tools_get_next_chunk_backward(const struct header *h, void *map,
                                    size_t *offset, int fd);
-
-/**
- * @brief internal function of #tools_get_next_chunk. Should not be used outside
- *
- * @param h #header structure of the file
- * @param map file mapping
- * @param offset In: initial offset, Out: offset of the next chunk
- *
- * @return error code, -1 if no next chunk
- */
 int _tools_get_next_chunk_forward(const struct header *h, void *map,
                                   size_t *offset);
-
-/**
- * @brief switch side offset
- *
- * From current chunk, switch side of the offset of the previous one.
- * @param h #header structure of the file
- * @param map file mapping
- * @param offset In: initial offset, Out: offset of next chunk
- *
- * @return error code
- */
 int tools_reverse_offset(const struct header *h, void *map, size_t *offset);
-
-/**
- * @brief debugging function checking the offset of a chunk
- *
- * Compare the mask with the one pointed by the header.
- * if the chunk is a particle, check the id too.
- * @param h #header structure of the file
- * @param map file mapping
- * @param offset In: chunk offset, Out: offset after the chunk
- *
- * @return error code
- */
 int tools_check_offset(const struct header *h, void *map, size_t *offset);
 
 #endif  //__LOGGER_TOOLS_H__

logger/particle.c

@@ -8,6 +8,11 @@
 #include <stdlib.h>
 #include <stdint.h>
 
+/**
+ * @brief print a particle
+ *
+ * @param p #particle particle to print
+ */
 void particle_print(const struct particle *p) {
   printf("ID:            %lu\n", p->id);
   printf("Mass:          %g\n", p->mass);
@@ -20,11 +25,23 @@ void particle_print(const struct particle *p) {
   printf("Density:       %g\n", p->density);
 }
 
+/**
+ * @brief Check if dump data type are compatible with the particle type
+ *
+ * @param h #header structure of the file
+ *
+ * @return error code
+ */
 int particle_check_data_type(__attribute__((unused)) const struct header *h) {
   printf("TODO check_data_type\n");
   return 1;
 }
 
+/**
+ * @brief initialize a particle
+ *
+ * @param part #particle particle to initialize
+ */
 void particle_init(struct particle *part) {
   for (size_t k = 0; k < DIM; k++) {
     part->pos[k] = 0;
@@ -39,6 +56,18 @@ void particle_init(struct particle *part) {
   part->id = SIZE_MAX;
 }
 
+/**
+ * @brief read a single field for a particle
+ *
+ * @param part @particle particle to update
+ * @param map file mapping
+ * @param offset In: read position, Out: input shifted by the required amount of
+ * data
+ * @param field field to read
+ * @param size number of bits to read
+ *
+ * @return error code
+ */
 int particle_read_field(struct particle *part, void *map, size_t *offset,
                         const char *field, const size_t size) {
   void *p = NULL;
@@ -77,6 +106,19 @@ int particle_read_field(struct particle *part, void *map, size_t *offset,
   return error_code;
 }
 
+/**
+ * @brief read a particle in the dump file
+ *
+ * @param part #particle particle to update
+ * @param h #header structure of the file
+ * @param map file mapping
+ * @param offset offset of the chunk to read (update it to the end of the chunk)
+ * @param time time to interpolate (if #reader_type is an interpolating one)
+ * @param reader #reader_type
+ * @param times #time_array times in the dump
+ *
+ * @return error code
+ */
 int particle_read(struct particle *part, const struct header *h, void *map,
                   size_t *offset, const double time, const int reader,
                   struct time_array *times) {
@@ -129,6 +171,16 @@ int particle_read(struct particle *part, const struct header *h, void *map,
   return 0;
 }
 
+/**
+ * @brief interpolate two particles at a given time
+ *
+ * @param part_curr #particle In: current particle (before time), Out:
+ * interpolated particle
+ * @param part_next #particle next particle (after time)
+ * @param time interpolation time
+ *
+ * @return error code
+ */
 int particle_interpolate(struct particle *part_curr,
                          const struct particle *part_next,
                          const double time) {

logger/particle.h

@@ -44,71 +44,18 @@ enum reader_type {
   reader_lin,
 };
 
-/**
- * @brief print a particle
- *
- * @param p #particle particle to print
- */
 void particle_print(const struct particle *p);
 
-/**
- * @brief read a particle in the dump file
- *
- * @param part #particle particle to update
- * @param h #header structure of the file
- * @param map file mapping
- * @param offset offset of the chunk to read (update it to the end of the chunk)
- * @param time time to interpolate (if #reader_type is an interpolating one)
- * @param reader #reader_type
- * @param times #time_array times in the dump
- *
- * @return error code
- */
 int particle_read(struct particle *part, const struct header *h, void *map,
                   size_t *offset, const double time, const int reader,
                   struct time_array *times);
 
-/**
- * @brief Check if dump data type are compatible with the particle type
- *
- * @param h #header structure of the file
- *
- * @return error code
- */
 int particle_check_data_type(const struct header *h);
-
-/**
- * @brief initialize a particle
- *
- * @param part #particle particle to initialize
- */
 void particle_init(struct particle *part);
 
-/**
- * @brief read a single field for a particle
- *
- * @param part @particle particle to update
- * @param map file mapping
- * @param offset In: read position, Out: input shifted by the required amount of
- * data
- * @param field field to read
- * @param size number of bits to read
- *
- * @return error code
- */
 int particle_read_field(struct particle *part, void *map, size_t *offset,
                         const char *field, const size_t size);
 
-/**
- * @brief interpolate two particles at a given time
- *
- * @param part_curr #particle In: current particle (before time), Out:
- * interpolated particle
- * @param part_next #particle next particle (after time)
- * @param time interpolation time
- *
- * @return error code
- */
 int particle_interpolate(struct particle *part_curr,
                          const struct particle *part_next,
                          const double time);

logger/timeline.c

 #include "timeline.h"
 #include "io.h"
 
+/**
+ * @brief convert an integer time to a real time
+ *
+ * @param ti integer time to convert
+ * @param timeBase time base of the integer time
+ *
+ * @return converted time
+ */
 double time_convert_to_double(const integertime_t ti, const double timeBase) {
   return ti * timeBase;  // should add timebegin
 }
 
+/**
+ * @brief convert an integer time to a real time
+ *
+ * @param ti integer time to convert
+ * @param timeBase time base of the integer time
+ *
+ * @return converted time
+ */
 integertime_t time_convert_to_integer(const double ti,
                                       const double timeBase) {
   return ti / timeBase;  // should add timebegin
 }
 
+/**
+ * @brief read a time stamp
+ *
+ * @param timestamp timestamp read
+ * @param time time read
+ * @param h #header file structure
+ * @param map file mapping
+ * @param offset In: position in the file, Out: shifted by the timestamp
+ */
 int time_read(integertime_t *timestamp, double *time, const struct header *h, void *map,
               size_t *offset) {
   int error_code = 0;
@@ -41,6 +66,15 @@ int time_read(integertime_t *timestamp, double *time, const struct header *h, vo
   return error_code;
 }
 
+/**
+ * @brief get offset of first timestamp
+ *
+ * @param h file #header
+ * @param map file mapping
+ * @param offset out: offset of first timestamp
+ *
+ * @return error code
+ */
 int time_first_timestamp(const struct header *h, void *map, size_t *offset) {
   *offset = h->offset_first;
   int test;
@@ -61,6 +95,14 @@ int time_first_timestamp(const struct header *h, void *map, size_t *offset) {
   return 0;
 }
 
+/**
+ * @brief Initialize a time array
+ *
+ * @param t #time_array to initialize
+ * @param h #header file structure
+ * @param map file mapping
+ * @param fd file id
+ */
 int time_array_init(struct time_array *t, const struct header *h, void *map,
                     int fd) {
 
@@ -110,16 +152,40 @@ int time_array_init(struct time_array *t, const struct header *h, void *map,
   return 0;
 }
 
+/**
+ * @brief access the time of a given chunk (by its offset)
+ *
+ * @param t #time_array to access
+ * @param offset offset of the chunk
+ *
+ * @return integer time of the chunk
+ */
 integertime_t time_array_get_integertime(struct time_array *t, const size_t offset) {
   const struct time_array *tmp = time_array_get_time_array(t, offset);
   return tmp->timestamp;
 }
 
+/**
+ * @brief access the time of a given chunk (by its offset)
+ *
+ * @param t #time_array to access
+ * @param offset offset of the chunk
+ *
+ * @return time of the chunk
+ */
 double time_array_get_time(struct time_array *t, const size_t offset) {
   const struct time_array *tmp = time_array_get_time_array(t, offset);
   return tmp->time;
 }
 
+/**
+ * @brief access the #time_array of a given chunk (by its offset)
+ *
+ * @param t #time_array to access
+ * @param offset offset of the chunk
+ *
+ * @return pointer to the requested #time_array
+ */
 struct time_array *time_array_get_time_array(struct time_array *t,
                                              const size_t offset) {
 
@@ -138,6 +204,11 @@ struct time_array *time_array_get_time_array(struct time_array *t,
   return tmp;
 }
 
+/**
+ * @brief free memory of a #time_array
+ *
+ * @param t #time_array to free
+ */
 void time_array_free(struct time_array *t) {
   struct time_array *tmp;
   while (t->next) {
@@ -147,6 +218,11 @@ void time_array_free(struct time_array *t) {
   }
 }
 
+/**
+ * @brief print a #time_array
+ *
+ * @param t #time_array to print
+ */
 void time_array_print(const struct time_array *t) {
   size_t threshold = 4;
 
@@ -167,6 +243,11 @@ void time_array_print(const struct time_array *t) {
   printf("]\n");
 }
 
+/**
+ * @brief print a #time_array (offset)
+ *
+ * @param t #time_array to print
+ */
 void time_array_print_offset(const struct time_array *t) {
   size_t threshold = 4;
 
@@ -187,6 +268,13 @@ void time_array_print_offset(const struct time_array *t) {
   printf("]\n");
 }
 
+/**
+ * @brief count number of element in #time_array
+ *
+ * @param t #time_array to count
+ *
+ * @return number of element
+ */
 size_t time_array_count(const struct time_array *t) {
   size_t count = 1;
   while (t->next) {

logger/timeline.h

@@ -15,119 +15,20 @@ struct time_array {
   size_t offset;
 };
 
-/**
- * @brief convert an integer time to a real time
- *
- * @param ti integer time to convert
- * @param timeBase time base of the integer time
- *
- * @return converted time
- */
 double time_convert_to_double(const integertime_t ti, const double timeBase);
-
-/**
- * @brief convert an integer time to a real time
- *
- * @param ti integer time to convert
- * @param timeBase time base of the integer time
- *
- * @return converted time
- */
 integertime_t time_convert_to_integer(const double ti, const double timeBase);
-
-/**
- * @brief read a time stamp
- *
- * @param timestamp timestamp read
- * @param time time read
- * @param h #header file structure
- * @param map file mapping
- * @param offset In: position in the file, Out: shifted by the timestamp
- */
 int time_read(integertime_t *timestamp, double *time, const struct header *h, void *map,
               size_t *offset);
-
-/**
- * @brief Initialize a time array
- *
- * @param t #time_array to initialize
- * @param h #header file structure
- * @param map file mapping
- * @param fd file id
- */
 int time_array_init(struct time_array *t, const struct header *h, void *map,
                     int fd);
-
-/**
- * @brief access the time of a given chunk (by its offset)
- *
- * @param t #time_array to access
- * @param offset offset of the chunk
- *
- * @return integer time of the chunk
- */
 integertime_t time_array_get_integertime(struct time_array *t, const size_t offset);
-
-/**
- * @brief access the time of a given chunk (by its offset)
- *
- * @param t #time_array to access
- * @param offset offset of the chunk
- *
- * @return time of the chunk
- */
 double time_array_get_time(struct time_array *t, const size_t offset);
-
-/**
- * @brief access the #time_array of a given chunk (by its offset)
- *
- * @param t #time_array to access
- * @param offset offset of the chunk
- *
- * @return pointer to the requested #time_array
- */
 struct time_array *time_array_get_time_array(struct time_array *t,
                                              const size_t offset);
-
-/**
- * @brief free memory of a #time_array
- *
- * @param t #time_array to free
- */
 void time_array_free(struct time_array *t);
-
-/**
- * @brief print a #time_array
- *
- * @param t #time_array to print
- */
 void time_array_print(const struct time_array *t);
-
-/**
- * @brief print a #time_array (offset)
- *
- * @param t #time_array to print
- */
 void time_array_print_offset(const struct time_array *t);
-
-/**
- * @brief count number of element in #time_array
- *
- * @param t #time_array to count
- *
- * @return number of element
- */
 size_t time_array_count(const struct time_array *t);
-
-/**
- * @brief get offset of first timestamp
- *
- * @param h file #header
- * @param map file mapping
- * @param offset out: offset of first timestamp
- *
- * @return error code
- */
 int time_first_timestamp(const struct header *h, void *map, size_t *offset);
 
 #endif  // __TIMELINE_H__