More comments in the source

elem.h

@@ -81,7 +81,7 @@ struct snapraid_file {
  */
 struct snapraid_disk {
 	char name[PATH_MAX]; /**< Name of the disk. */
-	char dir[PATH_MAX]; /**< Mount point of the disk. */
+	char dir[PATH_MAX]; /**< Mount point of the disk. It always terminates with /. */
 	block_off_t first_free_block; /**< First free searching block. */
 	tommy_list filelist; /**< List of all the files. */
 	tommy_hashdyn fileset; /**< Hashtable by sub of all the files. */
@@ -89,31 +89,53 @@ struct snapraid_disk {
 };
 
 /**
- * Get the relative position of a block inside the file.
+ * Gets the relative position of a block inside the file.
  */
 block_off_t block_file_pos(struct snapraid_block* block);
 
 /**
- * Get the size in bytes of the block.
- * If it's the last block of a file it could less than block_size.
+ * Gets the size in bytes of the block.
+ * If it's the last block of a file it could be less than block_size.
  */
 unsigned block_file_size(struct snapraid_block* block, unsigned block_size);
 
+/**
+ * Allocates a file.
+ */
 struct snapraid_file* file_alloc(unsigned block_size, const char* sub, data_off_t size, time_t mtime);
 
+/**
+ * Deallocate a file.
+ */
 void file_free(struct snapraid_file* file);
 
+/**
+ * Compares two files by path.
+ */
 int file_compare(const void* void_arg, const void* void_data);
 
+/**
+ * Computes the hash of a file path.
+ */
 static inline tommy_uint32_t file_hash(const char* sub)
 {
 	return tommy_hash_u32(0, sub, strlen(sub));
 }
 
+/**
+ * Allocates a disk.
+ */
 struct snapraid_disk* disk_alloc(const char* name, const char* dir);
 
+/**
+ * Deallocates a disk.
+ */
 void disk_free(struct snapraid_disk* disk);
 
+/**
+ * Gets a specific block of a disk.
+ * Returns 0 if the block is over the end of the disk or not used.
+ */
 static inline struct snapraid_block* disk_block_get(struct snapraid_disk* disk, block_off_t pos)
 {
 	if (pos < tommy_array_size(&disk->blockarr))

handle.h

@@ -40,10 +40,19 @@ int handle_create(struct snapraid_handle* handle, struct snapraid_file* file);
  */
 int handle_open(int ret_on_error, struct snapraid_handle* handle, struct snapraid_file* file);
 
+/**
+ * Close a file.
+ */
 void handle_close(struct snapraid_handle* handle);
 
+/**
+ * Read a block from a file.
+ */
 int handle_read(int ret_on_error, struct snapraid_handle* handle, struct snapraid_block* block, unsigned char* block_buffer, unsigned block_size);
 
+/**
+ * Writes a block to a file.
+ */
 void handle_write(struct snapraid_handle* handle, struct snapraid_block* block, unsigned char* block_buffer, unsigned block_size);
 
 #endif

parity.h

@@ -26,17 +26,35 @@
  */
 block_off_t parity_resize(struct snapraid_state* state);
 
+/**
+ * Creates the parity file.
+ */
 int parity_create(const char* path, data_off_t size);
 
+/**
+ * Opens an already existing parity file.
+ */
 int parity_open(int ret_on_error, const char* path);
 
+/**
+ * Flushes the parity file in the disk.
+ */
 void parity_sync(const char* path, int f);
 
+/**
+ * Closes the parity file.
+ */
 void parity_close(const char* path, int f);
 
-void parity_write(const char* parity_path, int parity_f, block_off_t pos, unsigned char* block_buffer, unsigned block_size);
-
+/**
+ * Read a block from the parity file.
+ */
 int parity_read(int ret_on_error, const char* parity_path, int parity_f, block_off_t pos, unsigned char* block_buffer, unsigned block_size);
 
+/**
+ * Writes a block in the parity file.
+ */
+void parity_write(const char* parity_path, int parity_f, block_off_t pos, unsigned char* block_buffer, unsigned block_size);
+
 #endif
 

state.h

@@ -35,10 +35,19 @@ struct snapraid_state {
 	tommy_array diskarr; /**< Disk array. */
 };
 
+/**
+ * Initializes the state.
+ */
 void state_init(struct snapraid_state* state);
 
+/**
+ * Deinitializes the state.
+ */
 void state_done(struct snapraid_state* state);
 
+/**
+ * Read the configuration file.
+ */
 void state_config(struct snapraid_state* state, const char* path, int verbose, int force);
 
 /**
@@ -47,25 +56,28 @@ void state_config(struct snapraid_state* state, const char* path, int verbose, i
 void state_read(struct snapraid_state* state);
 
 /**
- * Write the new state.
+ * Writes the new state.
  */
 void state_write(struct snapraid_state* state);
 
 /**
- * Update the internal state to represent the new state.
+ * Scans all the disks to update the state.
  */
 void state_scan(struct snapraid_state* state);
 
 /**
- * Sync.
+ * Syncs the parity data.
  */
 void state_sync(struct snapraid_state* state, block_off_t blockstart);
 
 /**
- * Check.
+ * Checks (and fixes) all the files and the parity data.
  */
 void state_check(struct snapraid_state* state, int fix, block_off_t blockstart);
 
+/**
+ * Writes the progress.
+ */
 int state_progress(time_t* start, time_t* last, block_off_t blockpos, block_off_t blockmax, data_off_t count_block, data_off_t count_size);
 
 #endif