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, 25 insertions, 35 deletions

diff --git a/fs/ntfs3/record.c b/fs/ntfs3/record.c
index dec83ac815c7..d48a5e6c5045 100644
--- a/fs/ntfs3/record.c
+++ b/fs/ntfs3/record.c
@@ -18,15 +18,13 @@ static inline int compare_attr(const struct ATTRIB *left, enum ATTR_TYPE type,
 			       const __le16 *name, u8 name_len,
 			       const u16 *upcase)
 {
-	/* First, compare the type codes: */
+	/* First, compare the type codes. */
 	int diff = le32_to_cpu(left->type) - le32_to_cpu(type);
 
 	if (diff)
 		return diff;
 
-	/*
-	 * They have the same type code, so we have to compare the names.
-	 */
+	/* They have the same type code, so we have to compare the names. */
 	return ntfs_cmp_names(attr_name(left), left->name_len, name, name_len,
 			      upcase, true);
 }
@@ -34,7 +32,7 @@ static inline int compare_attr(const struct ATTRIB *left, enum ATTR_TYPE type,
 /*
  * mi_new_attt_id
  *
- * returns unused attribute id that is less than mrec->next_attr_id
+ * Return: Unused attribute id that is less than mrec->next_attr_id.
  */
 static __le16 mi_new_attt_id(struct mft_inode *mi)
 {
@@ -50,7 +48,7 @@ static __le16 mi_new_attt_id(struct mft_inode *mi)
 		return id;
 	}
 
-	/* One record can store up to 1024/24 ~= 42 attributes */
+	/* One record can store up to 1024/24 ~= 42 attributes. */
 	free_id = 0;
 	max_id = 0;
 
@@ -115,9 +113,7 @@ int mi_init(struct mft_inode *mi, struct ntfs_sb_info *sbi, CLST rno)
 }
 
 /*
- * mi_read
- *
- * reads MFT data
+ * mi_read - Read MFT data.
  */
 int mi_read(struct mft_inode *mi, bool is_mft)
 {
@@ -178,7 +174,7 @@ int mi_read(struct mft_inode *mi, bool is_mft)
 		goto out;
 
 ok:
-	/* check field 'total' only here */
+	/* Check field 'total' only here. */
 	if (le32_to_cpu(rec->total) != bpr) {
 		err = -EINVAL;
 		goto out;
@@ -210,13 +206,13 @@ struct ATTRIB *mi_enum_attr(struct mft_inode *mi, struct ATTRIB *attr)
 			return NULL;
 		}
 
-		/* Skip non-resident records */
+		/* Skip non-resident records. */
 		if (!is_rec_inuse(rec))
 			return NULL;
 
 		attr = Add2Ptr(rec, off);
 	} else {
-		/* Check if input attr inside record */
+		/* Check if input attr inside record. */
 		off = PtrOffset(rec, attr);
 		if (off >= used)
 			return NULL;
@@ -233,27 +229,27 @@ struct ATTRIB *mi_enum_attr(struct mft_inode *mi, struct ATTRIB *attr)
 
 	asize = le32_to_cpu(attr->size);
 
-	/* Can we use the first field (attr->type) */
+	/* Can we use the first field (attr->type). */
 	if (off + 8 > used) {
 		static_assert(ALIGN(sizeof(enum ATTR_TYPE), 8) == 8);
 		return NULL;
 	}
 
 	if (attr->type == ATTR_END) {
-		/* end of enumeration */
+		/* End of enumeration. */
 		return NULL;
 	}
 
-	/* 0x100 is last known attribute for now*/
+	/* 0x100 is last known attribute for now. */
 	t32 = le32_to_cpu(attr->type);
 	if ((t32 & 0xf) || (t32 > 0x100))
 		return NULL;
 
-	/* Check boundary */
+	/* Check boundary. */
 	if (off + asize > used)
 		return NULL;
 
-	/* Check size of attribute */
+	/* Check size of attribute. */
 	if (!attr->non_res) {
 		if (asize < SIZEOF_RESIDENT)
 			return NULL;
@@ -270,7 +266,7 @@ struct ATTRIB *mi_enum_attr(struct mft_inode *mi, struct ATTRIB *attr)
 		return attr;
 	}
 
-	/* Check some nonresident fields */
+	/* Check some nonresident fields. */
 	if (attr->name_len &&
 	    le16_to_cpu(attr->name_off) + sizeof(short) * attr->name_len >
 		    le16_to_cpu(attr->nres.run_off)) {
@@ -290,9 +286,7 @@ struct ATTRIB *mi_enum_attr(struct mft_inode *mi, struct ATTRIB *attr)
 }
 
 /*
- * mi_find_attr
- *
- * finds the attribute by type and name and id
+ * mi_find_attr - Find the attribute by type and name and id.
  */
 struct ATTRIB *mi_find_attr(struct mft_inode *mi, struct ATTRIB *attr,
 			    enum ATTR_TYPE type, const __le16 *name,
@@ -372,7 +366,7 @@ int mi_format_new(struct mft_inode *mi, struct ntfs_sb_info *sbi, CLST rno,
 	} else if (mi_read(mi, is_mft)) {
 		;
 	} else if (rec->rhdr.sign == NTFS_FILE_SIGNATURE) {
-		/* Record is reused. Update its sequence number */
+		/* Record is reused. Update its sequence number. */
 		seq = le16_to_cpu(rec->seq) + 1;
 		if (!seq)
 			seq = 1;
@@ -404,9 +398,7 @@ int mi_format_new(struct mft_inode *mi, struct ntfs_sb_info *sbi, CLST rno,
 }
 
 /*
- * mi_mark_free
- *
- * marks record as unused and marks it as free in bitmap
+ * mi_mark_free - Mark record as unused and marks it as free in bitmap.
  */
 void mi_mark_free(struct mft_inode *mi)
 {
@@ -428,10 +420,9 @@ void mi_mark_free(struct mft_inode *mi)
 }
 
 /*
- * mi_insert_attr
+ * mi_insert_attr - Reserve space for new attribute.
  *
- * reserves space for new attribute
- * returns not full constructed attribute or NULL if not possible to create
+ * Return: Not full constructed attribute or NULL if not possible to create.
  */
 struct ATTRIB *mi_insert_attr(struct mft_inode *mi, enum ATTR_TYPE type,
 			      const __le16 *name, u8 name_len, u32 asize,
@@ -468,7 +459,7 @@ struct ATTRIB *mi_insert_attr(struct mft_inode *mi, enum ATTR_TYPE type,
 	}
 
 	if (!attr) {
-		tail = 8; /* not used, just to suppress warning */
+		tail = 8; /* Not used, just to suppress warning. */
 		attr = Add2Ptr(rec, used - 8);
 	} else {
 		tail = used - PtrOffset(rec, attr);
@@ -494,10 +485,9 @@ struct ATTRIB *mi_insert_attr(struct mft_inode *mi, enum ATTR_TYPE type,
 }
 
 /*
- * mi_remove_attr
+ * mi_remove_attr - Remove the attribute from record.
  *
- * removes the attribute from record
- * NOTE: The source attr will point to next attribute
+ * NOTE: The source attr will point to next attribute.
  */
 bool mi_remove_attr(struct mft_inode *mi, struct ATTRIB *attr)
 {
@@ -543,7 +533,7 @@ bool mi_resize_attr(struct mft_inode *mi, struct ATTRIB *attr, int bytes)
 		if (used + dsize > total)
 			return false;
 		nsize = asize + dsize;
-		// move tail
+		/* Move tail */
 		memmove(next + dsize, next, tail);
 		memset(next, 0, dsize);
 		used += dsize;
@@ -585,10 +575,10 @@ int mi_pack_runs(struct mft_inode *mi, struct ATTRIB *attr,
 	u32 tail = used - aoff - asize;
 	u32 dsize = sbi->record_size - used;
 
-	/* Make a maximum gap in current record */
+	/* Make a maximum gap in current record. */
 	memmove(next + dsize, next, tail);
 
-	/* Pack as much as possible */
+	/* Pack as much as possible. */
 	err = run_pack(run, svcn, len, Add2Ptr(attr, run_off), run_size + dsize,
 		       &plen);
 	if (err < 0) {