add doxygen comments to column-utils.h and do a slight code cleanup

svn path=/trunk/; revision=16066

1 files changed, 155 insertions, 25 deletions

diff --git a/epan/column-utils.h b/epan/column-utils.h
index c503ddcbc9..f5dda5c560 100644
--- a/epan/column-utils.h
+++ b/epan/column-utils.h
@@ -27,42 +27,172 @@
 
 #include <glib.h>
 
-#define COL_MAX_LEN 256
-#define COL_MAX_INFO_LEN 4096
-
 #include "gnuc_format_check.h"
 #include "column_info.h"
 #include "packet_info.h"
 
-/* Allocate all the data structures for constructing column data, given
-   the number of columns. */
-extern void	col_setup(column_info *, gint);
+/** Maximum length of columns (except COL_INFO).
+ * Internal, don't use this in dissectors!
+ */
+
+#define COL_MAX_LEN 256
+/** Maximum length of info columns (COL_INFO only).
+ * Internal, don't use this in dissectors!
+ */
+#define COL_MAX_INFO_LEN 4096
+
+
+/** Allocate all the data structures for constructing column data, given
+ * the number of columns.
+ *
+ * Internal, don't use this in dissectors!
+ */
+extern void	col_setup(column_info *cinfo, gint num_cols);
+
+/** Initialize the data structures for constructing column data.
+ *
+ * Internal, don't use this in dissectors!
+ */
+extern void	col_init(column_info *cinfo);
+
+/** Set the format of the "variable time format".
+ *
+ * Internal, don't use this in dissectors!
+ */
+extern void	col_set_cls_time(frame_data *, column_info *cinfo, gint col);
 
-/* Initialize the data structures for constructing column data. */
-extern void	col_init(column_info *);
+/** Fill in all columns of the given packet.
+ *
+ * Internal, don't use this in dissectors!
+ */
+extern void	col_fill_in(packet_info *pinfo);
 
 /* Utility routines used by packet*.c */
 
-extern gboolean	col_get_writable(column_info *);
-extern void	col_set_writable(column_info *, gboolean);
-extern gint	check_col(column_info *, gint);
-extern void	col_set_fence(column_info *, gint);
-extern void	col_clear(column_info *, gint);
-extern void	col_set_str(column_info *, gint, const gchar *);
-extern void	col_add_fstr(column_info *, gint, const gchar *, ...)
+/** Are the columns writable?
+ *
+ * @param cinfo the current packet row
+ * @return TRUE if it's writable, FALSE if not
+ */
+extern gboolean	col_get_writable(column_info *cinfo);
+
+/** Set the columns writable. 
+ *
+ * @param cinfo the current packet row
+ * @param writable TRUE if it's writable, FALSE if not
+ */
+extern void	col_set_writable(column_info *cinfo, gboolean writable);
+
+/** Check if the given column be filled with data.
+ *
+ * @param cinfo the current packet row
+ * @param col the column to use, e.g. COL_INFO
+ */
+extern gint	check_col(column_info *cinfo, gint col);
+
+/** Sets a fence for the current column content, 
+ * so this content won't be affected by further col_... function calls. 
+ *
+ * This can be useful if a protocol is more than once in a single packet,
+ * e.g. multiple HTTP calls in a single TCP packet.
+ *
+ * @param cinfo the current packet row
+ * @param col the column to use, e.g. COL_INFO
+ */
+extern void	col_set_fence(column_info *cinfo, gint col);
+
+/** Clears the text of a column element.
+ *
+ * @param cinfo the current packet row
+ * @param col the column to use, e.g. COL_INFO
+ */
+extern void	col_clear(column_info *cinfo, gint col);
+
+/** Set (replace) the text of a column element, the text won't be copied.
+ *
+ * Usually used to set const strings!
+ *
+ * @param cinfo the current packet row
+ * @param col the column to use, e.g. COL_INFO
+ * @param str the string to set
+ */
+extern void	col_set_str(column_info *cinfo, gint col, const gchar * str);
+
+/** Add (replace) the text of a column element, the text will be copied.
+ *
+ * @param cinfo the current packet row
+ * @param col the column to use, e.g. COL_INFO
+ * @param str the string to add
+ */
+extern void	col_add_str(column_info *cinfo, gint col, const gchar *str);
+
+/** Add (replace) the text of a column element, the text will be formatted and copied.
+ *
+ * Same function as col_add_str() but using a printf-like format string.
+ *
+ * @param cinfo the current packet row
+ * @param col the column to use, e.g. COL_INFO
+ * @param format the format string
+ * @param ... the variable number of parameters
+ */
+extern void	col_add_fstr(column_info *cinfo, gint col, const gchar *format, ...)
     GNUC_FORMAT_CHECK(printf, 3, 4);
-extern void	col_append_fstr(column_info *, gint, const gchar *, ...)
+
+/** Append the given text to a column element, the text will be copied.
+ *
+ * @param cinfo the current packet row
+ * @param col the column to use, e.g. COL_INFO
+ * @param str the string to append
+ */
+extern void	col_append_str(column_info *cinfo, gint col, const gchar *str);
+
+/** Append the given text to a column element, the text will be formatted and copied.
+ *
+ * Same function as col_append_str() but using a printf-like format string.
+ *
+ * @param cinfo the current packet row
+ * @param col the column to use, e.g. COL_INFO
+ * @param format the format string
+ * @param ... the variable number of parameters
+ */
+extern void	col_append_fstr(column_info *cinfo, gint col, const gchar *format, ...)
     GNUC_FORMAT_CHECK(printf, 3, 4);
-extern void	col_append_sep_fstr(column_info *, gint, const gchar *sep,
-		const gchar *fmt, ...)
-    GNUC_FORMAT_CHECK(printf, 4, 5);
-extern void	col_prepend_fstr(column_info *, gint, const gchar *, ...)
+
+/** Prepend the given text to a column element, the text will be formatted and copied.
+ *
+ * @param cinfo the current packet row
+ * @param col the column to use, e.g. COL_INFO
+ * @param format the format string
+ * @param ... the variable number of parameters
+ */
+extern void	col_prepend_fstr(column_info *cinfo, gint col, const gchar *format, ...)
     GNUC_FORMAT_CHECK(printf, 3, 4);
-extern void	col_add_str(column_info *, gint, const gchar *);
-extern void	col_append_str(column_info *, gint, const gchar *);
-extern void	col_append_sep_str(column_info *, gint, const gchar *sep,
+
+/** Append the given text (prepended by a separator) to a column element.
+ *
+ * Much like col_append_str() but will prepend the given separator if the column isn't empty.
+ *
+ * @param cinfo the current packet row
+ * @param col the column to use, e.g. COL_INFO
+ * @param sep the separator string or NULL for default: ", "
+ * @param str the string to append
+ */
+extern void	col_append_sep_str(column_info *cinfo, gint col, const gchar *sep,
 		const gchar *str);
-extern void	col_set_cls_time(frame_data *, column_info *, int);
-extern void	fill_in_columns(packet_info *);
+
+/** Append the given text (prepended by a separator) to a column element.
+ *
+ * Much like col_append_fstr() but will prepend the given separator if the column isn't empty.
+ *
+ * @param cinfo the current packet row
+ * @param col the column to use, e.g. COL_INFO
+ * @param sep the separator string or NULL for default: ", "
+ * @param format the format string
+ * @param ... the variable number of parameters
+ */
+extern void	col_append_sep_fstr(column_info *cinfo, gint col, const gchar *sep,
+		const gchar *format, ...)
+    GNUC_FORMAT_CHECK(printf, 4, 5);
+
 
 #endif /* __COLUMN_UTILS_H__ */