linux-kernel - Re: [PATCH] Restyle comments to better align with kernel-doc

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <22f979ec-95e5-e95a-0d58-9eb43f2038aa@paragon-software.com>
Date:   Mon, 30 Aug 2021 19:10:36 +0300
From:   Konstantin Komarov <almaz.alexandrovich@...agon-software.com>
To:     Kari Argillander <kari.argillander@...il.com>
CC:     <linux-fsdevel@...r.kernel.org>, <linux-kernel@...r.kernel.org>,
        <joe@...ches.com>, <dan.carpenter@...cle.com>,
        <willy@...radead.org>, <ntfs3@...ts.linux.dev>
Subject: Re: [PATCH] Restyle comments to better align with kernel-doc



On 03.08.2021 14:57, Kari Argillander wrote:
> 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@...il.com>
> ---
> Yes I know that this patch is quite monster. That's why I try to send this
> now before patch series get merged. After that this patch probebly needs to
> be splitted more and sended in patch series.
> 
> If someone thinks this should not be added now it is ok. I have try to read
> what is kernel philosophy in case "patch to patch" but haven't found any
> good information about it. It is no big deal to add later. In my own mind I
> do not want to touch so much comments after code is in.
> 
> I also don't know how easy this kind of patch is apply top of the patch
> series.

Thanks for the patch. I've applied it to create uniform style of comments.

Also removed double line addition from patch:

@@ -269,22 +260,28 @@ enum RECORD_FLAG {
 	RECORD_FLAG_UNKNOWN	= cpu_to_le16(0x0008),
 };

-/* MFT Record structure */
+/* MFT Record structure, */
 struct MFT_REC {
 	struct NTFS_RECORD_HEADER rhdr; // 'FILE'

-	__le16 seq;		// 0x10: Sequence number for this record
-	__le16 hard_links;	// 0x12: The number of hard links to record
-	__le16 attr_off;	// 0x14: Offset to attributes
-	__le16 flags;		// 0x16: See RECORD_FLAG
-	__le32 used;		// 0x18: The size of used part
-	__le32 total;		// 0x1C: Total record size
+	__le16 seq;		// 0x10: Sequence number for this record.
+	__le16 hard_links;	// 0x12: The number of hard links to record.
+	__le16 attr_off;	// 0x14: Offset to attributes.
+	__le16 flags;		// 0x16: See RECORD_FLAG.
+	__le32 used;		// 0x18: The size of used part.
+	__le32 total;		// 0x1C: Total record size.
+
+	struct MFT_REF parent_ref; // 0x20: Parent MFT record.
+	__le16 next_attr_id;	// 0x28: The next attribute Id.

-	struct MFT_REF parent_ref; // 0x20: Parent MFT record
-	__le16 next_attr_id;	// 0x28: The next attribute Id
+	__le32 used;		// 0x18: The size of used part.
+	__le32 total;		// 0x1C: Total record size.

-	__le16 res;		// 0x2A: High part of mft record?
-	__le32 mft_record;	// 0x2C: Current mft record number
+	struct MFT_REF parent_ref; // 0x20: Parent MFT record.
+	__le16 next_attr_id;	// 0x28: The next attribute Id.
+
+	__le16 res;		// 0x2A: High part of MFT record?
+	__le32 mft_record;	// 0x2C: Current MFT record number.
 	__le16 fixups[];	// 0x30:
 };