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>
diff --git a/fs/ntfs3/record.c b/fs/ntfs3/record.c
index dec83ac..d48a5e6 100644
--- a/fs/ntfs3/record.c
+++ b/fs/ntfs3/record.c
@@ -18,15 +18,13 @@ static inline int compare_attr(const struct ATTRIB *left, enum ATTR_TYPE type,
const __le16 *name, u8 name_len,
const u16 *upcase)
{
- /* First, compare the type codes: */
+ /* First, compare the type codes. */
int diff = le32_to_cpu(left->type) - le32_to_cpu(type);
if (diff)
return diff;
- /*
- * They have the same type code, so we have to compare the names.
- */
+ /* They have the same type code, so we have to compare the names. */
return ntfs_cmp_names(attr_name(left), left->name_len, name, name_len,
upcase, true);
}
@@ -34,7 +32,7 @@ static inline int compare_attr(const struct ATTRIB *left, enum ATTR_TYPE type,
/*
* mi_new_attt_id
*
- * returns unused attribute id that is less than mrec->next_attr_id
+ * Return: Unused attribute id that is less than mrec->next_attr_id.
*/
static __le16 mi_new_attt_id(struct mft_inode *mi)
{
@@ -50,7 +48,7 @@ static __le16 mi_new_attt_id(struct mft_inode *mi)
return id;
}
- /* One record can store up to 1024/24 ~= 42 attributes */
+ /* One record can store up to 1024/24 ~= 42 attributes. */
free_id = 0;
max_id = 0;
@@ -115,9 +113,7 @@ int mi_init(struct mft_inode *mi, struct ntfs_sb_info *sbi, CLST rno)
}
/*
- * mi_read
- *
- * reads MFT data
+ * mi_read - Read MFT data.
*/
int mi_read(struct mft_inode *mi, bool is_mft)
{
@@ -178,7 +174,7 @@ int mi_read(struct mft_inode *mi, bool is_mft)
goto out;
ok:
- /* check field 'total' only here */
+ /* Check field 'total' only here. */
if (le32_to_cpu(rec->total) != bpr) {
err = -EINVAL;
goto out;
@@ -210,13 +206,13 @@ struct ATTRIB *mi_enum_attr(struct mft_inode *mi, struct ATTRIB *attr)
return NULL;
}
- /* Skip non-resident records */
+ /* Skip non-resident records. */
if (!is_rec_inuse(rec))
return NULL;
attr = Add2Ptr(rec, off);
} else {
- /* Check if input attr inside record */
+ /* Check if input attr inside record. */
off = PtrOffset(rec, attr);
if (off >= used)
return NULL;
@@ -233,27 +229,27 @@ struct ATTRIB *mi_enum_attr(struct mft_inode *mi, struct ATTRIB *attr)
asize = le32_to_cpu(attr->size);
- /* Can we use the first field (attr->type) */
+ /* Can we use the first field (attr->type). */
if (off + 8 > used) {
static_assert(ALIGN(sizeof(enum ATTR_TYPE), 8) == 8);
return NULL;
}
if (attr->type == ATTR_END) {
- /* end of enumeration */
+ /* End of enumeration. */
return NULL;
}
- /* 0x100 is last known attribute for now*/
+ /* 0x100 is last known attribute for now. */
t32 = le32_to_cpu(attr->type);
if ((t32 & 0xf) || (t32 > 0x100))
return NULL;
- /* Check boundary */
+ /* Check boundary. */
if (off + asize > used)
return NULL;
- /* Check size of attribute */
+ /* Check size of attribute. */
if (!attr->non_res) {
if (asize < SIZEOF_RESIDENT)
return NULL;
@@ -270,7 +266,7 @@ struct ATTRIB *mi_enum_attr(struct mft_inode *mi, struct ATTRIB *attr)
return attr;
}
- /* Check some nonresident fields */
+ /* Check some nonresident fields. */
if (attr->name_len &&
le16_to_cpu(attr->name_off) + sizeof(short) * attr->name_len >
le16_to_cpu(attr->nres.run_off)) {
@@ -290,9 +286,7 @@ struct ATTRIB *mi_enum_attr(struct mft_inode *mi, struct ATTRIB *attr)
}
/*
- * mi_find_attr
- *
- * finds the attribute by type and name and id
+ * mi_find_attr - Find the attribute by type and name and id.
*/
struct ATTRIB *mi_find_attr(struct mft_inode *mi, struct ATTRIB *attr,
enum ATTR_TYPE type, const __le16 *name,
@@ -372,7 +366,7 @@ int mi_format_new(struct mft_inode *mi, struct ntfs_sb_info *sbi, CLST rno,
} else if (mi_read(mi, is_mft)) {
;
} else if (rec->rhdr.sign == NTFS_FILE_SIGNATURE) {
- /* Record is reused. Update its sequence number */
+ /* Record is reused. Update its sequence number. */
seq = le16_to_cpu(rec->seq) + 1;
if (!seq)
seq = 1;
@@ -404,9 +398,7 @@ int mi_format_new(struct mft_inode *mi, struct ntfs_sb_info *sbi, CLST rno,
}
/*
- * mi_mark_free
- *
- * marks record as unused and marks it as free in bitmap
+ * mi_mark_free - Mark record as unused and marks it as free in bitmap.
*/
void mi_mark_free(struct mft_inode *mi)
{
@@ -428,10 +420,9 @@ void mi_mark_free(struct mft_inode *mi)
}
/*
- * mi_insert_attr
+ * mi_insert_attr - Reserve space for new attribute.
*
- * reserves space for new attribute
- * returns not full constructed attribute or NULL if not possible to create
+ * Return: Not full constructed attribute or NULL if not possible to create.
*/
struct ATTRIB *mi_insert_attr(struct mft_inode *mi, enum ATTR_TYPE type,
const __le16 *name, u8 name_len, u32 asize,
@@ -468,7 +459,7 @@ struct ATTRIB *mi_insert_attr(struct mft_inode *mi, enum ATTR_TYPE type,
}
if (!attr) {
- tail = 8; /* not used, just to suppress warning */
+ tail = 8; /* Not used, just to suppress warning. */
attr = Add2Ptr(rec, used - 8);
} else {
tail = used - PtrOffset(rec, attr);
@@ -494,10 +485,9 @@ struct ATTRIB *mi_insert_attr(struct mft_inode *mi, enum ATTR_TYPE type,
}
/*
- * mi_remove_attr
+ * mi_remove_attr - Remove the attribute from record.
*
- * removes the attribute from record
- * NOTE: The source attr will point to next attribute
+ * NOTE: The source attr will point to next attribute.
*/
bool mi_remove_attr(struct mft_inode *mi, struct ATTRIB *attr)
{
@@ -543,7 +533,7 @@ bool mi_resize_attr(struct mft_inode *mi, struct ATTRIB *attr, int bytes)
if (used + dsize > total)
return false;
nsize = asize + dsize;
- // move tail
+ /* Move tail */
memmove(next + dsize, next, tail);
memset(next, 0, dsize);
used += dsize;
@@ -585,10 +575,10 @@ int mi_pack_runs(struct mft_inode *mi, struct ATTRIB *attr,
u32 tail = used - aoff - asize;
u32 dsize = sbi->record_size - used;
- /* Make a maximum gap in current record */
+ /* Make a maximum gap in current record. */
memmove(next + dsize, next, tail);
- /* Pack as much as possible */
+ /* Pack as much as possible. */
err = run_pack(run, svcn, len, Add2Ptr(attr, run_off), run_size + dsize,
&plen);
if (err < 0) {