Index: uspace/lib/ext4/libext4_extent.c
===================================================================
--- uspace/lib/ext4/libext4_extent.c	(revision cb7056ae1da753c448596f60b309940133614bba)
+++ uspace/lib/ext4/libext4_extent.c	(revision 728d771b70f52d20161ed3599fe51a7d6d8ee239)
@@ -41,5 +41,5 @@
 #include "libext4.h"
 
-/** Get logical number of the block covered extent.
+/** Get logical number of the block covered by extent.
  *
  * @param extent	extent to load number from
@@ -53,5 +53,5 @@
 /** Set logical number of the first block covered by extent.
  *
- * @param extent	extent to load number from
+ * @param extent	extent to set number to
  * @param iblock	logical number of the first block covered by extent
  */
@@ -103,6 +103,9 @@
 }
 
-// TODO start comments here
-
+/** Get logical number of the block covered by extent index.
+ *
+ * @param index 	extent index to load number from
+ * @return			logical number of the first block covered by extent index
+ */
 uint32_t ext4_extent_index_get_first_block(ext4_extent_index_t *index)
 {
@@ -110,10 +113,20 @@
 }
 
+/** Set logical number of the block covered by extent index.
+ *
+ * @param index 	extent index to set number to
+ * @param iblock	logical number of the first block covered by extent index
+ */
 void ext4_extent_index_set_first_block(ext4_extent_index_t *index,
-		uint32_t first)
-{
-	index->first_block = host2uint32_t_le(first);
-}
-
+		uint32_t iblock)
+{
+	index->first_block = host2uint32_t_le(iblock);
+}
+
+/** Get physical number of block where the child node is located.
+ *
+ * @param index		extent index to load number from
+ * @return			physical number of the block with child node
+ */
 uint64_t ext4_extent_index_get_leaf(ext4_extent_index_t *index)
 {
@@ -122,10 +135,20 @@
 }
 
-void ext4_extent_index_set_leaf(ext4_extent_index_t *index, uint64_t leaf)
-{
-	index->leaf_lo = host2uint32_t_le((leaf << 32) >> 32);
-	index->leaf_hi = host2uint16_t_le((uint16_t)(leaf >> 32));
-}
-
+/** Set physical number of block where the child node is located.
+ *
+ * @param index		extent index to set number to
+ * @param fblock	physical number of the block with child node
+ */
+void ext4_extent_index_set_leaf(ext4_extent_index_t *index, uint64_t fblock)
+{
+	index->leaf_lo = host2uint32_t_le((fblock << 32) >> 32);
+	index->leaf_hi = host2uint16_t_le((uint16_t)(fblock >> 32));
+}
+
+/** Get magic value from extent header.
+ *
+ * @param header	extent header to load value from
+ * @return			magic value of extent header
+ */
 uint16_t ext4_extent_header_get_magic(ext4_extent_header_t *header)
 {
@@ -133,4 +156,9 @@
 }
 
+/** Set magic value to extent header.
+ *
+ * @param header	extent header to set value to
+ * @param magic		magic value of extent header
+ */
 void ext4_extent_header_set_magic(ext4_extent_header_t *header, uint16_t magic)
 {
@@ -138,4 +166,9 @@
 }
 
+/** Get number of entries from extent header
+ *
+ * @param header	extent header to get value from
+ * @return			number of entries covered by extent header
+ */
 uint16_t ext4_extent_header_get_entries_count(ext4_extent_header_t *header)
 {
@@ -143,4 +176,9 @@
 }
 
+/** Set number of entries to extent header
+ *
+ * @param header	extent header to set value to
+ * @param count		number of entries covered by extent header
+ */
 void ext4_extent_header_set_entries_count(ext4_extent_header_t *header,
 		uint16_t count)
@@ -149,4 +187,9 @@
 }
 
+/** Get maximum number of entries from extent header
+ *
+ * @param header	extent header to get value from
+ * @return			maximum number of entries covered by extent header
+ */
 uint16_t ext4_extent_header_get_max_entries_count(ext4_extent_header_t *header)
 {
@@ -154,4 +197,9 @@
 }
 
+/** Set maximum number of entries to extent header
+ *
+ * @param header	extent header to set value to
+ * @param max_count maximum number of entries covered by extent header
+ */
 void ext4_extent_header_set_max_entries_count(ext4_extent_header_t *header,
 		uint16_t max_count)
@@ -160,4 +208,9 @@
 }
 
+/** Get depth of extent subtree.
+ *
+ * @param header	extent header to get value from
+ * @return			depth of extent subtree
+ */
 uint16_t ext4_extent_header_get_depth(ext4_extent_header_t *header)
 {
@@ -165,4 +218,9 @@
 }
 
+/** Set depth of extent subtree.
+ *
+ * @param header	extent header to set value to
+ * @param depth 	depth of extent subtree
+ */
 void ext4_extent_header_set_depth(ext4_extent_header_t *header, uint16_t depth)
 {
@@ -170,4 +228,9 @@
 }
 
+/** Get generation from extent header
+ *
+ * @param header 	extent header to get value from
+ * @return 			generation
+ */
 uint32_t ext4_extent_header_get_generation(ext4_extent_header_t *header)
 {
@@ -175,4 +238,9 @@
 }
 
+/** Set generation to extent header
+ *
+ * @param header 		extent header to set value to
+ * @param generation	generation
+ */
 void ext4_extent_header_set_generation(ext4_extent_header_t *header,
 		uint32_t generation)
@@ -181,6 +249,9 @@
 }
 
-/**
- * Binary search in extent index node
+/** Binary search in extent index node.
+ *
+ * @param header	extent header of index node
+ * @param index		output value - found index will be set here
+ * @param iblock	logical block number to find in index node
  */
 static void ext4_extent_binsearch_idx(ext4_extent_header_t *header,
@@ -191,4 +262,5 @@
 	uint16_t entries_count = ext4_extent_header_get_entries_count(header);
 
+	// Check trivial situation
 	if (entries_count == 1) {
 		*index = EXT4_EXTENT_FIRST_INDEX(header);
@@ -196,7 +268,9 @@
 	}
 
+	// Initialize bounds
 	l = EXT4_EXTENT_FIRST_INDEX(header) + 1;
 	r = l + entries_count - 1;
 
+	// Do binary search
 	while (l <= r) {
 		m = l + (r - l) / 2;
@@ -209,9 +283,14 @@
 	}
 
+	// Set output value
 	*index = l - 1;
 }
 
-/**
- * Binary search in extent leaf node
+/** Binary search in extent leaf node.
+ * @param header	extent header of leaf node
+ * @param extent	output value - found extent will be set here,
+ * 					or NULL if node is empty
+ * @param iblock	logical block number to find in leaf node
+ *
  */
 static void ext4_extent_binsearch(ext4_extent_header_t *header,
@@ -224,9 +303,9 @@
 	if (entries_count == 0) {
 		// this leaf is empty
-//		EXT4FS_DBG("EMPTY LEAF");
 		*extent = NULL;
 		return;
 	}
 
+	// Check trivial situation
 	if (entries_count == 1) {
 		*extent = EXT4_EXTENT_FIRST(header);
@@ -234,7 +313,9 @@
 	}
 
+	// Initialize bounds
 	l = EXT4_EXTENT_FIRST(header) + 1;
 	r = l + entries_count - 1;
 
+	// Do binary search
 	while (l < r) {
 		m = l + (r - l) / 2;
@@ -247,12 +328,23 @@
 	}
 
+	// Set output value
 	*extent = l - 1;
 }
 
-// Reading routine without saving blocks to path - for saving memory during finding block
-int ext4_extent_find_block(ext4_inode_ref_t *inode_ref, uint32_t iblock, uint32_t *fblock)
+/** Find physical block in the extent tree by logical block number.
+ *
+ * There is no need to save path in the tree during this algorithm.
+ *
+ * @param inode_ref		i-node to load block from
+ * @param iblock		logical block number to find
+ * @param fblock		output value for physical block number
+ * @return				error code
+ */
+int ext4_extent_find_block(ext4_inode_ref_t *inode_ref,
+		uint32_t iblock, uint32_t *fblock)
 {
 	int rc;
 
+	// Compute bound defined by i-node size
 	uint64_t inode_size = ext4_inode_get_size(
 			inode_ref->fs->superblock, inode_ref->inode);
@@ -263,4 +355,5 @@
 	uint32_t last_idx = (inode_size - 1) / block_size;
 
+	// Check if requested iblock is not over size of i-node
 	if (iblock > last_idx) {
 		*fblock = 0;
@@ -270,10 +363,13 @@
 	block_t* block = NULL;
 
+	// Walk through extent tree
 	ext4_extent_header_t *header = ext4_inode_get_extent_header(inode_ref->inode);
 	while (ext4_extent_header_get_depth(header) != 0) {
 
+		// Search index in node
 		ext4_extent_index_t *index;
 		ext4_extent_binsearch_idx(header, &index, iblock);
 
+		// Load child node and set values for the next iteration
 		uint64_t child = ext4_extent_index_get_leaf(index);
 
@@ -290,11 +386,14 @@
 	}
 
-
+	// Search extent in the leaf block
 	ext4_extent_t* extent = NULL;
 	ext4_extent_binsearch(header, &extent, iblock);
 
+	// Prevent empty leaf
 	if (extent == NULL) {
 		*fblock = 0;
 	} else {
+
+		// Compute requested physical block address
 		uint32_t phys_block;
 		phys_block = ext4_extent_get_start(extent) + iblock;
@@ -304,4 +403,5 @@
 	}
 
+	// Cleanup
 	if (block != NULL) {
 		block_put(block);
@@ -311,4 +411,15 @@
 }
 
+
+/** Find extent for specified iblock.
+ *
+ * This function is used for finding block in the extent tree with
+ * saving the path through the tree for possible future modifications.
+ *
+ * @param inode_ref		i-node to read extent tree from
+ * @param iblock		iblock to find extent for
+ * @param ret_path		output value for loaded path from extent tree
+ * @return				error code
+ */
 static int ext4_extent_find_extent(ext4_inode_ref_t *inode_ref,
 		uint32_t iblock, ext4_extent_path_t **ret_path)
@@ -329,10 +440,13 @@
 	}
 
+	// Initialize structure for algorithm start
 	tmp_path[0].block = inode_ref->block;
 	tmp_path[0].header = eh;
 
+	// Walk through the extent tree
 	uint16_t pos = 0;
 	while (ext4_extent_header_get_depth(eh) != 0) {
 
+		// Search index in index node by iblock
 		ext4_extent_binsearch_idx(tmp_path[pos].header, &tmp_path[pos].index, iblock);
 
@@ -342,4 +456,5 @@
 		assert(tmp_path[pos].index != NULL);
 
+		// Load information for the next iteration
 		uint64_t fblock = ext4_extent_index_get_leaf(tmp_path[pos].index);
 
@@ -362,5 +477,5 @@
 	tmp_path[pos].index = NULL;
 
-    /* find extent */
+    // Find extent in the leaf node
 	ext4_extent_binsearch(tmp_path[pos].header, &tmp_path[pos].extent, iblock);
 
@@ -382,11 +497,18 @@
 
 	return rc;
-
-}
-
-static int ext4_extent_release(ext4_inode_ref_t *inode_ref, ext4_extent_t* extent)
+}
+
+/** Release extent and all data blocks covered by the extent.
+ *
+ * @param inode_ref		i-node to release extent and block from
+ * @param extent		extent to release
+ * @return				error code
+ */
+static int ext4_extent_release(
+		ext4_inode_ref_t *inode_ref, ext4_extent_t *extent)
 {
 	int rc;
 
+	// Compute number of the first physical block to release
 	uint64_t start = ext4_extent_get_start(extent);
 	uint16_t block_count = ext4_extent_get_block_count(extent);
@@ -394,5 +516,5 @@
 	rc = ext4_balloc_free_blocks(inode_ref, start, block_count);
 	if (rc != EOK) {
-		EXT4FS_DBG("ERROR");
+		EXT4FS_DBG("Error in releasing data blocks");
 		return rc;
 	}
@@ -400,4 +522,6 @@
 	return EOK;
 }
+
+// TODO comments
 
 // Recursive release