From 0eb92d7aa0fca23cafb675f6140861206ba48101 Mon Sep 17 00:00:00 2001 From: Jaap Keuter Date: Wed, 29 Apr 2020 09:29:53 +0200 Subject: [PATCH] Document unit string and true false string helper functions Provide Doxygen comment blocks for unit string and true false string helper functions. Change-Id: I70801561e9cd3ead5e3417ea9d297d828105f3d0 Reviewed-on: https://code.wireshark.org/review/36968 Petri-Dish: Anders Broman Tested-by: Petri Dish Buildbot Reviewed-by: Anders Broman --- epan/tfs.c | 1 + epan/tfs.h | 11 +++++++++-- epan/unit_strings.c | 3 +++ epan/unit_strings.h | 29 ++++++++++++++++++++++++++--- 4 files changed, 39 insertions(+), 5 deletions(-) diff --git a/epan/tfs.c b/epan/tfs.c index 402fb56762..cd560660cf 100644 --- a/epan/tfs.c +++ b/epan/tfs.c @@ -13,6 +13,7 @@ #include "tfs.h" +/** Returns the string representing the true or false value. */ const char *tfs_get_string(gboolean value, const true_false_string *tfs) { return value ? tfs->true_string : tfs->false_string; diff --git a/epan/tfs.h b/epan/tfs.h index d24f09ef3c..ccd41b609c 100644 --- a/epan/tfs.h +++ b/epan/tfs.h @@ -23,13 +23,20 @@ extern "C" { * true_false strings */ -/** Struct for boolean enumerations */ +/** Struct for boolean representation */ typedef struct true_false_string { const char *true_string; /**< The string presented when true */ const char *false_string; /**< The string presented when false */ } true_false_string; -WS_DLL_PUBLIC const char *tfs_get_string(gboolean, const true_false_string *); +/** Returns the string representing the true or false value. + * + * From the given true_false_string return the appropriate string pointer + * @param[in] value The boolean value for which the string representation is sought + * @param[in] tfs The true_false_string containing the relevant strings + * @return Pointer to the appropriate string + */ +WS_DLL_PUBLIC const char *tfs_get_string(gboolean value, const true_false_string *tfs); /* * A default set of true/false strings that dissectors can use for diff --git a/epan/unit_strings.c b/epan/unit_strings.c index 8b91120d0d..2d7d668155 100644 --- a/epan/unit_strings.c +++ b/epan/unit_strings.c @@ -14,6 +14,7 @@ #include #include "unit_strings.h" +/** Returns the unit string appropriate for the 32 bit value. */ const char* unit_name_string_get_value(guint32 value, const unit_name_string* units) { if (units->plural == NULL) @@ -22,6 +23,7 @@ const char* unit_name_string_get_value(guint32 value, const unit_name_string* un return plurality(value, units->singular, units->plural); } +/** Returns the unit string appropriate for the 64 bit value. */ const char* unit_name_string_get_value64(guint64 value, const unit_name_string* units) { if (units->plural == NULL) @@ -30,6 +32,7 @@ const char* unit_name_string_get_value64(guint64 value, const unit_name_string* return plurality(value, units->singular, units->plural); } +/** Returns the unit string appropriate for the double value. */ const char* unit_name_string_get_double(double value, const unit_name_string* units) { if (units->plural == NULL) diff --git a/epan/unit_strings.h b/epan/unit_strings.h index 87d65ca73f..d52d54d2be 100644 --- a/epan/unit_strings.h +++ b/epan/unit_strings.h @@ -21,14 +21,37 @@ extern "C" { * Units to append to field values */ -/* For BASE_UNIT_STRING, the display format for adding units */ +/** For BASE_UNIT_STRING, the display format for adding units */ typedef struct unit_name_string { - char *singular; /* name to use for 1 unit */ - char *plural; /* name to use for < 1 or > 1 units */ + char *singular; /**< name to use for 1 unit */ + char *plural; /**< name to use for < 1 or > 1 units */ } unit_name_string; +/** Returns the unit string appropriate for the 32 bit value. + * + * From the given unit_name_string return the appropriate string pointer + * @param[in] value The value for which to get the appropriate string + * @param[in] units The unit_name_string containing the relevant strings + * @return Pointer to the appropriate string + */ WS_DLL_PUBLIC const char* unit_name_string_get_value(guint32 value, const unit_name_string* units); + +/** Returns the unit string appropriate for the 64 bit value. + * + * From the given unit_name_string return the appropriate string pointer + * @param[in] value The value for which to get the appropriate string + * @param[in] units The unit_name_string containing the relevant strings + * @return Pointer to the appropriate string + */ WS_DLL_PUBLIC const char* unit_name_string_get_value64(guint64 value, const unit_name_string* units); + +/** Returns the unit string appropriate for the double value. + * + * From the given unit_name_string return the appropriate string pointer + * @param[in] value The value for which to get the appropriate string + * @param[in] units The unit_name_string containing the relevant strings + * @return Pointer to the appropriate string + */ WS_DLL_PUBLIC const char* unit_name_string_get_double(double value, const unit_name_string* units); /*