Improve some comments
Subsystems (2)
Damien Le Moal
maintainercover Improve some comments
Jens,
Here are a couple of patches to improve helper function comments. No functional changes.
This also gets rid of the "XXX" strings in the comments, which makes temporary coding easier as XXX is often used to marke places that need some more attention when developing.
Damien Le Moal (2):
block: fix blk_zone_cond_str() comment
block: improve blk_op_str() comment
block/blk-core.c | 10 +++++----- block/blk-zoned.c | 10 +++++----- include/linux/blkdev.h | 4 ++-- 3 files changed, 12 insertions(+), 12 deletions(-)
Signature · 1 line
2.52.0
Damien Le Moal
maintainerPATCH 1/2 block: fix blk_zone_cond_str() comment
Fix the comment for blk_zone_cond_str() by replacing the meaningless BLK_ZONE_ZONE_XXX comment with the correct BLK_ZONE_COND_name, thus also replacing the XXX with what that actually means.
--- block/blk-zoned.c | 10 +++++----- include/linux/blkdev.h | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-)
block/blk-zoned.c +5 -5
@@ -112,12 +112,12 @@ static inline unsigned int disk_zone_wplugs_hash_size(struct gendisk *disk)#define BLK_ZONE_WPLUG_UNHASHED (1U << 2)/** -* blk_zone_cond_str - Return string XXX in BLK_ZONE_COND_XXX. -* @zone_cond: BLK_ZONE_COND_XXX. +* blk_zone_cond_str - Return a zone condition name string +* @zone_cond: a zone condition BLK_ZONE_COND_name * -* Description: Centralize block layer function to convert BLK_ZONE_COND_XXX -* into string format. Useful in the debugging and tracing zone conditions. For -* invalid BLK_ZONE_COND_XXX it returns string "UNKNOWN". +* Convert a BLK_ZONE_COND_name zone condition into the string "name". Useful +* for the debugging and tracing zone conditions. For an invalid zone +* conditions, the string "UNKNOWN" is returned. */ const char *blk_zone_cond_str (enum blk_zone_cond zone_cond) {
include/linux/blkdev.h +1 -1
@@ -1044,7 +1044,7 @@ static inline struct request_queue *bdev_get_queue(struct block_device *bdev)return bdev->bd_queue;/* this is never NULL */ } -/* Helper to convert BLK_ZONE_ZONE_XXX to its string format XXX */ +/* Convert a zone condition BLK_ZONE_COND_name into the string "name" */ const char *blk_zone_cond_str (enum blk_zone_cond zone_cond);static inline unsigned int bio_zone_no (struct bio *bio)
Signature · 1 line
2.52.0
Damien Le Moal
maintainerPATCH 2/2 block: improve blk_op_str() comment
In reply to Damien Le MoalReplace XXX with what it actually means.
--- block/blk-core.c | 10 +++++----- include/linux/blkdev.h | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-)
block/blk-core.c +5 -5
@@ -114,12 +114,12 @@ static const char *const blk_op_name[] = {#undef REQ_OP_NAME/** -* blk_op_str - Return string XXX in the REQ_OP_XXX. -* @op: REQ_OP_XXX. +* blk_op_str - Return the string "name" for an operation REQ_OP_name. +* @op: a request operation. * -* Description: Centralize block layer function to convert REQ_OP_XXX into -* string format. Useful in the debugging and tracing bio or request. For -* invalid REQ_OP_XXX it returns string "UNKNOWN". +* Convert a request operation REQ_OP_name into the string "name". Useful for +* debugging and tracing BIOs and requests. For an invalid request operation +* code, the string "UNKNOWN" is returned. */ inline const char *blk_op_str (enum req_op op) {
include/linux/blkdev.h +1 -1
@@ -1026,7 +1026,7 @@ extern int blk_queue_enter(struct request_queue *q, blk_mq_req_flags_t flags);extern void blk_queue_exit (struct request_queue *q);extern void blk_sync_queue (struct request_queue *q); -/* Helper to convert REQ_OP_XXX to its string format XXX */ +/* Convert a request operation REQ_OP_name into the string "name" */ extern const char *blk_op_str (enum req_op op);int blk_status_to_errno (blk_status_t status);
Signature · 1 line
2.52.0
Re: [PATCH 1/2] block: fix blk_zone_cond_str() comment
In reply to Damien Le MoalQuoted 5 lines · Damien Le Moal
Fix the comment for
blk_zone_cond_str()by replacing the meaninglessBLK_ZONE_ZONE_XXXcomment with the correctBLK_ZONE_COND_name, thus also replacing the XXX with what that actually means.Signed-off-by Damien Le Moal<[email protected]>
Looks good.
-ck
Re: [PATCH 2/2] block: improve blk_op_str() comment
In reply to Damien Le MoalQuoted 3 lines · Damien Le Moal
Replace XXX with what it actually means.
Signed-off-by Damien Le Moal<[email protected]>
Looks good.
-ck
Re: [PATCH 1/2] block: fix blk_zone_cond_str() comment
In reply to Damien Le MoalThanks, I always hated that XXX as it triggers the todo list detector in my syntax highlighting setup.
Re: [PATCH 2/2] block: improve blk_op_str() comment
In reply to Damien Le MoalLooks good:
Quoted 6 lines · Damien Le Moal
Here are a couple of patches to improve helper function comments. No functional changes.
This also gets rid of the "XXX" strings in the comments, which makes temporary coding easier as XXX is often used to marke places that need some more attention when developing.
For the series:
Quoted 10 lines · Damien Le Moal
Jens,
Here are a couple of patches to improve helper function comments. No functional changes.
This also gets rid of the "XXX" strings in the comments, which makes temporary coding easier as XXX is often used to marke places that need some more attention when developing.
[...]
Applied, thanks!
[1/2] block: fix blk_zone_cond_str() comment
commit: 41ee77b75308354054f4fe03a05b8016a0d41573
[2/2] block: improve blk_op_str() comment
commit: 5e35a24c96185e1be4c24a713e53a49e92ab925bBest regards,
Signature · 1 line
Jens Axboe