fs/ntfs3: Restyle comments to better align with kernel-doc

Capitalize comments and end with period for better reading.

Also function comments are now little more kernel-doc style. This way we
can easily convert them to kernel-doc style if we want. Note that these
are not yet complete with this style. Example function comments start
with /* and in kernel-doc style they start /**.

Use imperative mood in function descriptions.

Change words like ntfs -> NTFS, linux -> Linux.

Use "we" not "I" when commenting code.

Signed-off-by: Kari Argillander <kari.argillander@gmail.com>
Signed-off-by: Konstantin Komarov <almaz.alexandrovich@paragon-software.com>

1 files changed, 200 insertions, 195 deletions

diff --git a/fs/ntfs3/index.c b/fs/ntfs3/index.c
index 69c6c4e0b4d9..70ef59455b72 100644
--- a/fs/ntfs3/index.c
+++ b/fs/ntfs3/index.c
@@ -24,9 +24,10 @@ static const struct INDEX_NAMES {
 };
 
 /*
- * compare two names in index
+ * cmp_fnames - Compare two names in index.
+ *
  * if l1 != 0
- *   both names are little endian on-disk ATTR_FILE_NAME structs
+ *   Both names are little endian on-disk ATTR_FILE_NAME structs.
  * else
  *   key1 - cpu_str, key2 - ATTR_FILE_NAME
  */
@@ -52,7 +53,7 @@ static int cmp_fnames(const void *key1, size_t l1, const void *key2, size_t l2,
 
 		/*
 		 * If names are equal (case insensitive)
-		 * try to compare it case sensitive
+		 * try to compare it case sensitive.
 		 */
 		return ntfs_cmp_names_cpu(key1, s2, sbi->upcase, both_case);
 	}
@@ -62,7 +63,9 @@ static int cmp_fnames(const void *key1, size_t l1, const void *key2, size_t l2,
 			      sbi->upcase, both_case);
 }
 
-/* $SII of $Secure and $Q of Quota */
+/*
+ * cmp_uint - $SII of $Secure and $Q of Quota
+ */
 static int cmp_uint(const void *key1, size_t l1, const void *key2, size_t l2,
 		    const void *data)
 {
@@ -79,7 +82,9 @@ static int cmp_uint(const void *key1, size_t l1, const void *key2, size_t l2,
 	return 0;
 }
 
-/* $SDH of $Secure */
+/*
+ * cmp_sdh - $SDH of $Secure
+ */
 static int cmp_sdh(const void *key1, size_t l1, const void *key2, size_t l2,
 		   const void *data)
 {
@@ -93,13 +98,13 @@ static int cmp_sdh(const void *key1, size_t l1, const void *key2, size_t l2,
 	t1 = le32_to_cpu(k1->hash);
 	t2 = le32_to_cpu(k2->hash);
 
-	/* First value is a hash value itself */
+	/* First value is a hash value itself. */
 	if (t1 < t2)
 		return -1;
 	if (t1 > t2)
 		return 1;
 
-	/* Second value is security Id */
+	/* Second value is security Id. */
 	if (data) {
 		t1 = le32_to_cpu(k1->sec_id);
 		t2 = le32_to_cpu(k2->sec_id);
@@ -112,7 +117,9 @@ static int cmp_sdh(const void *key1, size_t l1, const void *key2, size_t l2,
 	return 0;
 }
 
-/* $O of ObjId and "$R" for Reparse */
+/*
+ * cmp_uints - $O of ObjId and "$R" for Reparse.
+ */
 static int cmp_uints(const void *key1, size_t l1, const void *key2, size_t l2,
 		     const void *data)
 {
@@ -122,12 +129,13 @@ static int cmp_uints(const void *key1, size_t l1, const void *key2, size_t l2,
 
 	if ((size_t)data == 1) {
 		/*
-		 * ni_delete_all -> ntfs_remove_reparse -> delete all with this reference
+		 * ni_delete_all -> ntfs_remove_reparse ->
+		 * delete all with this reference.
 		 * k1, k2 - pointers to REPARSE_KEY
 		 */
 
-		k1 += 1; // skip REPARSE_KEY.ReparseTag
-		k2 += 1; // skip REPARSE_KEY.ReparseTag
+		k1 += 1; // Skip REPARSE_KEY.ReparseTag
+		k2 += 1; // Skip REPARSE_KEY.ReparseTag
 		if (l2 <= sizeof(int))
 			return -1;
 		l2 -= sizeof(int);
@@ -229,7 +237,7 @@ static int bmp_buf_get(struct ntfs_index *indx, struct ntfs_inode *ni,
 
 	data_size = le64_to_cpu(b->nres.data_size);
 	if (WARN_ON(off >= data_size)) {
-		/* looks like filesystem error */
+		/* Looks like filesystem error. */
 		return -EINVAL;
 	}
 
@@ -303,9 +311,7 @@ out:
 }
 
 /*
- * indx_mark_used
- *
- * marks the bit 'bit' as used
+ * indx_mark_used - Mark the bit @bit as used.
  */
 static int indx_mark_used(struct ntfs_index *indx, struct ntfs_inode *ni,
 			  size_t bit)
@@ -325,9 +331,7 @@ static int indx_mark_used(struct ntfs_index *indx, struct ntfs_inode *ni,
 }
 
 /*
- * indx_mark_free
- *
- * the bit 'bit' as free
+ * indx_mark_free - Mark the bit @bit as free.
  */
 static int indx_mark_free(struct ntfs_index *indx, struct ntfs_inode *ni,
 			  size_t bit)
@@ -347,9 +351,11 @@ static int indx_mark_free(struct ntfs_index *indx, struct ntfs_inode *ni,
 }
 
 /*
- * if ntfs_readdir calls this function (indx_used_bit -> scan_nres_bitmap),
- * inode is shared locked and no ni_lock
- * use rw_semaphore for read/write access to bitmap_run
+ * scan_nres_bitmap
+ *
+ * If ntfs_readdir calls this function (indx_used_bit -> scan_nres_bitmap),
+ * inode is shared locked and no ni_lock.
+ * Use rw_semaphore for read/write access to bitmap_run.
  */
 static int scan_nres_bitmap(struct ntfs_inode *ni, struct ATTRIB *bitmap,
 			    struct ntfs_index *indx, size_t from,
@@ -460,10 +466,9 @@ static bool scan_for_free(const ulong *buf, u32 bit, u32 bits, size_t *ret)
 }
 
 /*
- * indx_find_free
+ * indx_find_free - Look for free bit.
  *
- * looks for free bit
- * returns -1 if no free bits
+ * Return: -1 if no free bits.
  */
 static int indx_find_free(struct ntfs_index *indx, struct ntfs_inode *ni,
 			  size_t *bit, struct ATTRIB **bitmap)
@@ -509,10 +514,9 @@ static bool scan_for_used(const ulong *buf, u32 bit, u32 bits, size_t *ret)
 }
 
 /*
- * indx_used_bit
+ * indx_used_bit - Look for used bit.
  *
- * looks for used bit
- * returns MINUS_ONE_T if no used bits
+ * Return: MINUS_ONE_T if no used bits.
  */
 int indx_used_bit(struct ntfs_index *indx, struct ntfs_inode *ni, size_t *bit)
 {
@@ -548,9 +552,8 @@ int indx_used_bit(struct ntfs_index *indx, struct ntfs_inode *ni, size_t *bit)
 /*
  * hdr_find_split
  *
- * finds a point at which the index allocation buffer would like to
- * be split.
- * NOTE: This function should never return 'END' entry NULL returns on error
+ * Find a point at which the index allocation buffer would like to be split.
+ * NOTE: This function should never return 'END' entry NULL returns on error.
  */
 static const struct NTFS_DE *hdr_find_split(const struct INDEX_HDR *hdr)
 {
@@ -568,7 +571,7 @@ static const struct NTFS_DE *hdr_find_split(const struct INDEX_HDR *hdr)
 
 		e = Add2Ptr(hdr, o);
 
-		/* We must not return END entry */
+		/* We must not return END entry. */
 		if (de_is_last(e))
 			return p;
 
@@ -579,9 +582,8 @@ static const struct NTFS_DE *hdr_find_split(const struct INDEX_HDR *hdr)
 }
 
 /*
- * hdr_insert_head
+ * hdr_insert_head - Insert some entries at the beginning of the buffer.
  *
- * inserts some entries at the beginning of the buffer.
  * It is used to insert entries into a newly-created buffer.
  */
 static const struct NTFS_DE *hdr_insert_head(struct INDEX_HDR *hdr,
@@ -656,14 +658,14 @@ static bool fnd_is_empty(struct ntfs_fnd *fnd)
 }
 
 /*
- * hdr_find_e
+ * hdr_find_e - Locate an entry the index buffer.
  *
- * locates an entry the index buffer.
  * If no matching entry is found, it returns the first entry which is greater
  * than the desired entry If the search key is greater than all the entries the
  * buffer, it returns the 'end' entry. This function does a binary search of the
- * current index buffer, for the first entry that is <= to the search value
- * Returns NULL if error
+ * current index buffer, for the first entry that is <= to the search value.
+ *
+ * Return: NULL if error.
  */
 static struct NTFS_DE *hdr_find_e(const struct ntfs_index *indx,
 				  const struct INDEX_HDR *hdr, const void *key,
@@ -687,7 +689,7 @@ static struct NTFS_DE *hdr_find_e(const struct ntfs_index *indx,
 	if (!offs)
 		goto next;
 
-	/* use binary search algorithm */
+	/* Use binary search algorithm. */
 next1:
 	if (off + sizeof(struct NTFS_DE) > end) {
 		e = NULL;
@@ -715,7 +717,7 @@ next1:
 			goto next;
 	}
 
-	/* Store entry table */
+	/* Store entry table. */
 	offs[max_idx] = off;
 
 	if (!de_is_last(e)) {
@@ -725,8 +727,8 @@ next1:
 	}
 
 	/*
-	 * Table of pointers is created
-	 * Use binary search to find entry that is <= to the search value
+	 * Table of pointers is created.
+	 * Use binary search to find entry that is <= to the search value.
 	 */
 	fnd = -1;
 	min_idx = 0;
@@ -772,8 +774,9 @@ out1:
 
 next:
 	/*
-	 * Entries index are sorted
-	 * Enumerate all entries until we find entry that is <= to the search value
+	 * Entries index are sorted.
+	 * Enumerate all entries until we find entry
+	 * that is <= to the search value.
 	 */
 	if (off + sizeof(struct NTFS_DE) > end)
 		return NULL;
@@ -803,10 +806,9 @@ next:
 }
 
 /*
- * hdr_insert_de
+ * hdr_insert_de - Insert an index entry into the buffer.
  *
- * inserts an index entry into the buffer.
- * 'before' should be a pointer previously returned from hdr_find_e
+ * 'before' should be a pointer previously returned from hdr_find_e.
  */
 static struct NTFS_DE *hdr_insert_de(const struct ntfs_index *indx,
 				     struct INDEX_HDR *hdr,
@@ -819,20 +821,20 @@ static struct NTFS_DE *hdr_insert_de(const struct ntfs_index *indx,
 	u32 total = le32_to_cpu(hdr->total);
 	u16 de_size = le16_to_cpu(de->size);
 
-	/* First, check to see if there's enough room */
+	/* First, check to see if there's enough room. */
 	if (used + de_size > total)
 		return NULL;
 
 	/* We know there's enough space, so we know we'll succeed. */
 	if (before) {
-		/* Check that before is inside Index */
+		/* Check that before is inside Index. */
 		if (off >= used || off < le32_to_cpu(hdr->de_off) ||
 		    off + le16_to_cpu(before->size) > total) {
 			return NULL;
 		}
 		goto ok;
 	}
-	/* No insert point is applied. Get it manually */
+	/* No insert point is applied. Get it manually. */
 	before = hdr_find_e(indx, hdr, de + 1, le16_to_cpu(de->key_size), ctx,
 			    &diff);
 	if (!before)
@@ -850,9 +852,7 @@ ok:
 }
 
 /*
- * hdr_delete_de
- *
- * removes an entry from the index buffer
+ * hdr_delete_de - Remove an entry from the index buffer.
  */
 static inline struct NTFS_DE *hdr_delete_de(struct INDEX_HDR *hdr,
 					    struct NTFS_DE *re)
@@ -884,7 +884,7 @@ int indx_init(struct ntfs_index *indx, struct ntfs_sb_info *sbi,
 	u32 t32;
 	const struct INDEX_ROOT *root = resident_data(attr);
 
-	/* Check root fields */
+	/* Check root fields. */
 	if (!root->index_block_clst)
 		return -EINVAL;
 
@@ -894,13 +894,13 @@ int indx_init(struct ntfs_index *indx, struct ntfs_sb_info *sbi,
 	t32 = le32_to_cpu(root->index_block_size);
 	indx->index_bits = blksize_bits(t32);
 
-	/* Check index record size */
+	/* Check index record size. */
 	if (t32 < sbi->cluster_size) {
-		/* index record is smaller than a cluster, use 512 blocks */
+		/* Index record is smaller than a cluster, use 512 blocks. */
 		if (t32 != root->index_block_clst * SECTOR_SIZE)
 			return -EINVAL;
 
-		/* Check alignment to a cluster */
+		/* Check alignment to a cluster. */
 		if ((sbi->cluster_size >> SECTOR_SHIFT) &
 		    (root->index_block_clst - 1)) {
 			return -EINVAL;
@@ -908,7 +908,7 @@ int indx_init(struct ntfs_index *indx, struct ntfs_sb_info *sbi,
 
 		indx->vbn2vbo_bits = SECTOR_SHIFT;
 	} else {
-		/* index record must be a multiple of cluster size */
+		/* Index record must be a multiple of cluster size. */
 		if (t32 != root->index_block_clst << sbi->cluster_bits)
 			return -EINVAL;
 
@@ -953,7 +953,7 @@ static struct indx_node *indx_new(struct ntfs_index *indx,
 		return ERR_PTR(err);
 	}
 
-	/* Create header */
+	/* Create header. */
 	index->rhdr.sign = NTFS_INDX_SIGNATURE;
 	index->rhdr.fix_off = cpu_to_le16(sizeof(struct INDEX_BUFFER)); // 0x28
 	fn = (bytes >> SECTOR_SHIFT) + 1; // 9
@@ -1011,9 +1011,11 @@ static int indx_write(struct ntfs_index *indx, struct ntfs_inode *ni,
 }
 
 /*
- * if ntfs_readdir calls this function
- * inode is shared locked and no ni_lock
- * use rw_semaphore for read/write access to alloc_run
+ * indx_read
+ *
+ * If ntfs_readdir calls this function
+ * inode is shared locked and no ni_lock.
+ * Use rw_semaphore for read/write access to alloc_run.
  */
 int indx_read(struct ntfs_index *indx, struct ntfs_inode *ni, CLST vbn,
 	      struct indx_node **node)
@@ -1095,9 +1097,7 @@ out:
 }
 
 /*
- * indx_find
- *
- * scans NTFS directory for given entry
+ * indx_find - Scan NTFS directory for given entry.
  */
 int indx_find(struct ntfs_index *indx, struct ntfs_inode *ni,
 	      const struct INDEX_ROOT *root, const void *key, size_t key_len,
@@ -1119,7 +1119,7 @@ int indx_find(struct ntfs_index *indx, struct ntfs_inode *ni,
 
 	hdr = &root->ihdr;
 
-	/* Check cache */
+	/* Check cache. */
 	e = fnd->level ? fnd->de[fnd->level - 1] : fnd->root_de;
 	if (e && !de_is_last(e) &&
 	    !(*indx->cmp)(key, key_len, e + 1, le16_to_cpu(e->key_size), ctx)) {
@@ -1128,10 +1128,10 @@ int indx_find(struct ntfs_index *indx, struct ntfs_inode *ni,
 		return 0;
 	}
 
-	/* Soft finder reset */
+	/* Soft finder reset. */
 	fnd_clear(fnd);
 
-	/* Lookup entry that is <= to the search value */
+	/* Lookup entry that is <= to the search value. */
 	e = hdr_find_e(indx, hdr, key, key_len, ctx, diff);
 	if (!e)
 		return -EINVAL;
@@ -1153,7 +1153,7 @@ int indx_find(struct ntfs_index *indx, struct ntfs_inode *ni,
 		if (err)
 			goto out;
 
-		/* Lookup entry that is <= to the search value */
+		/* Lookup entry that is <= to the search value. */
 		e = hdr_find_e(indx, &node->index->ihdr, key, key_len, ctx,
 			       diff);
 		if (!e) {
@@ -1180,7 +1180,7 @@ int indx_find_sort(struct ntfs_index *indx, struct ntfs_inode *ni,
 	int level = fnd->level;
 
 	if (!*entry) {
-		/* Start find */
+		/* Start find. */
 		e = hdr_first_de(&root->ihdr);
 		if (!e)
 			return 0;
@@ -1210,7 +1210,7 @@ int indx_find_sort(struct ntfs_index *indx, struct ntfs_inode *ni,
 		fnd->de[level - 1] = e;
 	}
 
-	/* Just to avoid tree cycle */
+	/* Just to avoid tree cycle. */
 next_iter:
 	if (iter++ >= 1000)
 		return -EINVAL;
@@ -1225,12 +1225,12 @@ next_iter:
 			return -EINVAL;
 		}
 
-		/* Read next level */
+		/* Read next level. */
 		err = indx_read(indx, ni, de_get_vbn(e), &n);
 		if (err)
 			return err;
 
-		/* Try next level */
+		/* Try next level. */
 		e = hdr_first_de(&n->index->ihdr);
 		if (!e) {
 			kfree(n);
@@ -1250,7 +1250,7 @@ pop_level:
 		if (!de_is_last(e))
 			goto next_iter;
 
-		/* Pop one level */
+		/* Pop one level. */
 		if (n) {
 			fnd_pop(fnd);
 			kfree(n);
@@ -1292,35 +1292,35 @@ int indx_find_raw(struct ntfs_index *indx, struct ntfs_inode *ni,
 	CLST next_vbn;
 	u32 record_size = ni->mi.sbi->record_size;
 
-	/* Use non sorted algorithm */
+	/* Use non sorted algorithm. */
 	if (!*entry) {
-		/* This is the first call */
+		/* This is the first call. */
 		e = hdr_first_de(&root->ihdr);
 		if (!e)
 			return 0;
 		fnd_clear(fnd);
 		fnd->root_de = e;
 
-		/* The first call with setup of initial element */
+		/* The first call with setup of initial element. */
 		if (*off >= record_size) {
 			next_vbn = (((*off - record_size) >> indx->index_bits))
 				   << indx->idx2vbn_bits;
-			/* jump inside cycle 'for'*/
+			/* Jump inside cycle 'for'. */
 			goto next;
 		}
 
-		/* Start enumeration from root */
+		/* Start enumeration from root. */
 		*off = 0;
 	} else if (!fnd->root_de)
 		return -EINVAL;
 
 	for (;;) {
-		/* Check if current entry can be used */
+		/* Check if current entry can be used. */
 		if (e && le16_to_cpu(e->size) > sizeof(struct NTFS_DE))
 			goto ok;
 
 		if (!fnd->level) {
-			/* Continue to enumerate root */
+			/* Continue to enumerate root. */
 			if (!de_is_last(fnd->root_de)) {
 				e = hdr_next_de(&root->ihdr, fnd->root_de);
 				if (!e)
@@ -1329,10 +1329,10 @@ int indx_find_raw(struct ntfs_index *indx, struct ntfs_inode *ni,
 				continue;
 			}
 
-			/* Start to enumerate indexes from 0 */
+			/* Start to enumerate indexes from 0. */
 			next_vbn = 0;
 		} else {
-			/* Continue to enumerate indexes */
+			/* Continue to enumerate indexes. */
 			e2 = fnd->de[fnd->level - 1];
 
 			n = fnd->nodes[fnd->level - 1];
@@ -1345,31 +1345,31 @@ int indx_find_raw(struct ntfs_index *indx, struct ntfs_inode *ni,
 				continue;
 			}
 
-			/* Continue with next index */
+			/* Continue with next index. */
 			next_vbn = le64_to_cpu(n->index->vbn) +
 				   root->index_block_clst;
 		}
 
 next:
-		/* Release current index */
+		/* Release current index. */
 		if (n) {
 			fnd_pop(fnd);
 			put_indx_node(n);
 			n = NULL;
 		}
 
-		/* Skip all free indexes */
+		/* Skip all free indexes. */
 		bit = next_vbn >> indx->idx2vbn_bits;
 		err = indx_used_bit(indx, ni, &bit);
 		if (err == -ENOENT || bit == MINUS_ONE_T) {
-			/* No used indexes */
+			/* No used indexes. */
 			*entry = NULL;
 			return 0;
 		}
 
 		next_used_vbn = bit << indx->idx2vbn_bits;
 
-		/* Read buffer into memory */
+		/* Read buffer into memory. */
 		err = indx_read(indx, ni, next_used_vbn, &n);
 		if (err)
 			return err;
@@ -1381,12 +1381,12 @@ next:
 	}
 
 ok:
-	/* return offset to restore enumerator if necessary */
+	/* Return offset to restore enumerator if necessary. */
 	if (!n) {
-		/* 'e' points in root */
+		/* 'e' points in root, */
 		*off = PtrOffset(&root->ihdr, e);
 	} else {
-		/* 'e' points in index */
+		/* 'e' points in index, */
 		*off = (le64_to_cpu(n->index->vbn) << indx->vbn2vbo_bits) +
 		       record_size + PtrOffset(&n->index->ihdr, e);
 	}
@@ -1396,9 +1396,7 @@ ok:
 }
 
 /*
- * indx_create_allocate
- *
- * create "Allocation + Bitmap" attributes
+ * indx_create_allocate - Create "Allocation + Bitmap" attributes.
  */
 static int indx_create_allocate(struct ntfs_index *indx, struct ntfs_inode *ni,
 				CLST *vbn)
@@ -1455,9 +1453,7 @@ out:
 }
 
 /*
- * indx_add_allocate
- *
- * add clusters to index
+ * indx_add_allocate - Add clusters to index.
  */
 static int indx_add_allocate(struct ntfs_index *indx, struct ntfs_inode *ni,
 			     CLST *vbn)
@@ -1490,7 +1486,7 @@ static int indx_add_allocate(struct ntfs_index *indx, struct ntfs_inode *ni,
 	data_size = (u64)(bit + 1) << indx->index_bits;
 
 	if (bmp) {
-		/* Increase bitmap */
+		/* Increase bitmap. */
 		err = attr_set_size(ni, ATTR_BITMAP, in->name, in->name_len,
 				    &indx->bitmap_run, bitmap_size(bit + 1),
 				    NULL, true, NULL);
@@ -1507,7 +1503,7 @@ static int indx_add_allocate(struct ntfs_index *indx, struct ntfs_inode *ni,
 		goto out1;
 	}
 
-	/* Increase allocation */
+	/* Increase allocation. */
 	err = attr_set_size(ni, ATTR_ALLOC, in->name, in->name_len,
 			    &indx->alloc_run, data_size, &data_size, true,
 			    NULL);
@@ -1522,7 +1518,7 @@ static int indx_add_allocate(struct ntfs_index *indx, struct ntfs_inode *ni,
 	return 0;
 
 out2:
-	/* Ops (no space?) */
+	/* Ops. No space? */
 	attr_set_size(ni, ATTR_BITMAP, in->name, in->name_len,
 		      &indx->bitmap_run, bmp_size, &bmp_size_v, false, NULL);
 
@@ -1531,9 +1527,8 @@ out1:
 }
 
 /*
- * indx_insert_into_root
+ * indx_insert_into_root - Attempt to insert an entry into the index root.
  *
- * attempts to insert an entry into the index root
  * If necessary, it will twiddle the index b-tree.
  */
 static int indx_insert_into_root(struct ntfs_index *indx, struct ntfs_inode *ni,
@@ -1557,7 +1552,7 @@ static int indx_insert_into_root(struct ntfs_index *indx, struct ntfs_inode *ni,
 	int ds_root;
 	struct INDEX_ROOT *root, *a_root;
 
-	/* Get the record this root placed in */
+	/* Get the record this root placed in. */
 	root = indx_get_root(indx, ni, &attr, &mi);
 	if (!root)
 		return -EINVAL;
@@ -1579,7 +1574,7 @@ static int indx_insert_into_root(struct ntfs_index *indx, struct ntfs_inode *ni,
 	ds_root = new_de_size + hdr_used - hdr_total;
 
 	if (used + ds_root < sbi->max_bytes_per_attr) {
-		/* make a room for new elements */
+		/* Make a room for new elements. */
 		mi_resize_attr(mi, attr, ds_root);
 		hdr->total = cpu_to_le32(hdr_total + ds_root);
 		e = hdr_insert_de(indx, hdr, new_de, root_de, ctx);
@@ -1590,16 +1585,19 @@ static int indx_insert_into_root(struct ntfs_index *indx, struct ntfs_inode *ni,
 		return 0;
 	}
 
-	/* Make a copy of root attribute to restore if error */
+	/* Make a copy of root attribute to restore if error. */
 	a_root = kmemdup(attr, asize, GFP_NOFS);
 	if (!a_root)
 		return -ENOMEM;
 
-	/* copy all the non-end entries from the index root to the new buffer.*/
+	/*
+	 * Copy all the non-end entries from
+	 * the index root to the new buffer.
+	 */
 	to_move = 0;
 	e0 = hdr_first_de(hdr);
 
-	/* Calculate the size to copy */
+	/* Calculate the size to copy. */
 	for (e = e0;; e = hdr_next_de(hdr, e)) {
 		if (!e) {
 			err = -EINVAL;
@@ -1632,7 +1630,7 @@ static int indx_insert_into_root(struct ntfs_index *indx, struct ntfs_inode *ni,
 	ds_root = new_root_size - root_size;
 
 	if (ds_root > 0 && used + ds_root > sbi->max_bytes_per_attr) {
-		/* make root external */
+		/* Make root external. */
 		err = -EOPNOTSUPP;
 		goto out_free_re;
 	}
@@ -1640,7 +1638,7 @@ static int indx_insert_into_root(struct ntfs_index *indx, struct ntfs_inode *ni,
 	if (ds_root)
 		mi_resize_attr(mi, attr, ds_root);
 
-	/* Fill first entry (vcn will be set later) */
+	/* Fill first entry (vcn will be set later). */
 	e = (struct NTFS_DE *)(root + 1);
 	memset(e, 0, sizeof(struct NTFS_DE));
 	e->size = cpu_to_le16(sizeof(struct NTFS_DE) + sizeof(u64));
@@ -1653,26 +1651,26 @@ static int indx_insert_into_root(struct ntfs_index *indx, struct ntfs_inode *ni,
 	fnd->root_de = hdr_first_de(hdr);
 	mi->dirty = true;
 
-	/* Create alloc and bitmap attributes (if not) */
+	/* Create alloc and bitmap attributes (if not). */
 	err = run_is_empty(&indx->alloc_run)
 		      ? indx_create_allocate(indx, ni, &new_vbn)
 		      : indx_add_allocate(indx, ni, &new_vbn);
 
-	/* layout of record may be changed, so rescan root */
+	/* Layout of record may be changed, so rescan root. */
 	root = indx_get_root(indx, ni, &attr, &mi);
 	if (!root) {
-		/* bug? */
+		/* Bug? */
 		ntfs_set_state(sbi, NTFS_DIRTY_ERROR);
 		err = -EINVAL;
 		goto out_free_re;
 	}
 
 	if (err) {
-		/* restore root */
+		/* Restore root. */
 		if (mi_resize_attr(mi, attr, -ds_root))
 			memcpy(attr, a_root, asize);
 		else {
-			/* bug? */
+			/* Bug? */
 			ntfs_set_state(sbi, NTFS_DIRTY_ERROR);
 		}
 		goto out_free_re;
@@ -1682,7 +1680,7 @@ static int indx_insert_into_root(struct ntfs_index *indx, struct ntfs_inode *ni,
 	*(__le64 *)(e + 1) = cpu_to_le64(new_vbn);
 	mi->dirty = true;
 
-	/* now we can create/format the new buffer and copy the entries into */
+	/* Now we can create/format the new buffer and copy the entries into. */
 	n = indx_new(indx, ni, new_vbn, sub_vbn);
 	if (IS_ERR(n)) {
 		err = PTR_ERR(n);
@@ -1693,19 +1691,19 @@ static int indx_insert_into_root(struct ntfs_index *indx, struct ntfs_inode *ni,
 	hdr_used = le32_to_cpu(hdr->used);
 	hdr_total = le32_to_cpu(hdr->total);
 
-	/* Copy root entries into new buffer */
+	/* Copy root entries into new buffer. */
 	hdr_insert_head(hdr, re, to_move);
 
-	/* Update bitmap attribute */
+	/* Update bitmap attribute. */
 	indx_mark_used(indx, ni, new_vbn >> indx->idx2vbn_bits);
 
-	/* Check if we can insert new entry new index buffer */
+	/* Check if we can insert new entry new index buffer. */
 	if (hdr_used + new_de_size > hdr_total) {
 		/*
-		 * This occurs if mft record is the same or bigger than index
+		 * This occurs if MFT record is the same or bigger than index
 		 * buffer. Move all root new index and have no space to add
-		 * new entry classic case when mft record is 1K and index
-		 * buffer 4K the problem should not occurs
+		 * new entry classic case when MFT record is 1K and index
+		 * buffer 4K the problem should not occurs.
 		 */
 		kfree(re);
 		indx_write(indx, ni, n, 0);
@@ -1717,8 +1715,8 @@ static int indx_insert_into_root(struct ntfs_index *indx, struct ntfs_inode *ni,
 	}
 
 	/*
-	 * Now root is a parent for new index buffer
-	 * Insert NewEntry a new buffer
+	 * Now root is a parent for new index buffer.
+	 * Insert NewEntry a new buffer.
 	 */
 	e = hdr_insert_de(indx, hdr, new_de, NULL, ctx);
 	if (!e) {
@@ -1727,7 +1725,7 @@ static int indx_insert_into_root(struct ntfs_index *indx, struct ntfs_inode *ni,
 	}
 	fnd_push(fnd, n, e);
 
-	/* Just write updates index into disk */
+	/* Just write updates index into disk. */
 	indx_write(indx, ni, n, 0);
 
 	n = NULL;
@@ -1744,7 +1742,7 @@ out_free_root:
 /*
  * indx_insert_into_buffer
  *
- * attempts to insert an entry into an Index Allocation Buffer.
+ * Attempt to insert an entry into an Index Allocation Buffer.
  * If necessary, it will split the buffer.
  */
 static int
@@ -1764,12 +1762,12 @@ indx_insert_into_buffer(struct ntfs_index *indx, struct ntfs_inode *ni,
 	__le64 t_vbn, *sub_vbn;
 	u16 sp_size;
 
-	/* Try the most easy case */
+	/* Try the most easy case. */
 	e = fnd->level - 1 == level ? fnd->de[level] : NULL;
 	e = hdr_insert_de(indx, hdr1, new_de, e, ctx);
 	fnd->de[level] = e;
 	if (e) {
-		/* Just write updated index into disk */
+		/* Just write updated index into disk. */
 		indx_write(indx, ni, n1, 0);
 		return 0;
 	}
@@ -1809,7 +1807,7 @@ indx_insert_into_buffer(struct ntfs_index *indx, struct ntfs_inode *ni,
 	if (err)
 		goto out;
 
-	/* Allocate and format memory a new index buffer */
+	/* Allocate and format memory a new index buffer. */
 	n2 = indx_new(indx, ni, new_vbn, sub_vbn);
 	if (IS_ERR(n2)) {
 		err = PTR_ERR(n2);
@@ -1818,20 +1816,23 @@ indx_insert_into_buffer(struct ntfs_index *indx, struct ntfs_inode *ni,
 
 	hdr2 = &n2->index->ihdr;
 
-	/* Make sp a parent for new buffer */
+	/* Make sp a parent for new buffer. */
 	de_set_vbn(up_e, new_vbn);
 
-	/* copy all the entries <= sp into the new buffer. */
+	/* Copy all the entries <= sp into the new buffer. */
 	de_t = hdr_first_de(hdr1);
 	to_copy = PtrOffset(de_t, sp);
 	hdr_insert_head(hdr2, de_t, to_copy);
 
-	/* remove all entries (sp including) from hdr1 */
+	/* Remove all entries (sp including) from hdr1. */
 	used = le32_to_cpu(hdr1->used) - to_copy - sp_size;
 	memmove(de_t, Add2Ptr(sp, sp_size), used - le32_to_cpu(hdr1->de_off));
 	hdr1->used = cpu_to_le32(used);
 
-	/* Insert new entry into left or right buffer (depending on sp <=> new_de) */
+	/*
+	 * Insert new entry into left or right buffer
+	 * (depending on sp <=> new_de).
+	 */
 	hdr_insert_de(indx,
 		      (*indx->cmp)(new_de + 1, le16_to_cpu(new_de->key_size),
 				   up_e + 1, le16_to_cpu(up_e->key_size),
@@ -1848,18 +1849,18 @@ indx_insert_into_buffer(struct ntfs_index *indx, struct ntfs_inode *ni,
 	put_indx_node(n2);
 
 	/*
-	 * we've finished splitting everybody, so we are ready to
+	 * We've finished splitting everybody, so we are ready to
 	 * insert the promoted entry into the parent.
 	 */
 	if (!level) {
-		/* Insert in root */
+		/* Insert in root. */
 		err = indx_insert_into_root(indx, ni, up_e, NULL, ctx, fnd);
 		if (err)
 			goto out;
 	} else {
 		/*
-		 * The target buffer's parent is another index buffer
-		 * TODO: Remove recursion
+		 * The target buffer's parent is another index buffer.
+		 * TODO: Remove recursion.
 		 */
 		err = indx_insert_into_buffer(indx, ni, root, up_e, ctx,
 					      level - 1, fnd);
@@ -1874,9 +1875,7 @@ out:
 }
 
 /*
- * indx_insert_entry
- *
- * inserts new entry into index
+ * indx_insert_entry - Insert new entry into index.
  */
 int indx_insert_entry(struct ntfs_index *indx, struct ntfs_inode *ni,
 		      const struct NTFS_DE *new_de, const void *ctx,
@@ -1904,7 +1903,10 @@ int indx_insert_entry(struct ntfs_index *indx, struct ntfs_inode *ni,
 	}
 
 	if (fnd_is_empty(fnd)) {
-		/* Find the spot the tree where we want to insert the new entry. */
+		/*
+		 * Find the spot the tree where we want to
+		 * insert the new entry.
+		 */
 		err = indx_find(indx, ni, root, new_de + 1,
 				le16_to_cpu(new_de->key_size), ctx, &diff, &e,
 				fnd);
@@ -1918,13 +1920,18 @@ int indx_insert_entry(struct ntfs_index *indx, struct ntfs_inode *ni,
 	}
 
 	if (!fnd->level) {
-		/* The root is also a leaf, so we'll insert the new entry into it. */
+		/*
+		 * The root is also a leaf, so we'll insert the
+		 * new entry into it.
+		 */
 		err = indx_insert_into_root(indx, ni, new_de, fnd->root_de, ctx,
 					    fnd);
 		if (err)
 			goto out;
 	} else {
-		/* found a leaf buffer, so we'll insert the new entry into it.*/
+		/*
+		 * Found a leaf buffer, so we'll insert the new entry into it.
+		 */
 		err = indx_insert_into_buffer(indx, ni, root, new_de, ctx,
 					      fnd->level - 1, fnd);
 		if (err)
@@ -1938,9 +1945,7 @@ out1:
 }
 
 /*
- * indx_find_buffer
- *
- * locates a buffer the tree.
+ * indx_find_buffer - Locate a buffer from the tree.
  */
 static struct indx_node *indx_find_buffer(struct ntfs_index *indx,
 					  struct ntfs_inode *ni,
@@ -1952,7 +1957,7 @@ static struct indx_node *indx_find_buffer(struct ntfs_index *indx,
 	struct indx_node *r;
 	const struct INDEX_HDR *hdr = n ? &n->index->ihdr : &root->ihdr;
 
-	/* Step 1: Scan one level */
+	/* Step 1: Scan one level. */
 	for (e = hdr_first_de(hdr);; e = hdr_next_de(hdr, e)) {
 		if (!e)
 			return ERR_PTR(-EINVAL);
@@ -1964,7 +1969,7 @@ static struct indx_node *indx_find_buffer(struct ntfs_index *indx,
 			break;
 	}
 
-	/* Step2: Do recursion */
+	/* Step2: Do recursion. */
 	e = Add2Ptr(hdr, le32_to_cpu(hdr->de_off));
 	for (;;) {
 		if (de_has_vcn_ex(e)) {
@@ -1987,9 +1992,7 @@ static struct indx_node *indx_find_buffer(struct ntfs_index *indx,
 }
 
 /*
- * indx_shrink
- *
- * deallocates unused tail indexes
+ * indx_shrink - Deallocate unused tail indexes.
  */
 static int indx_shrink(struct ntfs_index *indx, struct ntfs_inode *ni,
 		       size_t bit)
@@ -2066,7 +2069,7 @@ static int indx_free_children(struct ntfs_index *indx, struct ntfs_inode *ni,
 		return err;
 
 	hdr = &n->index->ihdr;
-	/* First, recurse into the children, if any.*/
+	/* First, recurse into the children, if any. */
 	if (hdr_has_subnode(hdr)) {
 		for (e = hdr_first_de(hdr); e; e = hdr_next_de(hdr, e)) {
 			indx_free_children(indx, ni, e, false);
@@ -2078,7 +2081,9 @@ static int indx_free_children(struct ntfs_index *indx, struct ntfs_inode *ni,
 	put_indx_node(n);
 
 	i = vbn >> indx->idx2vbn_bits;
-	/* We've gotten rid of the children; add this buffer to the free list. */
+	/*
+	 * We've gotten rid of the children; add this buffer to the free list.
+	 */
 	indx_mark_free(indx, ni, i);
 
 	if (!trim)
@@ -2086,8 +2091,8 @@ static int indx_free_children(struct ntfs_index *indx, struct ntfs_inode *ni,
 
 	/*
 	 * If there are no used indexes after current free index
-	 * then we can truncate allocation and bitmap
-	 * Use bitmap to estimate the case
+	 * then we can truncate allocation and bitmap.
+	 * Use bitmap to estimate the case.
 	 */
 	indx_shrink(indx, ni, i + 1);
 	return 0;
@@ -2096,9 +2101,9 @@ static int indx_free_children(struct ntfs_index *indx, struct ntfs_inode *ni,
 /*
  * indx_get_entry_to_replace
  *
- * finds a replacement entry for a deleted entry
- * always returns a node entry:
- * NTFS_IE_HAS_SUBNODES is set the flags and the size includes the sub_vcn
+ * Find a replacement entry for a deleted entry.
+ * Always returns a node entry:
+ * NTFS_IE_HAS_SUBNODES is set the flags and the size includes the sub_vcn.
  */
 static int indx_get_entry_to_replace(struct ntfs_index *indx,
 				     struct ntfs_inode *ni,
@@ -2115,7 +2120,7 @@ static int indx_get_entry_to_replace(struct ntfs_index *indx,
 
 	*de_to_replace = NULL;
 
-	/* Find first leaf entry down from de_next */
+	/* Find first leaf entry down from de_next. */
 	vbn = de_get_vbn(de_next);
 	for (;;) {
 		n = NULL;
@@ -2128,8 +2133,8 @@ static int indx_get_entry_to_replace(struct ntfs_index *indx,
 
 		if (!de_is_last(e)) {
 			/*
-			 * This buffer is non-empty, so its first entry could be used as the
-			 * replacement entry.
+			 * This buffer is non-empty, so its first entry
+			 * could be used as the replacement entry.
 			 */
 			level = fnd->level - 1;
 		}
@@ -2137,7 +2142,7 @@ static int indx_get_entry_to_replace(struct ntfs_index *indx,
 		if (!de_has_vcn(e))
 			break;
 
-		/* This buffer is a node. Continue to go down */
+		/* This buffer is a node. Continue to go down. */
 		vbn = de_get_vbn(e);
 	}
 
@@ -2158,15 +2163,16 @@ static int indx_get_entry_to_replace(struct ntfs_index *indx,
 
 	if (!de_has_vcn(re)) {
 		/*
-		 * The replacement entry we found doesn't have a sub_vcn. increase its size
-		 * to hold one.
+		 * The replacement entry we found doesn't have a sub_vcn.
+		 * increase its size to hold one.
 		 */
 		le16_add_cpu(&re->size, sizeof(u64));
 		re->flags |= NTFS_IE_HAS_SUBNODES;
 	} else {
 		/*
-		 * The replacement entry we found was a node entry, which means that all
-		 * its child buffers are empty. Return them to the free pool.
+		 * The replacement entry we found was a node entry, which
+		 * means that all its child buffers are empty. Return them
+		 * to the free pool.
 		 */
 		indx_free_children(indx, ni, te, true);
 	}
@@ -2191,9 +2197,7 @@ out:
 }
 
 /*
- * indx_delete_entry
- *
- * deletes an entry from the index.
+ * indx_delete_entry - Delete an entry from the index.
  */
 int indx_delete_entry(struct ntfs_index *indx, struct ntfs_inode *ni,
 		      const void *key, u32 key_len, const void *ctx)
@@ -2257,13 +2261,13 @@ int indx_delete_entry(struct ntfs_index *indx, struct ntfs_inode *ni,
 	e_size = le16_to_cpu(e->size);
 
 	if (!de_has_vcn_ex(e)) {
-		/* The entry to delete is a leaf, so we can just rip it out */
+		/* The entry to delete is a leaf, so we can just rip it out. */
 		hdr_delete_de(hdr, e);
 
 		if (!level) {
 			hdr->total = hdr->used;
 
-			/* Shrink resident root attribute */
+			/* Shrink resident root attribute. */
 			mi_resize_attr(mi, attr, 0 - e_size);
 			goto out;
 		}
@@ -2306,9 +2310,10 @@ int indx_delete_entry(struct ntfs_index *indx, struct ntfs_inode *ni,
 		} else {
 			/*
 			 * There is no replacement for the current entry.
-			 * This means that the subtree rooted at its node is empty,
-			 * and can be deleted, which turn means that the node can
-			 * just inherit the deleted entry sub_vcn
+			 * This means that the subtree rooted at its node
+			 * is empty, and can be deleted, which turn means
+			 * that the node can just inherit the deleted
+			 * entry sub_vcn.
 			 */
 			indx_free_children(indx, ni, next, true);
 
@@ -2319,17 +2324,17 @@ int indx_delete_entry(struct ntfs_index *indx, struct ntfs_inode *ni,
 			} else {
 				hdr->total = hdr->used;
 
-				/* Shrink resident root attribute */
+				/* Shrink resident root attribute. */
 				mi_resize_attr(mi, attr, 0 - e_size);
 			}
 		}
 	}
 
-	/* Delete a branch of tree */
+	/* Delete a branch of tree. */
 	if (!fnd2 || !fnd2->level)
 		goto out;
 
-	/* Reinit root 'cause it can be changed */
+	/* Reinit root 'cause it can be changed. */
 	root = indx_get_root(indx, ni, &attr, &mi);
 	if (!root) {
 		err = -EINVAL;
@@ -2343,7 +2348,7 @@ int indx_delete_entry(struct ntfs_index *indx, struct ntfs_inode *ni,
 
 	hdr = level ? &fnd->nodes[level - 1]->index->ihdr : &root->ihdr;
 
-	/* Scan current level */
+	/* Scan current level. */
 	for (e = hdr_first_de(hdr);; e = hdr_next_de(hdr, e)) {
 		if (!e) {
 			err = -EINVAL;
@@ -2360,7 +2365,7 @@ int indx_delete_entry(struct ntfs_index *indx, struct ntfs_inode *ni,
 	}
 
 	if (!e) {
-		/* Do slow search from root */
+		/* Do slow search from root. */
 		struct indx_node *in;
 
 		fnd_clear(fnd);
@@ -2375,7 +2380,7 @@ int indx_delete_entry(struct ntfs_index *indx, struct ntfs_inode *ni,
 			fnd_push(fnd, in, NULL);
 	}
 
-	/* Merge fnd2 -> fnd */
+	/* Merge fnd2 -> fnd. */
 	for (level = 0; level < fnd2->level; level++) {
 		fnd_push(fnd, fnd2->nodes[level], fnd2->de[level]);
 		fnd2->nodes[level] = NULL;
@@ -2421,8 +2426,8 @@ int indx_delete_entry(struct ntfs_index *indx, struct ntfs_inode *ni,
 
 		if (sub_vbn != de_get_vbn_le(e)) {
 			/*
-			 * Didn't find the parent entry, although this buffer is the parent trail.
-			 * Something is corrupt.
+			 * Didn't find the parent entry, although this buffer
+			 * is the parent trail. Something is corrupt.
 			 */
 			err = -EINVAL;
 			goto out;
@@ -2430,11 +2435,11 @@ int indx_delete_entry(struct ntfs_index *indx, struct ntfs_inode *ni,
 
 		if (de_is_last(e)) {
 			/*
-			 * Since we can't remove the end entry, we'll remove its
-			 * predecessor instead. This means we have to transfer the
-			 * predecessor's sub_vcn to the end entry.
-			 * Note: that this index block is not empty, so the
-			 * predecessor must exist
+			 * Since we can't remove the end entry, we'll remove
+			 * its predecessor instead. This means we have to
+			 * transfer the predecessor's sub_vcn to the end entry.
+			 * Note: This index block is not empty, so the
+			 * predecessor must exist.
 			 */
 			if (!prev) {
 				err = -EINVAL;
@@ -2452,9 +2457,9 @@ int indx_delete_entry(struct ntfs_index *indx, struct ntfs_inode *ni,
 		}
 
 		/*
-		 * Copy the current entry into a temporary buffer (stripping off its
-		 * down-pointer, if any) and delete it from the current buffer or root,
-		 * as appropriate.
+		 * Copy the current entry into a temporary buffer (stripping
+		 * off its down-pointer, if any) and delete it from the current
+		 * buffer or root, as appropriate.
 		 */
 		e_size = le16_to_cpu(e->size);
 		me = kmemdup(e, e_size, GFP_NOFS);
@@ -2474,14 +2479,14 @@ int indx_delete_entry(struct ntfs_index *indx, struct ntfs_inode *ni,
 			level = 0;
 			hdr->total = hdr->used;
 
-			/* Shrink resident root attribute */
+			/* Shrink resident root attribute. */
 			mi_resize_attr(mi, attr, 0 - e_size);
 		} else {
 			indx_write(indx, ni, n2d, 0);
 			level = level2;
 		}
 
-		/* Mark unused buffers as free */
+		/* Mark unused buffers as free. */
 		trim_bit = -1;
 		for (; level < fnd->level; level++) {
 			ib = fnd->nodes[level]->index;
@@ -2512,8 +2517,8 @@ int indx_delete_entry(struct ntfs_index *indx, struct ntfs_inode *ni,
 	} else {
 		/*
 		 * This tree needs to be collapsed down to an empty root.
-		 * Recreate the index root as an empty leaf and free all the bits the
-		 * index allocation bitmap.
+		 * Recreate the index root as an empty leaf and free all
+		 * the bits the index allocation bitmap.
 		 */
 		fnd_clear(fnd);
 		fnd_clear(fnd2);
@@ -2548,7 +2553,7 @@ int indx_delete_entry(struct ntfs_index *indx, struct ntfs_inode *ni,
 			goto out;
 		}
 
-		/* Fill first entry */
+		/* Fill first entry. */
 		e = (struct NTFS_DE *)(root + 1);
 		e->ref.low = 0;
 		e->ref.high = 0;
@@ -2601,7 +2606,7 @@ int indx_update_dup(struct ntfs_inode *ni, struct ntfs_sb_info *sbi,
 		goto out;
 	}
 
-	/* Find entry in directory */
+	/* Find entry in directory. */
 	err = indx_find(indx, ni, root, fname, fname_full_size(fname), sbi,
 			&diff, &e, fnd);
 	if (err)
@@ -2620,7 +2625,7 @@ int indx_update_dup(struct ntfs_inode *ni, struct ntfs_sb_info *sbi,
 	e_fname = (struct ATTR_FILE_NAME *)(e + 1);
 
 	if (!memcmp(&e_fname->dup, dup, sizeof(*dup))) {
-		/* nothing to update in index! Try to avoid this call */
+		/* Nothing to update in index! Try to avoid this call. */
 		goto out;
 	}