Refine comments

Author: jserv

bitmap.h

@@ -5,11 +5,11 @@
 
 #include "simplefs.h"
 
-/* Return the first bit we found and clear the the following 'len' consecutive
- * free bit(s) (set to 1) in a given in-memory bitmap spanning over multiple
- * blocks. Return 0 if no enough free bit(s) were found (we assume that the
- * first bit is never free because of the superblock and the root inode, thus
- * allowing us to use 0 as an error value).
+/* Returns the first bit found and clears the following 'len' consecutive
+ * free bits (sets them to 1) in a given in-memory bitmap spanning multiple
+ * blocks. Returns 0 if an adequate number of free bits were not found.
+ * Assumes the first bit is never free (reserved for the superblock and the
+ * root inode), allowing the use of 0 as an error value.
  */
 static inline uint32_t get_first_free_bits(unsigned long *freemap,
                                            unsigned long size,
@@ -51,7 +51,6 @@ static inline uint32_t get_free_blocks(struct simplefs_sb_info *sbi,
     return ret;
 }
 
-
 /* Mark the 'len' bit(s) from i-th bit in freemap as free (i.e. 1) */
 static inline int put_free_bits(unsigned long *freemap,
                                 unsigned long size,

dir.c

@@ -7,9 +7,9 @@
 
 #include "simplefs.h"
 
-/* Iterate over the files contained in dir and commit them in ctx.
- * This function is called by the VFS while ctx->pos changes.
- * Return 0 on success.
+/* Iterate over the files contained in dir and commit them to @ctx.
+ * This function is called by the VFS as ctx->pos changes.
+ * Returns 0 on success.
  */
 static int simplefs_iterate(struct file *dir, struct dir_context *ctx)
 {

extent.c

@@ -3,10 +3,10 @@
 
 #include "simplefs.h"
 
-/* Search the extent which contain the target block.
- * Return the first unused file index if not found.
- * Return -1 if it is out of range.
- * TODO: use binary search.
+/* Search for the extent containing the target block.
+ * Returns the first unused file index if not found.
+ * Returns -1 if the target block is out of range.
+ * TODO: Implement binary search for efficiency.
  */
 uint32_t simplefs_ext_search(struct simplefs_file_ei_block *index,
                              uint32_t iblock)

file.c

@@ -78,8 +78,8 @@ static int simplefs_file_get_block(struct inode *inode,
     return ret;
 }
 
-/* Called by the page cache to read a page from the physical disk and map it in
- * memory.
+/* Called by the page cache to read a page from the physical disk and map it
+ * into memory.
  */
 #if LINUX_VERSION_CODE >= KERNEL_VERSION(5, 19, 0)
 static void simplefs_readahead(struct readahead_control *rac)
@@ -101,9 +101,9 @@ static int simplefs_writepage(struct page *page, struct writeback_control *wbc)
     return block_write_full_page(page, simplefs_file_get_block, wbc);
 }
 
-/* Called by the VFS when a write() syscall occurs on file before writing the
- * data in the page cache. This functions checks if the write will be able to
- * complete and allocates the necessary blocks through block_write_begin().
+/* Called by the VFS when a write() syscall is made on a file, before writing
+ * the data into the page cache. This function checks if the write operation
+ * can complete and allocates the necessary blocks through block_write_begin().
  */
 #if LINUX_VERSION_CODE >= KERNEL_VERSION(5, 19, 0)
 static int simplefs_write_begin(struct file *file,
@@ -152,7 +152,7 @@ static int simplefs_write_begin(struct file *file,
 }
 
 /* Called by the VFS after writing data from a write() syscall to the page
- * cache. This functions updates inode metadata and truncates the file if
+ * cache. This function updates inode metadata and truncates the file if
  * necessary.
  */
 static int simplefs_write_end(struct file *file,

inode.c

@@ -96,9 +96,11 @@ struct inode *simplefs_iget(struct super_block *sb, unsigned long ino)
     return ERR_PTR(ret);
 }
 
-/* Look for dentry in dir.
- * Fill dentry with NULL if not in dir, with the corresponding inode if found.
- * Returns NULL on success.
+/* Searches for a dentry in dir.
+ * Fills dentry with NULL if not found in dir, or with the corresponding inode
+ * if found.
+ * Returns NULL on success, indicating the dentry was successfully filled or
+ * confirmed absent.
  */
 static struct dentry *simplefs_lookup(struct inode *dir,
                                       struct dentry *dentry,
@@ -554,10 +556,11 @@ static int simplefs_unlink(struct inode *dir, struct dentry *dentry)
         return ret;
     }
 
-    /* Cleanup pointed blocks if unlinking a file. If we fail to read the
-     * index block, cleanup inode anyway and lose this file's blocks
-     * forever. If we fail to scrub a data block, don't fail (too late
-     * anyway), just put the block and continue.
+    /* Cleans up pointed blocks when unlinking a file. If reading the index
+     * block fails, the inode is cleaned up regardless, resulting in the
+     * permanent loss of this file's blocks. If scrubbing a data block fails,
+     * do not terminate the operation (as it is already too late); instead,
+     * release the block and proceed.
      */
     bno = SIMPLEFS_INODE(inode)->ei_block;
     bh = sb_bread(sb, bno);