Document to_str-int.h functions.

Change argument name of hex_to_str_back pad->len it seems to sounds better.
Make uint_to_str_back_len() value uint32, to be sure about required buffer size.

Change-Id: I48fd560683c5c0845cbb60813887a18328ec01e6
Reviewed-on: https://code.wireshark.org/review/1448
Reviewed-by: Evan Huus <eapache@gmail.com>
Reviewed-by: Anders Broman <a.broman58@gmail.com>

1 files changed, 114 insertions, 2 deletions

diff --git a/epan/to_str-int.h b/epan/to_str-int.h
index 3f6989c156..675c090c72 100644
--- a/epan/to_str-int.h
+++ b/epan/to_str-int.h
@@ -25,17 +25,129 @@
 
 #include <glib.h>
 
+/**
+ * word_to_hex()
+ *
+ * Output guint16 hex represetation to 'out', and return pointer after last character (out + 4).
+ * It always output full representation (padded with 0).
+ *
+ * String is not NUL terminated by this routine.
+ * There needs to be at least 4 bytes in the buffer.
+ */
 char *word_to_hex(char *out, guint16 word);
+
+/**
+ * word_to_hex_npad()
+ *
+ * Output guint16 hex represetation to 'out', and return pointer after last character.
+ * Value is not padded.
+ *
+ * String is not NUL terminated by this routine.
+ * There needs to be at least 4 bytes in the buffer.
+ */
 char *word_to_hex_npad(char *out, guint16 word);
+
+/**
+ * dword_to_hex_punct()
+ *
+ * Output guint32 hex represetation to 'out', and return pointer after last character.
+ * Each byte will be seperated with punct character (cannot be NUL).
+ * It always output full representation (padded with 0).
+ *
+ * String is not NUL terminated by this routine.
+ * There needs to be at least 11 bytes in the buffer.
+ */
 char *dword_to_hex_punct(char *out, guint32 dword, char punct);
+
+/**
+ * dword_to_hex()
+ *
+ * Output guint32 hex represetation to 'out', and return pointer after last character.
+ * It always output full representation (padded with 0).
+ *
+ * String is not NUL terminated by this routine.
+ * There needs to be at least 8 bytes in the buffer.
+ */
 char *dword_to_hex(char *out, guint32 dword);
+
+/**
+ * bytes_to_hexstr()
+ *
+ * Output hex represetation of guint8 ad array, and return pointer after last character.
+ * It always output full representation (padded with 0).
+ *
+ * String is not NUL terminated by this routine.
+ * There needs to be at least len * 2 bytes in the buffer.
+ */
 char *bytes_to_hexstr(char *out, const guint8 *ad, guint32 len);
+
+/**
+ * bytes_to_hexstr_punct()
+ *
+ * Output hex represetation of guint8 ad array, and return pointer after last character.
+ * Each byte will be seperated with punct character (cannot be NUL).
+ * It always output full representation (padded with 0).
+ *
+ * String is not NUL terminated by this routine.
+ * There needs to be at least len * 3 - 1 bytes in the buffer.
+ */
 char *bytes_to_hexstr_punct(char *out, const guint8 *ad, guint32 len, char punct);
 
+/**
+ * oct_to_str_back()
+ *
+ * Output guint32 octal representation backward (last character will be written on ptr - 1),
+ * and return pointer to first character.
+ *
+ * String is not NUL terminated by this routine.
+ * There needs to be at least 12 bytes in the buffer.
+ */
 char *oct_to_str_back(char *ptr, guint32 value);
-char *hex_to_str_back(char *ptr, int pad, guint32 value);
+
+/**
+ * hex_to_str_back()
+ *
+ * Output guint32 hex representation backward (last character will be written on ptr - 1),
+ * and return pointer to first character.
+ * This routine will output for sure (can output more) 'len' decimal characters (number padded with '0').
+ *
+ * String is not NUL terminated by this routine.
+ * There needs to be at least 2 + MAX(8, len) bytes in the buffer.
+ */
+char *hex_to_str_back(char *ptr, int len, guint32 value);
+
+/**
+ * uint_to_str_back()
+ *
+ * Output guint32 decimal representation backward (last character will be written on ptr - 1),
+ * and return pointer to first character.
+ *
+ * String is not NUL terminated by this routine.
+ * There needs to be at least 10 bytes in the buffer.
+ */
 char *uint_to_str_back(char *ptr, guint32 value);
-char *uint_to_str_back_len(char *ptr, unsigned int value, int len);
+
+/**
+ * uint_to_str_back_len()
+ *
+ * Output guint32 decimal representation backward (last character will be written on ptr - 1),
+ * and return pointer to first character.
+ * This routine will output for sure (can output more) 'len' decimal characters (number padded with '0').
+ *
+ * String is not NUL terminated by this routine.
+ * There needs to be at least MAX(10, len) bytes in the buffer.
+ */
+char *uint_to_str_back_len(char *ptr, guint32 value, int len);
+
+/**
+ * int_to_str_back()
+ *
+ * Output gint32 decimal representation backward (last character will be written on ptr - 1),
+ * and return pointer to first character.
+ *
+ * String is not NUL terminated by this routine.
+ * There needs to be at least 11 bytes in the buffer.
+ */
 char *int_to_str_back(char *ptr, gint32 value);
 
 #endif /* __TO_STR_INT_H__ */