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] [day] [month] [year] [list]

Message-ID: <20210830171314.hya2vn3vyohcn4dk@kari-VirtualBox>
Date:   Mon, 30 Aug 2021 20:13:14 +0300
From:   Kari Argillander <kari.argillander@...il.com>
To:     Konstantin Komarov <almaz.alexandrovich@...agon-software.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 Mon, Aug 30, 2021 at 07:10:36PM +0300, Konstantin Komarov wrote:
> 
> 
> 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.

There where probably lot of merge conflicts as this patch was made for
v27. Also lot of changes since v28 in the code base. You can always ask
submitter to rebase patch and resend. Also there where quite lot of nack
about this patch so I though this should be dropped, but maintainer
decision I guess.

> Also removed double line addition from patch:

Just ask and submitter will do it for you.

> 
> @@ -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:
>  };
>