Tweak formatting and add minor updates to some comments.

git-svn-id: http://svn.digium.com/svn/asterisk/trunk@245269 f38db490-d61c-443f-a65b-d21fe96a405b

4 files changed, 40 insertions, 21 deletions

diff --git a/channels/sip/include/config_parser.h b/channels/sip/include/config_parser.h
index 128c24118..0b86188c6 100644
--- a/channels/sip/include/config_parser.h
+++ b/channels/sip/include/config_parser.h
@@ -24,27 +24,33 @@
 #ifndef _SIP_CONF_PARSE_H
 #define _SIP_CONF_PARSE_H
 
-
-/*! \brief Parse register=> line in sip.conf
+/*!
+ * \brief Parse register=> line in sip.conf
  *
- *  \retval 0 on success
- *  \retval -1 on failure
+ * \retval 0 on success
+ * \retval -1 on failure
  */
 int sip_parse_register_line(struct sip_registry *reg, int default_expiry, const char *value, int lineno);
 
 /*!
  * \brief parses a config line for a host with a transport
- *        i.e. tls://www.google.com:8056
  *
- *  \retval 0 on success
- *  \retval -1 on failure
+ * An example input would be: 
+ *     <code>tls://www.google.com:8056</code>
+ *
+ * \retval 0 on success
+ * \retval -1 on failure
  */
 int sip_parse_host(char *line, int lineno, char **hostname, int *portnum, enum sip_transport *transport);
 
-/*! \brief register config parsing tests */
+/*! 
+ * \brief register config parsing tests
+ */
 void sip_config_parser_register_tests(void);
 
-/*! \brief unregister config parsing tests */
+/*!
+ * \brief unregister config parsing tests
+ */
 void sip_config_parser_unregister_tests(void);
 
 #endif
diff --git a/channels/sip/include/reqresp_parser.h b/channels/sip/include/reqresp_parser.h
index c123fff2b..8f7d58898 100644
--- a/channels/sip/include/reqresp_parser.h
+++ b/channels/sip/include/reqresp_parser.h
@@ -22,7 +22,8 @@
 #ifndef _SIP_REQRESP_H
 #define _SIP_REQRESP_H
 
-/*! \brief parses a URI in its components.
+/*!
+ * \brief parses a URI in its components.
  *
  * \note
  * - Multiple scheme's can be specified ',' delimited. ex: "sip:,sips:"
@@ -38,20 +39,24 @@
  * \verbatim
  * general form we are expecting is sip:user:password;user-parameters@host:port;uri-parameters?headers
  * \endverbatim
- *
  */
 int parse_uri(char *uri, const char *scheme, char **ret_name, char **pass, char **domain, char **port, char **transport);
 
-/*! \brief  Get caller id name from SIP headers, copy into output buffer
+/*!
+ * \brief  Get caller id name from SIP headers, copy into output buffer
  *
- *  \retval input string pointer placed after display-name field if possible
+ * \retval input string pointer placed after display-name field if possible
  */
 const char *get_calleridname(const char *input, char *output, size_t outputsize);
 
-/*! \brief register request parsing tests */
+/*!
+ * \brief register request parsing tests
+ */
 void sip_request_parser_register_tests(void);
 
-/*! \brief unregister request parsing tests */
+/*!
+ * \brief unregister request parsing tests
+ */
 void sip_request_parser_unregister_tests(void);
 
 #endif
diff --git a/channels/sip/include/sip.h b/channels/sip/include/sip.h
index 9b605fe98..6ae1ce069 100644
--- a/channels/sip/include/sip.h
+++ b/channels/sip/include/sip.h
@@ -1207,6 +1207,8 @@ struct sip_peer {
  * or once the previously completed registration one expires).
  * The registration can be in one of many states, though at the moment
  * the handling is a bit mixed.
+ *
+ * \todo Convert this to astobj2
  */
 struct sip_registry {
 	ASTOBJ_COMPONENTS_FULL(struct sip_registry,1,1);
@@ -1259,7 +1261,11 @@ struct sip_threadinfo {
 	AST_LIST_HEAD_NOLOCK(, tcptls_packet) packet_q;
 };
 
-/*! \brief Definition of an MWI subscription to another server */
+/*!
+ * \brief Definition of an MWI subscription to another server
+ * 
+ * \todo Convert this to astobj2.
+ */
 struct sip_subscription_mwi {
 	ASTOBJ_COMPONENTS_FULL(struct sip_subscription_mwi,1,1);
 	AST_DECLARE_STRING_FIELDS(
diff --git a/channels/sip/include/sip_utils.h b/channels/sip/include/sip_utils.h
index 3a91564d1..86eb81933 100644
--- a/channels/sip/include/sip_utils.h
+++ b/channels/sip/include/sip_utils.h
@@ -22,12 +22,14 @@
 #ifndef _SIP_UTILS_H
 #define _SIP_UTILS_H
 
-
-/*! \brief converts ascii port to int representation. If no
- *  pt buffer is provided or the pt has errors when being converted
- *  to an int value, the port provided as the standard is used.
+/*! 
+ * \brief converts ascii port to int representation. 
+ *
+ * \arg pt[in] string that contains a port.
+ * \arg standard[in] port to return in case the port string input is NULL
+ *      or if there is a parsing error.
  *
- *  \retval positive numeric port 
+ * \return An integer port representation.
  */
 unsigned int port_str2int(const char *pt, unsigned int standard);