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, 53 insertions, 43 deletions

diff --git a/fs/ntfs3/file.c b/fs/ntfs3/file.c
index a959f6197c99..26346771d9dc 100644
--- a/fs/ntfs3/file.c
+++ b/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 @@ out:
 }
 
 /*
- * 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 @@ out:
 }
 
 /*
- * 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 @@ out:
 }
 
 /*
- * 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 @@ out:
 }
 
 /*
- * 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)
 {