Skip to contentSkip to conversation

Improve some comments

PATCH Applied Damien Le Moal 5 participants 9 messages Jan 6 – Jan 15

Subsystems (2)
lore
Share & tools
lore

Damien Le Moal

author maintainer
#0 lore raw

cover 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
author maintainer
#1 lore raw

PATCH 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
index 1c54678fae6b..ef3872c53244 100644
@@ -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
index 72e34acd439c..63affe898059 100644
@@ -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
author maintainer
#4 lore raw

PATCH 2/2 block: improve blk_op_str() comment

In reply to Damien Le Moal

Replace 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
index 8387fe50ea15..a8a62154376c 100644
@@ -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
index 63affe898059..438c4946b6e5 100644
@@ -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
Reviewed-by on the v1 series
#7 lore raw
In reply to Damien Le Moal
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:

maintainer Applied
#8 lore raw
In reply to Damien Le Moal
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: 5e35a24c96185e1be4c24a713e53a49e92ab925b

Best regards,

Signature · 1 line
Jens Axboe