[hipl-commit] [trunk] Rev 3736: Filled in the missing doxygen comments for lib/core/debug.c.

  • From: Miika Komu <miika@xxxxxx>
  • To: hipl-commit@xxxxxxxxxxxxx
  • Date: Sun, 28 Feb 2010 16:13:33 +0200

Committer: Miika Komu <miika@xxxxxx>
Date: Sun Feb 28 16:13:37 2010 +0200
Revision: 3736
Revision-id: miika@xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Branch nick: trunk

Log:
  Filled in the missing doxygen comments for lib/core/debug.c.
  Aligned also the style of the existing doxygen comments with the current 
  ones and removed also an unreferenced function which didn't need comments.

Modified:
  D  lib/core/debug.c.doxyme
  M  lib/core/debug.c
  M  lib/core/debug.h

=== modified file 'lib/core/debug.c'
--- lib/core/debug.c    2010-02-11 09:57:04 +0000
+++ lib/core/debug.c    2010-02-28 14:13:37 +0000
@@ -5,15 +5,17 @@
  * stderr. This is done automatically using DEBUG flag in Makefile (see logtype
  * variable below).
  *
+ * Distributed under <a 
href="http://www.gnu.org/licenses/gpl2.txt";>GNU/GPL</a>.
+ *
  * Examples:
  *<pre>
- * INFO("test foobar");
- * INFO("%s\n", "debug test");
- * _INFO("%s\n", "this is not printed, but may be important in future");
- * ERROR("%s%d\n", "serious error!", 123);
- * DIE("%s\n", "really bad error, exiting!");
- * PERROR("socket");
- * HEXDUMP("foobar", data, len);
+ * HIP_INFO("test foobar");
+ * HIP_INFO("%s\n", "debug test");
+ * _HIP_INFO("%s\n", "this is not printed, but may be important in future");
+ * HIP_ERROR("%s%d\n", "serious error!", 123);
+ * HIP_DIE("%s\n", "really bad error, exiting!");
+ * HIP_PERROR("socket");
+ * HIP_HEXDUMP("foobar", data, len);
  *</pre>
  *
  * Adjusting of log types and format dynamically. (there really should not be a
@@ -122,8 +124,8 @@
 }
 
 /**
- * hip_set_auto_logdebug - The libraries read from hipd configuration file what
- *                          logging messages to display
+ * The libraries read from hipd configuration file what logging messages to 
display
+ *
  * @param name   pointer that contains the name of the hipd configuration file.
  * @return       zero on success, or negative error value on error.
  *
@@ -210,12 +212,14 @@
 }
 
 /**
- * hip_handle_log_error - handle errors generated by log handling
+ * handle errors generated by log handling
+ *
  * @param logtype the type of the log that generated the error (LOGTYPE_STDERR 
or
  *           LOGTYPE_SYSLOG)
  *
- * The default policy is to ignore errors (an alternative policy would
+ * @note The default policy is to ignore errors (an alternative policy would
  * be to e.g. exit).
+ * @note Do not use this function outside of this file at all.
  *
  */
 void hip_handle_log_error(int logtype)
@@ -224,16 +228,16 @@
 }
 
 /**
- * hip_vlog - "multiplexer" for correctly outputting all debug messages
+ * "multiplexer" for correctly outputting all debug messages
+ *
  * @param debug_level the urgency of the message (DEBUG_LEVEL_XX)
  * @param file the file from where the debug call was made
  * @param line the line of the debug call in the source file
  * @param function the name of function where the debug call is located
  * @param fmt the output format of the debug message as in printf(3)
  * @param args the variable argument list to be output
- *
- * This function is to be used only from the hip_debug(), hip_info(), etc
- * debugging functions.
+ * @note This function is to be used only from the hip_debug(), hip_info(), etc
+ * debugging functions. Do not use outside of this file.
  */
 void hip_vlog(int debug_level, const char *file, const int line,
               const char *function, const char *fmt, va_list args)
@@ -295,6 +299,18 @@
     hip_handle_log_error(logtype);
 }
 
+/**
+ * a wrapper that filters unnecessary logging for hip_vlog()
+ *
+ * @param debug_level the debug level
+ * @param file a file handle where to print
+ * @param line the line number
+ * @param function the calling function
+ * @param fmt printf formatting options
+ * @param ... variable number of strings or integers to print
+ *        according to the @c fmt parameter
+ * @note Do not call this function outside of this file at all.
+ */
 void hip_print_str(int debug_level,
                    const char *file,
                    int line,
@@ -314,11 +330,13 @@
 }
 
 /**
- * hip_debug_gl - output development (low level) debugging messages
- *                a debug group and a debug level can be given. Debug
- *                messages are only displayed if the debug group matches
- *                the current debug group and the debug leven is smaller
- *                than the current debug level.
+ * @brief output development (low level) debugging messages
+ *
+ * A debug group and a debug level can be given. Debug
+ * messages are only displayed if the debug group matches
+ * the current debug group and the debug leven is smaller
+ * than the current debug level.
+ *
  * @param debug_group the debug group which has to be matched
  * @param debug_level the debug level of the debug output
  * @param file the file from where the debug call was made
@@ -326,7 +344,7 @@
  * @param function the name of function where the debug call is located
  * @param fmt the output format of the debug message as in printf(3)
  *
- * The variable size argument list (...) is used as in printf(3).
+ * @note The variable size argument list (...) is used as in printf(3).
  * Do not call this function from the outside of the debug module,
  * use the HIP_DEBUG_GL macro instead.
  */
@@ -345,13 +363,14 @@
 }
 
 /**
- * hip_die - output a fatal error and exit
+ * output a fatal error and exit
+ *
  * @param file the file from where the debug call was made
  * @param line the line of the debug call in the source file
  * @param function the name of function where the debug call is located
  * @param fmt the output format of the debug message as in printf(3)
  *
- * The variable size argument list (...) is used as in printf(3).
+ * @note The variable size argument list (...) is used as in printf(3).
  * Do not call this function from the outside of the debug module,
  * use the HIP_DIE macro instead.
  */
@@ -366,13 +385,14 @@
 }
 
 /**
- * hip_error - output an error message (high level)
+ * output an error message (high level)
+ *
  * @param file the file from where the debug call was made
  * @param line the line of the debug call in the source file
  * @param function the name of function where the debug call is located
  * @param fmt the output format of the debug message as in printf(3)
  *
- * The variable size argument list (...) is used as in printf(3).
+ * @note The variable size argument list (...) is used as in printf(3).
  * Do not call this function from the outside of the debug module,
  * use the HIP_ERROR macro instead.
  */
@@ -388,13 +408,14 @@
 }
 
 /**
- * hip_perror_wrapper - a wrapper for perror(3) style calls
+ * a wrapper for perror(3) style calls
+ *
  * @param file the file from where the debug call was made
  * @param line the line of the debug call in the source file
  * @param function the name of function where the debug call is located
  * @param s the string as in perror(3)
  *
- * The newline is already included after the first line in favour of
+ * @note The newline is already included after the first line in favour of
  * the perror(3) syntax. Do not call this function from the outside of the
  * debug module, use the HIP_PERROR macro instead.
  */
@@ -405,7 +426,7 @@
 }
 
 /**
- * Prints a hexdump starting from address @c str of length @c len. Do not call
+ * Print raw hexdump starting from address @c str of length @c len. Do not call
  * this function from the outside of the debug module, use the HIP_HEXDUMP 
macro
  * instead.
  *
@@ -465,9 +486,22 @@
 }
 
 /**
+ * Print fancy hexdump starting from address @c str of length @c len. Do not 
call
+ * this function from the outside of the debug module, use the HIP_DUMP_PACKET 
macro
+ * instead.
+ *
  * Example of the output:
+ * <pre>
  * 13 88 94 64 0d b9 89 ff f3 cc 4c a1 80 11 05 94 ...d......L.....
  * 6c 3c 00 00 01 01 08 0a 00 10 a2 58 00 0f 98 30 l<.........X....
+ * </pre>
+ *
+ * @param file     the file from where the debug call was made
+ * @param line     the line of the debug call in the source file
+ * @param function the name of function where the debug call is located
+ * @param prefix   the prefix string will printed before the hexdump
+ * @param str      pointer to the beginning of the data to be hexdumped
+ * @param len      the length of the data to be hexdumped
  */
 int hip_hexdump_parsed(const char *file, int line, const char *function,
                        const char *prefix, const void *str, int len)
@@ -537,7 +571,7 @@
             hexdump_index += hexdump_written;
             HIP_ASSERT(hexdump_index + hexdump_count == hexdump_total_size);
 
-            // Wite the character in ascii to asciidump line
+            /* Write the character in ascii to ascii dump line */
             if (written > 32 && written < 127) {
                 memset(asciidump + line_index, written, 1);
             } else {
@@ -546,7 +580,7 @@
             line_index++;
             /* If line is full or input is all read, copy data to hexdump */
             if (line_index >= 16 || (char_index + 1) == len) {
-                // Add padding
+                /* Add padding */
                 _HIP_DEBUG("Line ready\n");
                 if ((char_index + 1) == len && pad_length > 0
                     && ((hexdump_index + line_index + pad_length) < 
hexdump_total_size)) {
@@ -595,7 +629,8 @@
 }
 
 /**
- * hip_print_sockaddr - print a socket address structure
+ * print a socket address structure
+ *
  * @param file the file from where the debug call was made
  * @param line the line of the debug call in the source file
  * @param function the name of function where the debug call is located
@@ -603,9 +638,9 @@
  * @param family the family of the sockaddr
  * @param sockaddr pointer to the sockaddr to be printed
  *
- * Do not call this function from the outside of the debug module, use the
- * HIP_DEBUG_SOCKADDR macro instead. Currently this function supports
- * only INET and INET6 addresses.
+ * @note Do not call this function from the outside of the debug module, use 
the
+ * HIP_DEBUG_SOCKADDR macro instead.
+ * @note Currently this function supports only INET and INET6 addresses.
  */
 void hip_print_sockaddr(const char *file, int line, const char *function,
                         const char *prefix,
@@ -645,6 +680,18 @@
     }
 }
 
+/**
+ * print an LSI
+ *
+ * @param debug_level the urgency of the message (DEBUG_LEVEL_XX)
+ * @param file the file from where the debug call was made
+ * @param line the line of the debug call in the source file
+ * @param function the name of function where the debug call is located
+ * @param str string to be printed before the HIT
+ * @param lsi the LSI to be printed
+ * @note Do not call this function directly. Instead, use the
+ *       HIP_DEBUG_LSI and HIP_INFO_LSI macros.
+ */
 void hip_print_lsi(int debug_level, const char *file, int line, const char 
*function,
                    const char *str, const struct in_addr *lsi)
 {
@@ -654,9 +701,16 @@
 }
 
 /**
- * hip_print_hit - print a HIT
+ * print a HIT
+ *
+ * @param debug_level the urgency of the message (DEBUG_LEVEL_XX)
+ * @param file the file from where the debug call was made
+ * @param line the line of the debug call in the source file
+ * @param function the name of function where the debug call is located
  * @param str string to be printed before the HIT
  * @param hit the HIT to be printed
+ * @note Do not call this function directly. Instead, use the
+ *       HIP_DEBUG_HIT and HIP_INFO_HIT macros.
  */
 void hip_print_hit(int debug_level, const char *file, int line, const char 
*function,
                    const char *str, const struct in6_addr *hit)
@@ -679,7 +733,11 @@
     }
 }
 
-/* THIS ONE WORKS -SAMU */
+/**
+ * display a LOCATOR parameter contents in a HIP control message
+ *
+ * @param in_msg the message where the LOCATOR parameter is located
+ */
 void hip_print_locator_addresses(struct hip_common *in_msg)
 {
     struct hip_locator *locator;
@@ -718,6 +776,11 @@
     }
 }
 
+/**
+ * display peer_addr_list_to_be_added structure from a host association
+ *
+ * @param entry the host association
+ */
 void hip_print_peer_addresses_to_be_added(hip_ha_t *entry)
 {
     hip_list_t *item = NULL, *tmp = NULL;
@@ -736,6 +799,11 @@
     }
 }
 
+/**
+ * display addresses_to_send_echo_request structure from a host association
+ *
+ * @param entry the host association
+ */
 void hip_print_addresses_to_send_update_request(hip_ha_t *ha)
 {
     hip_list_t *item = NULL, *tmp = NULL;
@@ -748,61 +816,3 @@
         HIP_DEBUG_IN6ADDR("", address);
     }
 }
-
-//add  by santtu
-/**
- * hip_print_hit - print a HIT
- * @param str string to be printed before the HIT
- * @param hit the HIT to be printed
- */
-void hip_print_locator(int debug_level, const char *file, int line, const char 
*function,
-                       const char *str, const struct hip_locator *locator)
-{
-/* XXTRASHXX Totally useless does anything but what it is supposed to do -SAMU 
*/
-
-    int n_addrs                                               = 0, i = 0;
-    struct hip_locator_info_addr_item *first_address_item     = NULL,
-    *locator_address_item                                     = NULL;
-    struct hip_locator_info_addr_item2 *locator_address_item2 = NULL;
-    /* locator = hip_get_param((struct hip_common *)in_msg,
-     * HIP_PARAM_LOCATOR);*/
-    if (locator) {
-        HIP_DEBUG("%s: \n", str);
-
-        n_addrs            = hip_get_locator_addr_item_count(locator);
-        HIP_DEBUG("there are  %d locator items \n", n_addrs);
-        first_address_item = hip_get_locator_first_addr_item(locator);
-
-        for (i = 0; i < n_addrs; i++) {
-            locator_address_item = (struct hip_locator_info_addr_item *)
-                                   hip_get_locator_item(first_address_item, i);
-            _HIP_HEXDUMP("LOC HEX", &locator_address_item[i],
-                         sizeof(struct hip_locator_info_addr_item));
-            HIP_DEBUG("locator items index %d, type is %d \n", i,
-                      locator_address_item->locator_type );
-            if (locator_address_item->locator_type == 
HIP_LOCATOR_LOCATOR_TYPE_IPV6) {
-                HIP_INFO_HIT("locator",
-                             (struct in6_addr *) 
&locator_address_item->address);
-                _HIP_HEXDUMP("Should be in6_addr",
-                             &locator_address_item[i].address,
-                             sizeof(struct in6_addr));
-            }
-            if (locator_address_item->locator_type == 
HIP_LOCATOR_LOCATOR_TYPE_ESP_SPI) {
-                HIP_INFO_HIT("LOCATOR from ESP SPI(type 1)",
-                             (struct in6_addr *) 
&locator_address_item->address);
-                _HIP_HEXDUMP("Should be in6_addr",
-                             &locator_address_item[i].address,
-                             sizeof(struct in6_addr));
-            }
-            if (locator_address_item->locator_type == 
HIP_LOCATOR_LOCATOR_TYPE_UDP) {
-                locator_address_item2 = (struct hip_locator_info_addr_item2 *) 
locator_address_item;
-                HIP_INFO_HIT("LOCATOR from UDP",
-                             (struct in6_addr *) 
&locator_address_item2->address);
-                HIP_DEBUG("LOCATOR port for UDP: %d\n",  
ntohs(locator_address_item2->port));
-                _HIP_HEXDUMP("Should be in6_addr",
-                             &locator_address_item[i].address,
-                             sizeof(struct in6_addr));
-            }
-        }
-    }
-}

=== modified file 'lib/core/debug.h'
--- lib/core/debug.h    2010-02-27 13:59:35 +0000
+++ lib/core/debug.h    2010-02-28 14:13:37 +0000
@@ -238,12 +238,6 @@
 void hip_print_locator_addresses(struct hip_common *);
 void hip_print_peer_addresses_to_be_added(hip_ha_t *);
 void hip_print_peer_addresses(hip_ha_t *);
-void hip_print_locator(int debug_level,
-                       const char *file,
-                       int line,
-                       const char *function,
-                       const char *str,
-                       const struct hip_locator *locator);
 void hip_print_addresses_to_send_update_request(hip_ha_t *);
 
 #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))

Other related posts:

  • » [hipl-commit] [trunk] Rev 3736: Filled in the missing doxygen comments for lib/core/debug.c. - Miika Komu