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, 32 insertions, 29 deletions

diff --git a/fs/ntfs3/dir.c b/fs/ntfs3/dir.c
index d36d7fbc2b1d..93f6d485564e 100644
--- a/fs/ntfs3/dir.c
+++ b/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) {