[6/6] block-helpers: update doc comment in gtkdoc style

Commit Message

Stefan Hajnoczi June 19, 2020, 12:01 p.m. UTC

QEMU uses the gtkdoc style for API doc comments. For examples, see
include/qom/object.h.

Fully document the function with up-to-date information (the min/max
values were outdated).

Signed-off-by: Stefan Hajnoczi <[e-mail]>
---
 util/block-helpers.c | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

Patch

diff --git a/util/block-helpers.c b/util/block-helpers.c
index 9d12368032..c4851432f5 100644
--- a/util/block-helpers.c
+++ b/util/block-helpers.c
@@ -13,15 +13,17 @@ 
 #include "qapi/qmp/qerror.h"
 #include "block-helpers.h"
 
-/*
- * Logical block size input validation
+/**
+ * check_block_size:
+ * @id: The unique ID of the object
+ * @name: The name of the property being validated
+ * @value: The block size in bytes
+ * @errp: A pointer to an area to store an error
  *
- * The size should meet the following conditions:
- * 1. min=512
- * 2. max=32768
- * 3. a power of 2
- *
- *  Moved from hw/core/qdev-properties.c:set_blocksize()
+ * This function checks that the block size meets the following conditions:
+ * 1. At least MIN_BLOCK_SIZE
+ * 2. No larger than MAX_BLOCK_SIZE
+ * 3. A power of 2
  */
 void check_block_size(const char *id, const char *name, int64_t value,
                       Error **errp)