If routines return a wtap_opttype_return_val, declare them as doing so.

Also, improve the doxygen comments.

Change-Id: I57929dfba23d926fd806ac001a5a3924bb636ae0
Reviewed-on: https://code.wireshark.org/review/15634
Reviewed-by: Guy Harris <guy@alum.mit.edu>

2 files changed, 68 insertions, 48 deletions

diff --git a/wiretap/wtap_opttypes.c b/wiretap/wtap_opttypes.c
index 87c874a1a4..f5506750b5 100644
--- a/wiretap/wtap_opttypes.c
+++ b/wiretap/wtap_opttypes.c
@@ -264,7 +264,7 @@ void wtap_optionblock_foreach_option(wtap_optionblock_t block, wtap_optionblock_
     }
 }
 
-int wtap_optionblock_add_option(wtap_optionblock_t block, guint option_id, wtap_optblock_reg_t* option)
+wtap_opttype_return_val wtap_optionblock_add_option(wtap_optionblock_t block, guint option_id, wtap_optblock_reg_t* option)
 {
     wtap_optblock_value_t* opt_value = wtap_optionblock_get_option(block, option_id);
     wtap_optblock_internal_t *opt_internal;
@@ -312,7 +312,7 @@ int wtap_optionblock_add_option(wtap_optionblock_t block, guint option_id, wtap_
     return WTAP_OPTTYPE_SUCCESS;
 }
 
-int wtap_optionblock_set_option_string(wtap_optionblock_t block, guint option_id, char* value, gsize value_length)
+wtap_opttype_return_val wtap_optionblock_set_option_string(wtap_optionblock_t block, guint option_id, char* value, gsize value_length)
 {
     wtap_optblock_value_t* opt_value = wtap_optionblock_get_option(block, option_id);
 
@@ -328,7 +328,7 @@ int wtap_optionblock_set_option_string(wtap_optionblock_t block, guint option_id
     return WTAP_OPTTYPE_SUCCESS;
 }
 
-int wtap_optionblock_set_option_string_format(wtap_optionblock_t block, guint option_id, const char *format, ...)
+wtap_opttype_return_val wtap_optionblock_set_option_string_format(wtap_optionblock_t block, guint option_id, const char *format, ...)
 {
     va_list va;
     wtap_optblock_value_t* opt_value = wtap_optionblock_get_option(block, option_id);
@@ -347,7 +347,7 @@ int wtap_optionblock_set_option_string_format(wtap_optionblock_t block, guint op
     return WTAP_OPTTYPE_SUCCESS;
 }
 
-int wtap_optionblock_get_option_string(wtap_optionblock_t block, guint option_id, char** value)
+wtap_opttype_return_val wtap_optionblock_get_option_string(wtap_optionblock_t block, guint option_id, char** value)
 {
     wtap_optblock_value_t* opt_value = wtap_optionblock_get_option(block, option_id);
 
@@ -362,7 +362,7 @@ int wtap_optionblock_get_option_string(wtap_optionblock_t block, guint option_id
     return WTAP_OPTTYPE_SUCCESS;
 }
 
-int wtap_optionblock_set_option_uint64(wtap_optionblock_t block, guint option_id, guint64 value)
+wtap_opttype_return_val wtap_optionblock_set_option_uint64(wtap_optionblock_t block, guint option_id, guint64 value)
 {
     wtap_optblock_value_t* opt_value = wtap_optionblock_get_option(block, option_id);
 
@@ -377,7 +377,7 @@ int wtap_optionblock_set_option_uint64(wtap_optionblock_t block, guint option_id
     return WTAP_OPTTYPE_SUCCESS;
 }
 
-int wtap_optionblock_get_option_uint64(wtap_optionblock_t block, guint option_id, guint64* value)
+wtap_opttype_return_val wtap_optionblock_get_option_uint64(wtap_optionblock_t block, guint option_id, guint64* value)
 {
     wtap_optblock_value_t* opt_value = wtap_optionblock_get_option(block, option_id);
 
@@ -393,7 +393,7 @@ int wtap_optionblock_get_option_uint64(wtap_optionblock_t block, guint option_id
 }
 
 
-int wtap_optionblock_set_option_uint8(wtap_optionblock_t block, guint option_id, guint8 value)
+wtap_opttype_return_val wtap_optionblock_set_option_uint8(wtap_optionblock_t block, guint option_id, guint8 value)
 {
     wtap_optblock_value_t* opt_value = wtap_optionblock_get_option(block, option_id);
 
@@ -408,7 +408,7 @@ int wtap_optionblock_set_option_uint8(wtap_optionblock_t block, guint option_id,
     return WTAP_OPTTYPE_SUCCESS;
 }
 
-int wtap_optionblock_get_option_uint8(wtap_optionblock_t block, guint option_id, guint8* value)
+wtap_opttype_return_val wtap_optionblock_get_option_uint8(wtap_optionblock_t block, guint option_id, guint8* value)
 {
     wtap_optblock_value_t* opt_value = wtap_optionblock_get_option(block, option_id);
 
@@ -423,7 +423,7 @@ int wtap_optionblock_get_option_uint8(wtap_optionblock_t block, guint option_id,
     return WTAP_OPTTYPE_SUCCESS;
 }
 
-int wtap_optionblock_set_option_custom(wtap_optionblock_t block, guint option_id, void* value)
+wtap_opttype_return_val wtap_optionblock_set_option_custom(wtap_optionblock_t block, guint option_id, void* value)
 {
     wtap_optblock_value_t* opt_value = wtap_optionblock_get_option(block, option_id);
     void* prev_value;
@@ -442,7 +442,7 @@ int wtap_optionblock_set_option_custom(wtap_optionblock_t block, guint option_id
     return WTAP_OPTTYPE_SUCCESS;
 }
 
-int wtap_optionblock_get_option_custom(wtap_optionblock_t block, guint option_id, void** value)
+wtap_opttype_return_val wtap_optionblock_get_option_custom(wtap_optionblock_t block, guint option_id, void** value)
 {
     wtap_optblock_value_t* opt_value = wtap_optionblock_get_option(block, option_id);
 
diff --git a/wiretap/wtap_opttypes.h b/wiretap/wtap_opttypes.h
index fcdf36ce30..736d3e4145 100644
--- a/wiretap/wtap_opttypes.h
+++ b/wiretap/wtap_opttypes.h
@@ -108,102 +108,122 @@ WS_DLL_PUBLIC void wtap_optionblock_free(wtap_optionblock_t block);
 
 /** Provide mandatory data of an option block
  *
- * @param[in] block Block to retrieve mandatory data
+ * @param[in] block Block from which to retrieve mandatory data
  * @return Option block mandatory data.  Structure varies based on option block type
  */
 WS_DLL_PUBLIC void* wtap_optionblock_get_mandatory_data(wtap_optionblock_t block);
 
 /** Add an option to the option block
  *
- * @param[in] block Block to add option
+ * @param[in] block Block to which to add option
  * @param[in] option_id Identifier value for option
  * @param[in] option structure explaining it
- * @return 0 if successful
+ * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
+ * error code otherwise
  */
-int wtap_optionblock_add_option(wtap_optionblock_t block, guint option_id, wtap_optblock_reg_t* option);
+WS_DLL_PUBLIC wtap_opttype_return_val
+wtap_optionblock_add_option(wtap_optionblock_t block, guint option_id, wtap_optblock_reg_t* option);
 
-/** Set string option value to an option block
+/** Set string option value in an option block
  *
- * @param[in] block Block to add option
+ * @param[in] block Block in which to set the option value
  * @param[in] option_id Identifier value for option
  * @param[in] value New value of option
  * @param[in] value_length Maximum length of string to copy.
- * @return 0 if successful
+ * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
+ * error code otherwise
  */
-WS_DLL_PUBLIC int wtap_optionblock_set_option_string(wtap_optionblock_t block, guint option_id, char* value, gsize value_length);
+WS_DLL_PUBLIC wtap_opttype_return_val
+wtap_optionblock_set_option_string(wtap_optionblock_t block, guint option_id, char* value, gsize value_length);
 
-/** Set printf-styled string option value to an option block
+/** Set string option value in an option block to a printf-formatted string
  *
- * @param[in] block Block to add option
+ * @param[in] block Block in which to set the option value
  * @param[in] option_id Identifier value for option
- * @param[in] format printf like format string
- * @return 0 if successful
+ * @param[in] format printf-like format string
+ * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
+ * error code otherwise
  */
-WS_DLL_PUBLIC int wtap_optionblock_set_option_string_format(wtap_optionblock_t block, guint option_id, const char *format, ...)
-                                                            G_GNUC_PRINTF(3,4);
+WS_DLL_PUBLIC wtap_opttype_return_val
+wtap_optionblock_set_option_string_format(wtap_optionblock_t block, guint option_id, const char *format, ...)
+                                          G_GNUC_PRINTF(3,4);
 
 /** Get string option value from an option block
  *
- * @param[in] block Block to add option
+ * @param[in] block Block from which to get the option value
  * @param[in] option_id Identifier value for option
  * @param[out] value Returned value of option
- * @return 0 if successful
+ * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
+ * error code otherwise
  */
-WS_DLL_PUBLIC int wtap_optionblock_get_option_string(wtap_optionblock_t block, guint option_id, char** value);
+WS_DLL_PUBLIC wtap_opttype_return_val
+wtap_optionblock_get_option_string(wtap_optionblock_t block, guint option_id, char** value);
 
-/** Set UINT64 option value to an option block
+/** Set UINT64 option value in an option block
  *
- * @param[in] block Block to add option
+ * @param[in] block Block in which to set the option value
  * @param[in] option_id Identifier value for option
  * @param[in] value New value of option
- * @return 0 if successful
+ * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
+ * error code otherwise
  */
-WS_DLL_PUBLIC int wtap_optionblock_set_option_uint64(wtap_optionblock_t block, guint option_id, guint64 value);
+WS_DLL_PUBLIC wtap_opttype_return_val
+wtap_optionblock_set_option_uint64(wtap_optionblock_t block, guint option_id, guint64 value);
 
 /** Get UINT64 option value from an option block
  *
- * @param[in] block Block to add option
+ * @param[in] block Block from which to get the option value
  * @param[in] option_id Identifier value for option
  * @param[out] value Returned value of option
- * @return 0 if successful
+ * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
+ * error code otherwise
  */
-WS_DLL_PUBLIC int wtap_optionblock_get_option_uint64(wtap_optionblock_t block, guint option_id, guint64* value);
+WS_DLL_PUBLIC wtap_opttype_return_val
+wtap_optionblock_get_option_uint64(wtap_optionblock_t block, guint option_id, guint64* value);
 
-/** Set UINT8 option value to an option block
+/** Set UINT8 option value in an option block
  *
- * @param[in] block Block to add option
+ * @param[in] block Block in which to set the option value
  * @param[in] option_id Identifier value for option
  * @param[in] value New value of option
- * @return 0 if successful
+ * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
+ * error code otherwise
  */
-WS_DLL_PUBLIC int wtap_optionblock_set_option_uint8(wtap_optionblock_t block, guint option_id, guint8 value);
+WS_DLL_PUBLIC wtap_opttype_return_val
+wtap_optionblock_set_option_uint8(wtap_optionblock_t block, guint option_id, guint8 value);
 
 /** Get UINT8 option value from an option block
  *
- * @param[in] block Block to add option
+ * @param[in] block Block from which to get the option value
  * @param[in] option_id Identifier value for option
  * @param[out] value Returned value of option
- * @return 0 if successful
+ * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
+ * error code otherwise
  */
-WS_DLL_PUBLIC int wtap_optionblock_get_option_uint8(wtap_optionblock_t block, guint option_id, guint8* value);
+WS_DLL_PUBLIC wtap_opttype_return_val
+wtap_optionblock_get_option_uint8(wtap_optionblock_t block, guint option_id, guint8* value);
 
-/** Set a "custom" option value to an option block
+/** Set a "custom" option value in an option block
  *
- * @param[in] block Block to add option
+ * @param[in] block Block in which to set the option value
  * @param[in] option_id Identifier value for option
  * @param[in] value New value of option
- * @return 0 if successful
+ * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
+ * error code otherwise
  */
-WS_DLL_PUBLIC int wtap_optionblock_set_option_custom(wtap_optionblock_t block, guint option_id, void* value);
+WS_DLL_PUBLIC wtap_opttype_return_val
+wtap_optionblock_set_option_custom(wtap_optionblock_t block, guint option_id, void* value);
 
 /** Get a "custom" option value from an option block
  *
- * @param[in] block Block to add option
+ * @param[in] block Block from which to get the option value
  * @param[in] option_id Identifier value for option
  * @param[out] value Returned value of option
- * @return 0 if successful
+ * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
+ * error code otherwise
  */
-WS_DLL_PUBLIC int wtap_optionblock_get_option_custom(wtap_optionblock_t block, guint option_id, void** value);
+WS_DLL_PUBLIC wtap_opttype_return_val
+wtap_optionblock_get_option_custom(wtap_optionblock_t block, guint option_id, void** value);
 
 /** Copy an option block to another.
  *