msg: documenting msg_parse_next_field() and adding @since to other new functions

darcs-hash:20061101162751-65a35-a2e72787188a06d8834d42972805c80f61458ccd.gz

libsofia-sip-ua/msg/msg_parser.c

@@ -1187,7 +1187,26 @@ msg_header_t *error_header_parse(msg_t *msg, msg_pub_t *mo,
   return h;
 }
 
-/** Complete this header field and parse next header field. */
+/** Complete this header field and parse next header field. 
+ *
+ * This function completes parsing a multi-field header like @Accept,
+ * @Contact, @Via or @Warning. It updates the shortcuts to header parameters
+ * (see msg_header_update_params()) and then scans for the next header field.
+ * If one is found, it calls the parsing function recursively.
+ *
+ * @param home 	 memory home used ot allocate 
+ *             	 new header structures and parameter lists
+ * @param prev 	 pointer to header structure already parsed
+ * @param s    	 header content to parse; should point to the area after 
+ *             	 current header field (either end of line or to a comma
+ *             	 separating header fields)
+ * @param slen 	 ignored
+ *
+ * @since New in @VERSION_1_12_4
+ *
+ * @retval >= 0 when successful
+ * @retval -1 upon an error
+ */
 issize_t msg_parse_next_field(su_home_t *home, msg_header_t *prev, 
 			      char *s, isize_t slen)
 {

libsofia-sip-ua/msg/msg_parser_util.c

@@ -1098,6 +1098,8 @@ int msg_header_update_params(msg_common_t *h, int clear)
  * @return
  * A pointer to item, or NULL if it was not found.
  *
+ * @since New in @VERSION_1_12_4
+ *
  * @sa msg_header_replace_item(), msg_header_remove_item(), 
  * @Allow, @AllowEvents
  */
@@ -1136,6 +1138,8 @@ char const *msg_header_find_item(msg_common_t const *h, char const *item)
  * @retval 1 if item was replaced
  * @retval -1 upon an error
  *
+ * @since New in @VERSION_1_12_4
+ *
  * @sa msg_header_remove_item(), @Allow, @AllowEvents,
  * msg_header_replace_param(), msg_header_remove_param(), 
  * #msg_common_t, #msg_header_t, #msg_list_t
@@ -1164,6 +1168,8 @@ int msg_header_replace_item(su_home_t *home,
  * @retval 1 if item was replaced
  * @retval -1 upon an error
  *
+ * @since New in @VERSION_1_12_4
+ *
  * @sa msg_header_replace_item(), @Allow, @AllowEvents,
  * msg_header_replace_param(), msg_header_remove_param(), 
  * #msg_common_t, #msg_header_t, #msg_list_t