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: NKari Argillander <kari.argillander@gmail.com>
Signed-off-by: NKonstantin Komarov <almaz.alexandrovich@paragon-software.com>

fs/ntfs3/attrlist.c

@@ -14,7 +14,11 @@
 #include "ntfs.h"
 #include "ntfs_fs.h"
 
-/* Returns true if le is valid */
+/*
+ * al_is_valid_le
+ *
+ * Return: True if @le is valid.
+ */
 static inline bool al_is_valid_le(const struct ntfs_inode *ni,
 				  struct ATTR_LIST_ENTRY *le)
 {
@@ -101,8 +105,9 @@ int ntfs_load_attr_list(struct ntfs_inode *ni, struct ATTRIB *attr)
 /*
  * al_enumerate
  *
- * Returns the next list 'le'
- * if 'le' is NULL then returns the first 'le'
+ * Return:
+ * * The next list le.
+ * * If @le is NULL then return the first le.
  */
 struct ATTR_LIST_ENTRY *al_enumerate(struct ntfs_inode *ni,
 				     struct ATTR_LIST_ENTRY *le)
@@ -115,22 +120,22 @@ struct ATTR_LIST_ENTRY *al_enumerate(struct ntfs_inode *ni,
 	} else {
 		sz = le16_to_cpu(le->size);
 		if (sz < sizeof(struct ATTR_LIST_ENTRY)) {
-			/* Impossible 'cause we should not return such 'le' */
+			/* Impossible 'cause we should not return such le. */
 			return NULL;
 		}
 		le = Add2Ptr(le, sz);
 	}
 
-	/* Check boundary */
+	/* Check boundary. */
 	off = PtrOffset(ni->attr_list.le, le);
 	if (off + sizeof(struct ATTR_LIST_ENTRY) > ni->attr_list.size) {
-		// The regular end of list
+		/* The regular end of list. */
 		return NULL;
 	}
 
 	sz = le16_to_cpu(le->size);
 
-	/* Check 'le' for errors */
+	/* Check le for errors. */
 	if (sz < sizeof(struct ATTR_LIST_ENTRY) ||
 	    off + sz > ni->attr_list.size ||
 	    sz < le->name_off + le->name_len * sizeof(short)) {
@@ -143,8 +148,9 @@ struct ATTR_LIST_ENTRY *al_enumerate(struct ntfs_inode *ni,
 /*
  * al_find_le
  *
- * finds the first 'le' in the list which matches type, name and vcn
- * Returns NULL if not found
+ * Find the first le in the list which matches type, name and VCN.
+ *
+ * Return: NULL if not found.
  */
 struct ATTR_LIST_ENTRY *al_find_le(struct ntfs_inode *ni,
 				   struct ATTR_LIST_ENTRY *le,
@@ -159,8 +165,9 @@ struct ATTR_LIST_ENTRY *al_find_le(struct ntfs_inode *ni,
 /*
  * al_find_ex
  *
- * finds the first 'le' in the list which matches type, name and vcn
- * Returns NULL if not found
+ * Find the first le in the list which matches type, name and VCN.
+ *
+ * Return: NULL if not found.
  */
 struct ATTR_LIST_ENTRY *al_find_ex(struct ntfs_inode *ni,
 				   struct ATTR_LIST_ENTRY *le,
@@ -174,7 +181,7 @@ struct ATTR_LIST_ENTRY *al_find_ex(struct ntfs_inode *ni,
 		u64 le_vcn;
 		int diff = le32_to_cpu(le->type) - type_in;
 
-		/* List entries are sorted by type, name and vcn */
+		/* List entries are sorted by type, name and VCN. */
 		if (diff < 0)
 			continue;
 
@@ -187,7 +194,7 @@ struct ATTR_LIST_ENTRY *al_find_ex(struct ntfs_inode *ni,
 		le_vcn = le64_to_cpu(le->vcn);
 		if (!le_vcn) {
 			/*
-			 * compare entry names only for entry with vcn == 0
+			 * Compare entry names only for entry with vcn == 0.
 			 */
 			diff = ntfs_cmp_names(le_name(le), name_len, name,
 					      name_len, ni->mi.sbi->upcase,
@@ -217,7 +224,7 @@ struct ATTR_LIST_ENTRY *al_find_ex(struct ntfs_inode *ni,
 /*
  * al_find_le_to_insert
  *
- * finds the first list entry which matches type, name and vcn
+ * Find the first list entry which matches type, name and VCN.
  */
 static struct ATTR_LIST_ENTRY *al_find_le_to_insert(struct ntfs_inode *ni,
 						    enum ATTR_TYPE type,
@@ -227,7 +234,7 @@ static struct ATTR_LIST_ENTRY *al_find_le_to_insert(struct ntfs_inode *ni,
 	struct ATTR_LIST_ENTRY *le = NULL, *prev;
 	u32 type_in = le32_to_cpu(type);
 
-	/* List entries are sorted by type, name, vcn */
+	/* List entries are sorted by type, name and VCN. */
 	while ((le = al_enumerate(ni, prev = le))) {
 		int diff = le32_to_cpu(le->type) - type_in;
 
@@ -239,7 +246,7 @@ static struct ATTR_LIST_ENTRY *al_find_le_to_insert(struct ntfs_inode *ni,
 
 		if (!le->vcn) {
 			/*
-			 * compare entry names only for entry with vcn == 0
+			 * Compare entry names only for entry with vcn == 0.
 			 */
 			diff = ntfs_cmp_names(le_name(le), le->name_len, name,
 					      name_len, ni->mi.sbi->upcase,
@@ -261,7 +268,7 @@ static struct ATTR_LIST_ENTRY *al_find_le_to_insert(struct ntfs_inode *ni,
 /*
  * al_add_le
  *
- * adds an "attribute list entry" to the list.
+ * Add an "attribute list entry" to the list.
  */
 int al_add_le(struct ntfs_inode *ni, enum ATTR_TYPE type, const __le16 *name,
 	      u8 name_len, CLST svcn, __le16 id, const struct MFT_REF *ref,
@@ -335,9 +342,7 @@ int al_add_le(struct ntfs_inode *ni, enum ATTR_TYPE type, const __le16 *name,
 }
 
 /*
- * al_remove_le
- *
- * removes 'le' from attribute list
+ * al_remove_le - Remove @le from attribute list.
  */
 bool al_remove_le(struct ntfs_inode *ni, struct ATTR_LIST_ENTRY *le)
 {
@@ -361,9 +366,7 @@ bool al_remove_le(struct ntfs_inode *ni, struct ATTR_LIST_ENTRY *le)
 }
 
 /*
- * al_delete_le
- *
- * deletes from the list the first 'le' which matches its parameters.
+ * al_delete_le - Delete first le from the list which matches its parameters.
  */
 bool al_delete_le(struct ntfs_inode *ni, enum ATTR_TYPE type, CLST vcn,
 		  const __le16 *name, size_t name_len,
@@ -374,7 +377,7 @@ bool al_delete_le(struct ntfs_inode *ni, enum ATTR_TYPE type, CLST vcn,
 	size_t off;
 	typeof(ni->attr_list) *al = &ni->attr_list;
 
-	/* Scan forward to the first 'le' that matches the input */
+	/* Scan forward to the first le that matches the input. */
 	le = al_find_ex(ni, NULL, type, name, name_len, &vcn);
 	if (!le)
 		return false;
@@ -405,9 +408,9 @@ bool al_delete_le(struct ntfs_inode *ni, enum ATTR_TYPE type, CLST vcn,
 		goto next;
 	}
 
-	/* Save on stack the size of 'le' */
+	/* Save on stack the size of 'le'. */
 	size = le16_to_cpu(le->size);
-	/* Delete 'le'. */
+	/* Delete the le. */
 	memmove(le, Add2Ptr(le, size), al->size - (off + size));
 
 	al->size -= size;
@@ -416,9 +419,6 @@ bool al_delete_le(struct ntfs_inode *ni, enum ATTR_TYPE type, CLST vcn,
 	return true;
 }
 
-/*
- * al_update
- */
 int al_update(struct ntfs_inode *ni)
 {
 	int err;
@@ -429,8 +429,8 @@ int al_update(struct ntfs_inode *ni)
 		return 0;
 
 	/*
-	 * attribute list increased on demand in al_add_le
-	 * attribute list decreased here
+	 * Attribute list increased on demand in al_add_le.
+	 * Attribute list decreased here.
 	 */
 	err = attr_set_size(ni, ATTR_LIST, NULL, 0, &al->run, al->size, NULL,
 			    false, &attr);

fs/ntfs3/bitfunc.c

@@ -4,6 +4,7 @@
  * Copyright (C) 2019-2021 Paragon Software GmbH, All rights reserved.
  *
  */
+
 #include <linux/blkdev.h>
 #include <linux/buffer_head.h>
 #include <linux/fs.h>
@@ -32,7 +33,7 @@ static const u8 zero_mask[] = { 0xFF, 0xFE, 0xFC, 0xF8, 0xF0,
 /*
  * are_bits_clear
  *
- * Returns true if all bits [bit, bit+nbits) are zeros "0"
+ * Return: True if all bits [bit, bit+nbits) are zeros "0".
  */
 bool are_bits_clear(const ulong *lmap, size_t bit, size_t nbits)
 {
@@ -74,14 +75,13 @@ bool are_bits_clear(const ulong *lmap, size_t bit, size_t nbits)
 	if (pos && (*map & fill_mask[pos]))
 		return false;
 
-	// All bits are zero
 	return true;
 }
 
 /*
  * are_bits_set
  *
- * Returns true if all bits [bit, bit+nbits) are ones "1"
+ * Return: True if all bits [bit, bit+nbits) are ones "1".
  */
 bool are_bits_set(const ulong *lmap, size_t bit, size_t nbits)
 {
@@ -130,6 +130,5 @@ bool are_bits_set(const ulong *lmap, size_t bit, size_t nbits)
 			return false;
 	}
 
-	// All bits are ones
 	return true;
 }

fs/ntfs3/debug.h

@@ -3,7 +3,8 @@
  *
  * Copyright (C) 2019-2021 Paragon Software GmbH, All rights reserved.
  *
- * useful functions for debugging
+ * Useful functions for debugging.
+ *
  */
 
 // clang-format off
@@ -33,7 +34,7 @@ void ntfs_inode_printk(struct inode *inode, const char *fmt, ...)
 #endif
 
 /*
- * Logging macros ( thanks Joe Perches <joe@perches.com> for implementation )
+ * Logging macros. Thanks Joe Perches <joe@perches.com> for implementation.
  */
 
 #define ntfs_err(sb, fmt, ...)  ntfs_printk(sb, KERN_ERR fmt, ##__VA_ARGS__)

fs/ntfs3/dir.c

@@ -3,9 +3,10 @@
  *
  * Copyright (C) 2019-2021 Paragon Software GmbH, All rights reserved.
  *
- *  directory handling functions for ntfs-based filesystems
+ *  Directory handling functions for NTFS-based filesystems.
  *
  */
+
 #include <linux/blkdev.h>
 #include <linux/buffer_head.h>
 #include <linux/fs.h>
@@ -16,9 +17,7 @@
 #include "ntfs.h"
 #include "ntfs_fs.h"
 
-/*
- * Convert little endian utf16 to nls string
- */
+/* Convert little endian UTF-16 to NLS string. */
 int ntfs_utf16_to_nls(struct ntfs_sb_info *sbi, const struct le_str *uni,
 		      u8 *buf, int buf_len)
 {
@@ -30,7 +29,7 @@ int ntfs_utf16_to_nls(struct ntfs_sb_info *sbi, const struct le_str *uni,
 	static_assert(sizeof(wchar_t) == sizeof(__le16));
 
 	if (!nls) {
-		/* utf16 -> utf8 */
+		/* UTF-16 -> UTF-8 */
 		ret = utf16s_to_utf8s((wchar_t *)uni->name, uni->len,
 				      UTF16_LITTLE_ENDIAN, buf, buf_len);
 		buf[ret] = '\0';
@@ -89,8 +88,9 @@ int ntfs_utf16_to_nls(struct ntfs_sb_info *sbi, const struct le_str *uni,
 // clang-format on
 
 /*
- * modified version of put_utf16 from fs/nls/nls_base.c
- * is sparse warnings free
+ * put_utf16 - Modified version of put_utf16 from fs/nls/nls_base.c
+ *
+ * Function is sparse warnings free.
  */
 static inline void put_utf16(wchar_t *s, unsigned int c,
 			     enum utf16_endian endian)
@@ -112,8 +112,10 @@ static inline void put_utf16(wchar_t *s, unsigned int c,
 }
 
 /*
- * modified version of 'utf8s_to_utf16s' allows to
- * detect -ENAMETOOLONG without writing out of expected maximum
+ * _utf8s_to_utf16s
+ *
+ * Modified version of 'utf8s_to_utf16s' allows to
+ * detect -ENAMETOOLONG without writing out of expected maximum.
  */
 static int _utf8s_to_utf16s(const u8 *s, int inlen, enum utf16_endian endian,
 			    wchar_t *pwcs, int maxout)
@@ -165,17 +167,18 @@ static int _utf8s_to_utf16s(const u8 *s, int inlen, enum utf16_endian endian,
 }
 
 /*
- * Convert input string to utf16
- *
- * name, name_len - input name
- * uni, max_ulen - destination memory
- * endian - endian of target utf16 string
+ * ntfs_nls_to_utf16 - Convert input string to UTF-16.
+ * @name:	Input name.
+ * @name_len:	Input name length.
+ * @uni:	Destination memory.
+ * @max_ulen:	Destination memory.
+ * @endian:	Endian of target UTF-16 string.
  *
  * This function is called:
- * - to create ntfs name
+ * - to create NTFS name
  * - to create symlink
  *
- * returns utf16 string length or error (if negative)
+ * Return: UTF-16 string length or error (if negative).
  */
 int ntfs_nls_to_utf16(struct ntfs_sb_info *sbi, const u8 *name, u32 name_len,
 		      struct cpu_str *uni, u32 max_ulen,
@@ -230,7 +233,9 @@ int ntfs_nls_to_utf16(struct ntfs_sb_info *sbi, const u8 *name, u32 name_len,
 	return ret;
 }
 
-/* helper function */
+/*
+ * dir_search_u - Helper function.
+ */
 struct inode *dir_search_u(struct inode *dir, const struct cpu_str *uni,
 			   struct ntfs_fnd *fnd)
 {
@@ -295,7 +300,7 @@ static inline int ntfs_filldir(struct ntfs_sb_info *sbi, struct ntfs_inode *ni,
 	if (ino == MFT_REC_ROOT)
 		return 0;
 
-	/* Skip meta files ( unless option to show metafiles is set ) */
+	/* Skip meta files. Unless option to show metafiles is set. */
 	if (!sbi->options.showmeta && ntfs_is_meta_file(sbi, ino))
 		return 0;
 
@@ -316,9 +321,7 @@ static inline int ntfs_filldir(struct ntfs_sb_info *sbi, struct ntfs_inode *ni,
 }
 
 /*
- * ntfs_read_hdr
- *
- * helper function 'ntfs_readdir'
+ * ntfs_read_hdr - Helper function for ntfs_readdir().
  */
 static int ntfs_read_hdr(struct ntfs_sb_info *sbi, struct ntfs_inode *ni,
 			 const struct INDEX_HDR *hdr, u64 vbo, u64 pos,
@@ -342,7 +345,7 @@ static int ntfs_read_hdr(struct ntfs_sb_info *sbi, struct ntfs_inode *ni,
 		if (de_is_last(e))
 			return 0;
 
-		/* Skip already enumerated*/
+		/* Skip already enumerated. */
 		if (vbo + off < pos)
 			continue;
 
@@ -359,11 +362,11 @@ static int ntfs_read_hdr(struct ntfs_sb_info *sbi, struct ntfs_inode *ni,
 }
 
 /*
- * file_operations::iterate_shared
+ * ntfs_readdir - file_operations::iterate_shared
  *
  * Use non sorted enumeration.
  * We have an example of broken volume where sorted enumeration
- * counts each name twice
+ * counts each name twice.
  */
 static int ntfs_readdir(struct file *file, struct dir_context *ctx)
 {
@@ -382,7 +385,7 @@ static int ntfs_readdir(struct file *file, struct dir_context *ctx)
 	struct indx_node *node = NULL;
 	u8 index_bits = ni->dir.index_bits;
 
-	/* name is a buffer of PATH_MAX length */
+	/* Name is a buffer of PATH_MAX length. */
 	static_assert(NTFS_NAME_LEN * 4 < PATH_MAX);
 
 	eod = i_size + sbi->record_size;
@@ -393,16 +396,16 @@ static int ntfs_readdir(struct file *file, struct dir_context *ctx)
 	if (!dir_emit_dots(file, ctx))
 		return 0;
 
-	/* allocate PATH_MAX bytes */
+	/* Allocate PATH_MAX bytes. */
 	name = __getname();
 	if (!name)
 		return -ENOMEM;
 
 	if (!ni->mi_loaded && ni->attr_list.size) {
 		/*
-		 * directory inode is locked for read
-		 * load all subrecords to avoid 'write' access to 'ni' during
-		 * directory reading
+		 * Directory inode is locked for read.
+		 * Load all subrecords to avoid 'write' access to 'ni' during
+		 * directory reading.
 		 */
 		ni_lock(ni);
 		if (!ni->mi_loaded && ni->attr_list.size) {

fs/ntfs3/file.c

@@ -3,8 +3,10 @@
  *
  * Copyright (C) 2019-2021 Paragon Software GmbH, All rights reserved.
  *
- *  regular file handling primitives for ntfs-based filesystems
+ *  Regular file handling primitives for NTFS-based filesystems.
+ *
  */
+
 #include <linux/backing-dev.h>
 #include <linux/buffer_head.h>
 #include <linux/compat.h>
@@ -62,7 +64,7 @@ static long ntfs_ioctl(struct file *filp, u32 cmd, unsigned long arg)
 	case FITRIM:
 		return ntfs_ioctl_fitrim(sbi, arg);
 	}
-	return -ENOTTY; /* Inappropriate ioctl for device */
+	return -ENOTTY; /* Inappropriate ioctl for device. */
 }
 
 #ifdef CONFIG_COMPAT
@@ -74,7 +76,7 @@ static long ntfs_compat_ioctl(struct file *filp, u32 cmd, unsigned long arg)
 #endif
 
 /*
- * inode_operations::getattr
+ * ntfs_getattr - inode_operations::getattr
  */
 int ntfs_getattr(struct user_namespace *mnt_userns, const struct path *path,
 		 struct kstat *stat, u32 request_mask, u32 flags)
@@ -170,7 +172,7 @@ static int ntfs_extend_initialized_size(struct file *file,
 
 		zero_user_segment(page, zerofrom, PAGE_SIZE);
 
-		/* this function in any case puts page*/
+		/* This function in any case puts page. */
 		err = pagecache_write_end(file, mapping, pos, len, len, page,
 					  fsdata);
 		if (err < 0)
@@ -195,9 +197,7 @@ static int ntfs_extend_initialized_size(struct file *file,
 }
 
 /*
- * ntfs_zero_range
- *
- * Helper function for punch_hole.
+ * ntfs_zero_range - Helper function for punch_hole.
  * It zeroes a range [vbo, vbo_to)
  */
 static int ntfs_zero_range(struct inode *inode, u64 vbo, u64 vbo_to)
@@ -356,7 +356,7 @@ void ntfs_sparse_cluster(struct inode *inode, struct page *page0, CLST vcn,
 }
 
 /*
- * file_operations::mmap
+ * ntfs_file_mmap - file_operations::mmap
  */
 static int ntfs_file_mmap(struct file *file, struct vm_area_struct *vma)
 {
@@ -387,7 +387,7 @@ static int ntfs_file_mmap(struct file *file, struct vm_area_struct *vma)
 			       from + vma->vm_end - vma->vm_start);
 
 		if (is_sparsed(ni)) {
-			/* allocate clusters for rw map */
+			/* Allocate clusters for rw map. */
 			struct ntfs_sb_info *sbi = inode->i_sb->s_fs_info;
 			CLST lcn, len;
 			CLST vcn = from >> sbi->cluster_bits;
@@ -436,7 +436,7 @@ static int ntfs_extend(struct inode *inode, loff_t pos, size_t count,
 	if (end <= inode->i_size && !extend_init)
 		return 0;
 
-	/*mark rw ntfs as dirty. it will be cleared at umount*/
+	/* Mark rw ntfs as dirty. It will be cleared at umount. */
 	ntfs_set_state(ni->mi.sbi, NTFS_DIRTY_DIRTY);
 
 	if (end > inode->i_size) {
@@ -530,6 +530,8 @@ static int ntfs_truncate(struct inode *inode, loff_t new_size)
 }
 
 /*
+ * ntfs_fallocate
+ *
  * Preallocate space for a file. This implements ntfs's fallocate file
  * operation, which gets called from sys_fallocate system call. User
  * space requests 'len' bytes at 'vbo'. If FALLOC_FL_KEEP_SIZE is set
@@ -547,11 +549,11 @@ static long ntfs_fallocate(struct file *file, int mode, loff_t vbo, loff_t len)
 	loff_t i_size;
 	int err;
 
-	/* No support for dir */
+	/* No support for dir. */
 	if (!S_ISREG(inode->i_mode))
 		return -EOPNOTSUPP;
 
-	/* Return error if mode is not supported */
+	/* Return error if mode is not supported. */
 	if (mode & ~(FALLOC_FL_KEEP_SIZE | FALLOC_FL_PUNCH_HOLE |
 		     FALLOC_FL_COLLAPSE_RANGE)) {
 		ntfs_inode_warn(inode, "fallocate(0x%x) is not supported",
@@ -565,7 +567,7 @@ static long ntfs_fallocate(struct file *file, int mode, loff_t vbo, loff_t len)
 	i_size = inode->i_size;
 
 	if (WARN_ON(ni->ni_flags & NI_FLAG_COMPRESSED_MASK)) {
-		/* should never be here, see ntfs_file_open*/
+		/* Should never be here, see ntfs_file_open. */
 		err = -EOPNOTSUPP;
 		goto out;
 	}
@@ -646,7 +648,7 @@ static long ntfs_fallocate(struct file *file, int mode, loff_t vbo, loff_t len)
 
 		/*
 		 * Write data that will be shifted to preserve them
-		 * when discarding page cache below
+		 * when discarding page cache below.
 		 */
 		err = filemap_write_and_wait_range(inode->i_mapping, end,
 						   LLONG_MAX);
@@ -663,7 +665,7 @@ static long ntfs_fallocate(struct file *file, int mode, loff_t vbo, loff_t len)
 		ni_unlock(ni);
 	} else {
 		/*
-		 * normal file: allocate clusters, do not change 'valid' size
+		 * Normal file: Allocate clusters, do not change 'valid' size.
 		 */
 		err = ntfs_set_size(inode, max(end, i_size));
 		if (err)
@@ -677,10 +679,10 @@ static long ntfs_fallocate(struct file *file, int mode, loff_t vbo, loff_t len)
 			bool new;
 
 			/*
-			 * allocate but not zero new clusters (see below comments)
-			 * this breaks security (one can read unused on-disk areas)
-			 * zeroing these clusters may be too long
-			 * may be we should check here for root rights?
+			 * Allocate but do not zero new clusters. (see below comments)
+			 * This breaks security: One can read unused on-disk areas.
+			 * Zeroing these clusters may be too long.
+			 * Maybe we should check here for root rights?
 			 */
 			for (; vcn < cend; vcn += clen) {
 				err = attr_data_get_block(ni, vcn, cend - vcn,
@@ -691,15 +693,15 @@ static long ntfs_fallocate(struct file *file, int mode, loff_t vbo, loff_t len)
 					continue;
 
 				/*
-				 * Unwritten area
-				 * NTFS is not able to store several unwritten areas
-				 * Activate 'ntfs_sparse_cluster' to zero new allocated clusters
+				 * Unwritten area.
+				 * NTFS is not able to store several unwritten areas.
+				 * Activate 'ntfs_sparse_cluster' to zero new allocated clusters.
 				 *
 				 * Dangerous in case:
 				 * 1G of sparsed clusters + 1 cluster of data =>
 				 * valid_size == 1G + 1 cluster
 				 * fallocate(1G) will zero 1G and this can be very long
-				 * xfstest 016/086 will fail without 'ntfs_sparse_cluster'
+				 * xfstest 016/086 will fail without 'ntfs_sparse_cluster'.
 				 */
 				ntfs_sparse_cluster(inode, NULL, vcn,
 						    min(vcn_v - vcn, clen));
@@ -708,7 +710,7 @@ static long ntfs_fallocate(struct file *file, int mode, loff_t vbo, loff_t len)
 
 		if (mode & FALLOC_FL_KEEP_SIZE) {
 			ni_lock(ni);
-			/*true - keep preallocated*/
+			/* True - Keep preallocated. */
 			err = attr_set_size(ni, ATTR_DATA, NULL, 0,
 					    &ni->file.run, i_size, &ni->i_valid,
 					    true, NULL);
@@ -730,7 +732,7 @@ static long ntfs_fallocate(struct file *file, int mode, loff_t vbo, loff_t len)
 }
 
 /*
- * inode_operations::setattr
+ * ntfs3_setattr - inode_operations::setattr
  */
 int ntfs3_setattr(struct user_namespace *mnt_userns, struct dentry *dentry,
 		  struct iattr *attr)
@@ -744,9 +746,9 @@ int ntfs3_setattr(struct user_namespace *mnt_userns, struct dentry *dentry,
 	int err;
 
 	if (sbi->options.no_acs_rules) {
-		/* "no access rules" - force any changes of time etc. */
+		/* "No access rules" - Force any changes of time etc. */
 		attr->ia_valid |= ATTR_FORCE;
-		/* and disable for editing some attributes */
+		/* and disable for editing some attributes. */
 		attr->ia_valid &= ~(ATTR_UID | ATTR_GID | ATTR_MODE);
 		ia_valid = attr->ia_valid;
 	}
@@ -759,7 +761,7 @@ int ntfs3_setattr(struct user_namespace *mnt_userns, struct dentry *dentry,
 		loff_t oldsize = inode->i_size;
 
 		if (WARN_ON(ni->ni_flags & NI_FLAG_COMPRESSED_MASK)) {
-			/* should never be here, see ntfs_file_open*/
+			/* Should never be here, see ntfs_file_open(). */
 			err = -EOPNOTSUPP;
 			goto out;
 		}
@@ -783,7 +785,7 @@ int ntfs3_setattr(struct user_namespace *mnt_userns, struct dentry *dentry,
 		if (err)
 			goto out;
 
-		/* linux 'w' -> windows 'ro' */
+		/* Linux 'w' -> Windows 'ro'. */
 		if (0222 & inode->i_mode)
 			ni->std_fa &= ~FILE_ATTRIBUTE_READONLY;
 		else
@@ -834,7 +836,11 @@ static ssize_t ntfs_file_read_iter(struct kiocb *iocb, struct iov_iter *iter)
 	return err;
 }
 
-/* returns array of locked pages */
+/*
+ * ntfs_get_frame_pages
+ *
+ * Return: Array of locked pages.
+ */
 static int ntfs_get_frame_pages(struct address_space *mapping, pgoff_t index,
 				struct page **pages, u32 pages_per_frame,
 				bool *frame_uptodate)
@@ -867,7 +873,9 @@ static int ntfs_get_frame_pages(struct address_space *mapping, pgoff_t index,
 	return 0;
 }
 
-/*helper for ntfs_file_write_iter (compressed files)*/
+/*
+ * ntfs_compress_write - Helper for ntfs_file_write_iter() (compressed files).
+ */
 static ssize_t ntfs_compress_write(struct kiocb *iocb, struct iov_iter *from)
 {
 	int err;
@@ -913,7 +921,7 @@ static ssize_t ntfs_compress_write(struct kiocb *iocb, struct iov_iter *from)
 	if (err)
 		goto out;
 
-	/* zero range [valid : pos) */
+	/* Zero range [valid : pos). */
 	while (valid < pos) {
 		CLST lcn, clen;
 
@@ -932,7 +940,7 @@ static ssize_t ntfs_compress_write(struct kiocb *iocb, struct iov_iter *from)
 			continue;
 		}
 
-		/* Load full frame */
+		/* Load full frame. */
 		err = ntfs_get_frame_pages(mapping, frame_vbo >> PAGE_SHIFT,
 					   pages, pages_per_frame,
 					   &frame_uptodate);
@@ -978,7 +986,7 @@ static ssize_t ntfs_compress_write(struct kiocb *iocb, struct iov_iter *from)
 		ni->i_valid = valid = frame_vbo + frame_size;
 	}
 
-	/* copy user data [pos : pos + count) */
+	/* Copy user data [pos : pos + count). */
 	while (count) {
 		size_t copied, bytes;
 
@@ -996,7 +1004,7 @@ static ssize_t ntfs_compress_write(struct kiocb *iocb, struct iov_iter *from)
 			goto out;
 		}
 
-		/* Load full frame */
+		/* Load full frame. */
 		err = ntfs_get_frame_pages(mapping, index, pages,
 					   pages_per_frame, &frame_uptodate);
 		if (err)
@@ -1025,7 +1033,7 @@ static ssize_t ntfs_compress_write(struct kiocb *iocb, struct iov_iter *from)
 		ip = off >> PAGE_SHIFT;
 		off = offset_in_page(pos);
 
-		/* copy user data to pages */
+		/* Copy user data to pages. */
 		for (;;) {
 			size_t cp, tail = PAGE_SIZE - off;
 
@@ -1091,7 +1099,7 @@ static ssize_t ntfs_compress_write(struct kiocb *iocb, struct iov_iter *from)
 }
 
 /*
- * file_operations::write_iter
+ * ntfs_file_write_iter - file_operations::write_iter
  */
 static ssize_t ntfs_file_write_iter(struct kiocb *iocb, struct iov_iter *from)
 {
@@ -1127,7 +1135,7 @@ static ssize_t ntfs_file_write_iter(struct kiocb *iocb, struct iov_iter *from)
 		goto out;
 
 	if (WARN_ON(ni->ni_flags & NI_FLAG_COMPRESSED_MASK)) {
-		/* should never be here, see ntfs_file_open*/
+		/* Should never be here, see ntfs_file_open() */
 		ret = -EOPNOTSUPP;
 		goto out;
 	}
@@ -1149,7 +1157,7 @@ static ssize_t ntfs_file_write_iter(struct kiocb *iocb, struct iov_iter *from)
 }
 
 /*
- * file_operations::open
+ * ntfs_file_open - file_operations::open
  */
 int ntfs_file_open(struct inode *inode, struct file *file)
 {
@@ -1160,7 +1168,7 @@ int ntfs_file_open(struct inode *inode, struct file *file)
 		return -EOPNOTSUPP;
 	}
 
-	/* Decompress "external compressed" file if opened for rw */
+	/* Decompress "external compressed" file if opened for rw. */
 	if ((ni->ni_flags & NI_FLAG_COMPRESSED_MASK) &&
 	    (file->f_flags & (O_WRONLY | O_RDWR | O_TRUNC))) {
 #ifdef CONFIG_NTFS3_LZX_XPRESS
@@ -1180,7 +1188,7 @@ int ntfs_file_open(struct inode *inode, struct file *file)
 }
 
 /*
- * file_operations::release
+ * ntfs_file_release - file_operations::release
  */
 static int ntfs_file_release(struct inode *inode, struct file *file)
 {
@@ -1188,7 +1196,7 @@ static int ntfs_file_release(struct inode *inode, struct file *file)
 	struct ntfs_sb_info *sbi = ni->mi.sbi;
 	int err = 0;
 
-	/* if we are the last writer on the inode, drop the block reservation */
+	/* If we are last writer on the inode, drop the block reservation. */
 	if (sbi->options.prealloc && ((file->f_mode & FMODE_WRITE) &&
 				      atomic_read(&inode->i_writecount) == 1)) {
 		ni_lock(ni);
@@ -1203,7 +1211,9 @@ static int ntfs_file_release(struct inode *inode, struct file *file)
 	return err;
 }
 
-/* file_operations::fiemap */
+/*
+ * ntfs_fiemap - file_operations::fiemap
+ */
 int ntfs_fiemap(struct inode *inode, struct fiemap_extent_info *fieinfo,
 		__u64 start, __u64 len)
 {

fs/ntfs3/lznt.c

@@ -4,6 +4,7 @@
  * Copyright (C) 2019-2021 Paragon Software GmbH, All rights reserved.
  *
  */
+
 #include <linux/blkdev.h>
 #include <linux/buffer_head.h>
 #include <linux/fs.h>
@@ -14,7 +15,7 @@
 #include "ntfs_fs.h"
 
 // clang-format off
-/* src buffer is zero */
+/* Src buffer is zero. */
 #define LZNT_ERROR_ALL_ZEROS	1
 #define LZNT_CHUNK_SIZE		0x1000
 // clang-format on
@@ -72,7 +73,7 @@ static size_t longest_match_std(const u8 *src, struct lznt *ctx)
 					      hash[1] + 3, ctx->max_len - 3);
 	}
 
-	/* Compare two matches and select the best one */
+	/* Compare two matches and select the best one. */
 	if (len1 < len2) {
 		ctx->best_match = hash[1];
 		len1 = len2;
@@ -129,10 +130,10 @@ static inline size_t parse_pair(u16 pair, size_t *offset, size_t index)
 /*
  * compress_chunk
  *
- * returns one of the three values:
- * 0 - ok, 'cmpr' contains 'cmpr_chunk_size' bytes of compressed data
- * 1 - input buffer is full zero
- * -2 - the compressed buffer is too small to hold the compressed data
+ * Return:
+ * * 0	- Ok, @cmpr contains @cmpr_chunk_size bytes of compressed data.
+ * * 1	- Input buffer is full zero.
+ * * -2 - The compressed buffer is too small to hold the compressed data.
  */
 static inline int compress_chunk(size_t (*match)(const u8 *, struct lznt *),
 				 const u8 *unc, const u8 *unc_end, u8 *cmpr,
@@ -145,7 +146,7 @@ static inline int compress_chunk(size_t (*match)(const u8 *, struct lznt *),
 	u8 *cp = cmpr + 3;
 	u8 *cp2 = cmpr + 2;
 	u8 not_zero = 0;
-	/* Control byte of 8-bit values: ( 0 - means byte as is, 1 - short pair ) */
+	/* Control byte of 8-bit values: ( 0 - means byte as is, 1 - short pair ). */
 	u8 ohdr = 0;
 	u8 *last;
 	u16 t16;
@@ -165,7 +166,7 @@ static inline int compress_chunk(size_t (*match)(const u8 *, struct lznt *),
 		while (unc + s_max_off[idx] < up)
 			ctx->max_len = s_max_len[++idx];
 
-		// Find match
+		/* Find match. */
 		max_len = up + 3 <= unc_end ? (*match)(up, ctx) : 0;
 
 		if (!max_len) {
@@ -211,7 +212,7 @@ static inline int compress_chunk(size_t (*match)(const u8 *, struct lznt *),
 		return -2;
 
 	/*
-	 * Copy non cmpr data
+	 * Copy non cmpr data.
 	 * 0x3FFF == ((LZNT_CHUNK_SIZE + 2 - 3) | 0x3000)
 	 */
 	cmpr[0] = 0xff;
@@ -233,38 +234,38 @@ static inline ssize_t decompress_chunk(u8 *unc, u8 *unc_end, const u8 *cmpr,
 	u16 pair;
 	size_t offset, length;
 
-	/* Do decompression until pointers are inside range */
+	/* Do decompression until pointers are inside range. */
 	while (up < unc_end && cmpr < cmpr_end) {
 		/* Correct index */
 		while (unc + s_max_off[index] < up)
 			index += 1;
 
-		/* Check the current flag for zero */
+		/* Check the current flag for zero. */
 		if (!(ch & (1 << bit))) {
-			/* Just copy byte */
+			/* Just copy byte. */
 			*up++ = *cmpr++;
 			goto next;
 		}
 
-		/* Check for boundary */
+		/* Check for boundary. */
 		if (cmpr + 1 >= cmpr_end)
 			return -EINVAL;
 
-		/* Read a short from little endian stream */
+		/* Read a short from little endian stream. */
 		pair = cmpr[1];
 		pair <<= 8;
 		pair |= cmpr[0];
 
 		cmpr += 2;
 
-		/* Translate packed information into offset and length */
+		/* Translate packed information into offset and length. */
 		length = parse_pair(pair, &offset, index);
 
-		/* Check offset for boundary */
+		/* Check offset for boundary. */
 		if (unc + offset > up)
 			return -EINVAL;
 
-		/* Truncate the length if necessary */
+		/* Truncate the length if necessary. */
 		if (up + length >= unc_end)
 			length = unc_end - up;
 
@@ -273,7 +274,7 @@ static inline ssize_t decompress_chunk(u8 *unc, u8 *unc_end, const u8 *cmpr,
 			*up = *(up - offset);
 
 next:
-		/* Advance flag bit value */
+		/* Advance flag bit value. */
 		bit = (bit + 1) & 7;
 
 		if (!bit) {
@@ -284,13 +285,14 @@ static inline ssize_t decompress_chunk(u8 *unc, u8 *unc_end, const u8 *cmpr,
 		}
 	}
 
-	/* return the size of uncompressed data */
+	/* Return the size of uncompressed data. */
 	return up - unc;
 }
 
 /*
- * 0 - standard compression
- * !0 - best compression, requires a lot of cpu
+ * get_lznt_ctx
+ * @level: 0 - Standard compression.
+ * 	   !0 - Best compression, requires a lot of cpu.
  */
 struct lznt *get_lznt_ctx(int level)
 {
@@ -303,11 +305,11 @@ struct lznt *get_lznt_ctx(int level)
 }
 
 /*
- * compress_lznt
+ * compress_lznt - Compresses @unc into @cmpr
  *
- * Compresses "unc" into "cmpr"
- * +x - ok, 'cmpr' contains 'final_compressed_size' bytes of compressed data
- * 0 - input buffer is full zero
+ * Return:
+ * * +x - Ok, @cmpr contains 'final_compressed_size' bytes of compressed data.
+ * * 0 - Input buffer is full zero.
  */
 size_t compress_lznt(const void *unc, size_t unc_size, void *cmpr,
 		     size_t cmpr_size, struct lznt *ctx)
@@ -327,7 +329,7 @@ size_t compress_lznt(const void *unc, size_t unc_size, void *cmpr,
 		match = &longest_match_best;
 	}
 
-	/* compression cycle */
+	/* Compression cycle. */
 	for (; unc_chunk < unc_end; unc_chunk += LZNT_CHUNK_SIZE) {
 		cmpr_size = 0;
 		err = compress_chunk(match, unc_chunk, unc_end, p, end,
@@ -348,9 +350,7 @@ size_t compress_lznt(const void *unc, size_t unc_size, void *cmpr,
 }
 
 /*
- * decompress_lznt
- *
- * decompresses "cmpr" into "unc"
+ * decompress_lznt - Decompress @cmpr into @unc.
  */
 ssize_t decompress_lznt(const void *cmpr, size_t cmpr_size, void *unc,
 			size_t unc_size)
@@ -364,24 +364,24 @@ ssize_t decompress_lznt(const void *cmpr, size_t cmpr_size, void *unc,
 	if (cmpr_size < sizeof(short))
 		return -EINVAL;
 
-	/* read chunk header */
+	/* Read chunk header. */
 	chunk_hdr = cmpr_chunk[1];
 	chunk_hdr <<= 8;
 	chunk_hdr |= cmpr_chunk[0];
 
-	/* loop through decompressing chunks */
+	/* Loop through decompressing chunks. */
 	for (;;) {
 		size_t chunk_size_saved;
 		size_t unc_use;
 		size_t cmpr_use = 3 + (chunk_hdr & (LZNT_CHUNK_SIZE - 1));
 
-		/* Check that the chunk actually fits the supplied buffer */
+		/* Check that the chunk actually fits the supplied buffer. */
 		if (cmpr_chunk + cmpr_use > cmpr_end)
 			return -EINVAL;
 
-		/* First make sure the chunk contains compressed data */
+		/* First make sure the chunk contains compressed data. */
 		if (chunk_hdr & 0x8000) {
-			/* Decompress a chunk and return if we get an error */
+			/* Decompress a chunk and return if we get an error. */
 			ssize_t err =
 				decompress_chunk(unc_chunk, unc_end,
 						 cmpr_chunk + sizeof(chunk_hdr),
@@ -390,7 +390,7 @@ ssize_t decompress_lznt(const void *cmpr, size_t cmpr_size, void *unc,
 				return err;
 			unc_use = err;
 		} else {
-			/* This chunk does not contain compressed data */
+			/* This chunk does not contain compressed data. */
 			unc_use = unc_chunk + LZNT_CHUNK_SIZE > unc_end
 					  ? unc_end - unc_chunk
 					  : LZNT_CHUNK_SIZE;
@@ -404,21 +404,21 @@ ssize_t decompress_lznt(const void *cmpr, size_t cmpr_size, void *unc,
 			       unc_use);
 		}
 
-		/* Advance pointers */
+		/* Advance pointers. */
 		cmpr_chunk += cmpr_use;
 		unc_chunk += unc_use;
 
-		/* Check for the end of unc buffer */
+		/* Check for the end of unc buffer. */
 		if (unc_chunk >= unc_end)
 			break;
 
-		/* Proceed the next chunk */
+		/* Proceed the next chunk. */
 		if (cmpr_chunk > cmpr_end - 2)
 			break;
 
 		chunk_size_saved = LZNT_CHUNK_SIZE;
 
-		/* read chunk header */
+		/* Read chunk header. */
 		chunk_hdr = cmpr_chunk[1];
 		chunk_hdr <<= 8;
 		chunk_hdr |= cmpr_chunk[0];
@@ -426,12 +426,12 @@ ssize_t decompress_lznt(const void *cmpr, size_t cmpr_size, void *unc,
 		if (!chunk_hdr)
 			break;
 
-		/* Check the size of unc buffer */
+		/* Check the size of unc buffer. */
 		if (unc_use < chunk_size_saved) {
 			size_t t1 = chunk_size_saved - unc_use;
 			u8 *t2 = unc_chunk + t1;
 
-			/* 'Zero' memory */
+			/* 'Zero' memory. */
 			if (t2 >= unc_end)
 				break;
 
@@ -440,13 +440,13 @@ ssize_t decompress_lznt(const void *cmpr, size_t cmpr_size, void *unc,
 		}
 	}
 
-	/* Check compression boundary */
+	/* Check compression boundary. */
 	if (cmpr_chunk > cmpr_end)
 		return -EINVAL;
 
 	/*
 	 * The unc size is just a difference between current
-	 * pointer and original one
+	 * pointer and original one.
 	 */
 	return PtrOffset(unc, unc_chunk);
 }