[Asterisk-code-review] channels: Fix for Doxygen. (asterisk[16])

Alexander Traud asteriskteam at digium.com
Fri Nov 19 03:48:56 CST 2021


Alexander Traud has uploaded this change for review. ( https://gerrit.asterisk.org/c/asterisk/+/17560 )


Change subject: channels: Fix for Doxygen.
......................................................................

channels: Fix for Doxygen.

ASTERISK-29762

Change-Id: Ia8811ac12b93ff8c18164699c6fbc604cb0a23f7
---
M channels/chan_console.c
M channels/chan_dahdi.c
M channels/chan_iax2.c
M channels/chan_motif.c
M channels/chan_pjsip.c
M channels/chan_sip.c
M channels/dahdi/bridge_native_dahdi.c
M channels/iax2/codec_pref.c
M channels/iax2/include/firmware.h
M channels/sig_analog.c
M channels/sip/config_parser.c
M channels/sip/include/reqresp_parser.h
M channels/sip/include/route.h
M channels/sip/include/sip.h
M channels/sip/reqresp_parser.c
15 files changed, 94 insertions(+), 163 deletions(-)



  git pull ssh://gerrit.asterisk.org:29418/asterisk refs/changes/60/17560/1

diff --git a/channels/chan_console.c b/channels/chan_console.c
index a5ee2db..1d1d94c 100644
--- a/channels/chan_console.c
+++ b/channels/chan_console.c
@@ -552,7 +552,7 @@
 	return start_stream(pvt);
 }
 
-/*
+/*!
  * \brief Implementation of the ast_channel_tech read() callback
  *
  * Calling this function is harmless.  However, if it does get called, it
diff --git a/channels/chan_dahdi.c b/channels/chan_dahdi.c
index 941f646..d8dc90d 100644
--- a/channels/chan_dahdi.c
+++ b/channels/chan_dahdi.c
@@ -1799,8 +1799,6 @@
  *
  * \param p DAHDI private pointer
  * \param chan Channel associated with the private pointer
- *
- * \return Nothing
  */
 static void dahdi_ami_channel_event(struct dahdi_pvt *p, struct ast_channel *chan)
 {
@@ -1827,8 +1825,6 @@
  *
  * \param pvt DAHDI private pointer
  * \param chan Channel associated with the private pointer
- *
- * \return Nothing
  */
 static void my_ami_channel_event(void *pvt, struct ast_channel *chan)
 {
@@ -2221,6 +2217,7 @@
  * \note this variant of dahdi should only be used in conjunction with ast_callid_threadstorage_auto()
  *
  * \param callid_created value returned from ast_callid_threadstorage_auto()
+ * \param i, state, startpbx, idx, law, assignedids, requestor, callid
  */
 static struct ast_channel *dahdi_new_callid_clean(struct dahdi_pvt *i, int state, int startpbx, int idx, int law, const struct ast_assigned_ids *assignedids, const struct ast_channel *requestor, ast_callid callid, int callid_created);
 
@@ -2306,8 +2303,6 @@
  * \since 1.8
  *
  * \param p Channel private control structure.
- *
- * \return Nothing
  */
 static void my_pri_ss7_open_media(void *p)
 {
@@ -2359,8 +2354,6 @@
  * \param dial_string String to pass to DAHDI to dial.
  *
  * \note The channel private lock needs to be held when calling.
- *
- * \return Nothing
  */
 static void my_pri_dial_digits(void *p, const char *dial_string)
 {
@@ -2819,8 +2812,6 @@
  *
  * \param pvt DAHDI private structure
  * \param caller Caller-id information to set.
- *
- * \return Nothing
  */
 static void my_set_callerid(void *pvt, const struct ast_party_caller *caller)
 {
@@ -2855,8 +2846,6 @@
  *
  * \param pvt DAHDI private structure
  * \param dnid Dialed Number Identifier string.
- *
- * \return Nothing
  */
 static void my_set_dnid(void *pvt, const char *dnid)
 {
@@ -2874,8 +2863,6 @@
  *
  * \param pvt DAHDI private structure
  * \param rdnis Redirecting Directory Number Information Service (RDNIS) string.
- *
- * \return Nothing
  */
 static void my_set_rdnis(void *pvt, const char *rdnis)
 {
@@ -2907,8 +2894,6 @@
  *
  * The routine will check to see if the ISDN channel restriction is already
  * in the original dialstring.
- *
- * \return Nothing
  */
 static void my_pri_make_cc_dialstring(void *priv, char *buf, size_t buf_size)
 {
@@ -2953,8 +2938,6 @@
  *
  * \param pri Asterisk D channel control structure.
  *
- * \return Nothing
- *
  * \note Assumes the pri->lock is already obtained.
  */
 static void dahdi_pri_update_span_devstate(struct sig_pri_span *pri)
@@ -3018,8 +3001,6 @@
  * \internal
  * \brief Reference this module.
  * \since 1.8
- *
- * \return Nothing
  */
 static void my_module_ref(void)
 {
@@ -3032,8 +3013,6 @@
  * \internal
  * \brief Unreference this module.
  * \since 1.8
- *
- * \return Nothing
  */
 static void my_module_unref(void)
 {
@@ -3089,8 +3068,6 @@
  *
  * \param linkset Controlling linkset for the channel.
  * \param which Link index of the signaling channel.
- *
- * \return Nothing
  */
 static void my_handle_link_exception(struct sig_ss7_linkset *linkset, int which)
 {
@@ -3283,8 +3260,6 @@
  * \param thereornot This argument should simply be set to 1 or 0, to indicate
  *      whether there are messages waiting or not.
  *
- *  \return nothing
- *
  * This function does two things:
  *
  * 1) It generates an internal Asterisk event notifying any other module that
@@ -3463,8 +3438,6 @@
  * \note
  * Because deadlock avoidance may have been necessary, you need to confirm
  * the state of things before continuing.
- *
- * \return Nothing
  */
 static void dahdi_lock_sub_owner(struct dahdi_pvt *pvt, int sub_idx)
 {
@@ -5280,8 +5253,6 @@
  * Any duplicates are inserted after the existing entries.
  *
  * \note The new interface must not already be in the list.
- *
- * \return Nothing
  */
 static void dahdi_iflist_insert(struct dahdi_pvt *pvt)
 {
@@ -5330,8 +5301,6 @@
  * \note
  * The given interface structure can be either in the interface list or a stand alone
  * structure that has not been put in the list if the next and prev pointers are NULL.
- *
- * \return Nothing
  */
 static void dahdi_iflist_extract(struct dahdi_pvt *pvt)
 {
@@ -5371,8 +5340,6 @@
  * Any duplicates are inserted after the existing entries.
  *
  * \note The new interface must not already be in the list.
- *
- * \return Nothing
  */
 static void dahdi_nobch_insert(struct sig_pri_span *pri, struct dahdi_pvt *pvt)
 {
@@ -5424,8 +5391,6 @@
  * \note
  * The given interface structure can be either in the interface list or a stand alone
  * structure that has not been put in the list if the next and prev pointers are NULL.
- *
- * \return Nothing
  */
 static void dahdi_nobch_extract(struct sig_pri_span *pri, struct dahdi_pvt *pvt)
 {
@@ -5459,8 +5424,6 @@
  * \since 1.8
  *
  * \param pvt chan_dahdi private interface structure to unlink.
- *
- * \return Nothing
  */
 static void dahdi_unlink_pri_pvt(struct dahdi_pvt *pvt)
 {
@@ -5491,8 +5454,6 @@
  * \since 1.8
  *
  * \param pvt chan_dahdi private interface structure to unlink.
- *
- * \return Nothing
  */
 static void dahdi_unlink_ss7_pvt(struct dahdi_pvt *pvt)
 {
@@ -5522,8 +5483,6 @@
  * \brief Unlink the channel interface from the MFC/R2 private pointer array.
  *
  * \param pvt chan_dahdi private interface structure to unlink.
- *
- * \return Nothing
  */
 static void dahdi_unlink_mfcr2_pvt(struct dahdi_pvt *pvt)
 {
@@ -13136,8 +13095,6 @@
  * \param pri sig_pri PRI control structure.
  *
  * \note Assumes the pri->lock is already obtained.
- *
- * \return Nothing
  */
 static void my_pri_init_config(void *priv, struct sig_pri_span *pri)
 {
@@ -17510,8 +17467,6 @@
  * \details
  * The core will call this function upon completion
  * or failure of CC.
- *
- * \return Nothing
  */
 static void dahdi_pri_cc_agent_destructor(struct ast_cc_agent *agent)
 {
@@ -19343,8 +19298,6 @@
  *
  * \param dest Destination.
  * \param src Source.
- *
- * \return Nothing
  */
 static void deep_copy_dahdi_chan_conf(struct dahdi_chan_conf *dest, const struct dahdi_chan_conf *src)
 {
diff --git a/channels/chan_iax2.c b/channels/chan_iax2.c
index 5233aef..6d8ad30 100644
--- a/channels/chan_iax2.c
+++ b/channels/chan_iax2.c
@@ -3099,7 +3099,7 @@
 	return 0;
 }
 
-/*
+/*!
  * \note Calling this function while holding another pvt lock can cause a deadlock.
  */
 static int __find_callno(unsigned short callno, unsigned short dcallno, struct ast_sockaddr *addr, int new, int sockfd, int return_locked, int check_dcallno)
diff --git a/channels/chan_motif.c b/channels/chan_motif.c
index 8da2d16..5ec348d 100644
--- a/channels/chan_motif.c
+++ b/channels/chan_motif.c
@@ -328,7 +328,7 @@
 
 static struct ast_sched_context *sched; /*!< Scheduling context for RTCP */
 
-/* \brief Asterisk core interaction functions */
+/*! \brief Asterisk core interaction functions */
 static struct ast_channel *jingle_request(const char *type, struct ast_format_cap *cap, const struct ast_assigned_ids *assignedids, const struct ast_channel *requestor, const char *data, int *cause);
 static int jingle_sendtext(struct ast_channel *ast, const char *text);
 static int jingle_digit_begin(struct ast_channel *ast, char digit);
diff --git a/channels/chan_pjsip.c b/channels/chan_pjsip.c
index 4206974..1295c39 100644
--- a/channels/chan_pjsip.c
+++ b/channels/chan_pjsip.c
@@ -83,7 +83,7 @@
 {
 }
 
-/* \brief Asterisk core interaction functions */
+/*! \brief Asterisk core interaction functions */
 static struct ast_channel *chan_pjsip_request(const char *type, struct ast_format_cap *cap, const struct ast_assigned_ids *assignedids, const struct ast_channel *requestor, const char *data, int *cause);
 static struct ast_channel *chan_pjsip_request_with_stream_topology(const char *type,
 	struct ast_stream_topology *topology, const struct ast_assigned_ids *assignedids,
diff --git a/channels/chan_sip.c b/channels/chan_sip.c
index f242dd9..0e7a932 100644
--- a/channels/chan_sip.c
+++ b/channels/chan_sip.c
@@ -26,7 +26,7 @@
  * \arg \ref AstCREDITS
  *
  * Implementation of RFC 3261 - without S/MIME, and experimental TCP and TLS support
- * Configuration file \link Config_sip sip.conf \endlink
+ * Configuration file \ref sip.conf "Config_sip"
  *
  * ********** IMPORTANT *
  * \note TCP/TLS support is EXPERIMENTAL and WILL CHANGE. This applies to configuration
@@ -2304,7 +2304,7 @@
 	return 0;
 }
 
-/*
+/*!
  * \brief Determine what, if any, CC has been offered and queue a CC frame if possible
  *
  * After taking care of some formalities to be sure that this call is eligible for CC,
@@ -2404,7 +2404,7 @@
 };
 
 /*! \brief Append to SIP dialog history
-	\return Always returns 0 */
+	\retval 0 always */
 #define append_history(p, event, fmt , args... )	append_history_full(p, "%-15s " fmt, event, ## args)
 
 /*! \brief map from an integer value to a string.
@@ -2843,7 +2843,6 @@
  * 1) The message is a full SIP request
  * 2) The message is a partial SIP request
  * 3) The message contains a full SIP request along with another partial request
- * \param data The unparsed incoming SIP message.
  * \param request The resulting request with extra fragments removed.
  * \param overflow If the message contains more than a full request, this is the remainder of the message
  * \return The resulting integrity of the message
@@ -2910,10 +2909,13 @@
 }
 
 /*!
+ * \internal
  * \brief Read SIP request or response from a TCP/TLS connection
  *
  * \param req The request structure to be filled in
  * \param tcptls_session The TCP/TLS connection from which to read
+ * \param authenticated 0 means unauthenticated
+ * \param start timeout for unauthenticated server sessions
  * \retval -1 Failed to read data
  * \retval 0 Successfully read data
  */
@@ -3270,7 +3272,7 @@
 	}
 }
 
-/* \brief Unlink all marked peers from ao2 containers */
+/*! \brief Unlink all marked peers from ao2 containers */
 static void unlink_marked_peers_from_tables(void)
 {
 	unlink_peers_from_tables(SIP_PEERS_MARKED);
@@ -3281,7 +3283,9 @@
 	unlink_peers_from_tables(SIP_PEERS_ALL);
 }
 
-/*! \brief maintain proper refcounts for a sip_pvt's outboundproxy
+/*!
+ * \internal
+ * \brief maintain proper refcounts for a sip_pvt's outboundproxy
  *
  * This function sets pvt's outboundproxy pointer to the one referenced
  * by the proxy parameter. Because proxy may be a refcounted object, and
@@ -3290,7 +3294,6 @@
  *
  * \param pvt The sip_pvt for which we wish to set the outboundproxy
  * \param proxy The sip_proxy which we will point pvt towards.
- * \return Returns void
  */
 static void ref_proxy(struct sip_pvt *pvt, struct sip_proxy *proxy)
 {
@@ -4272,7 +4275,8 @@
 /*!
  * \internal
  * \brief Transmit packet with retransmits
- * \return 0 on success, -1 on failure to allocate packet
+ * \retval 0 on success
+ * \retval -1 on failure to allocate packet.
  */
 static enum sip_result __sip_reliable_xmit(struct sip_pvt *p, uint32_t seqno, int resp, struct ast_str *data, int fatal, int sipmethod)
 {
@@ -6038,7 +6042,8 @@
 }
 
 /*! \brief Initialize RTP portion of a dialog
- * \return -1 on failure, 0 on success
+ * \retval -1 on failure.
+ * \retval 0 on success.
  */
 static int dialog_initialize_rtp(struct sip_pvt *dialog)
 {
@@ -6132,7 +6137,8 @@
  *	This function copies data from peer to the dialog, so we don't have to look up the peer
  *	again from memory or database during the life time of the dialog.
  *
- * \return -1 on error, 0 on success.
+ * \retval -1 on error.
+ * \retval 0 on success.
  *
  */
 static int create_addr_from_peer(struct sip_pvt *dialog, struct sip_peer *peer)
@@ -6839,8 +6845,8 @@
  *
  * Thought: For realtime, we should probably update storage with inuse counter...
  *
- * \return 0 if call is ok (no call limit, below threshold)
- *	-1 on rejection of call
+ * \retval 0 if call is ok (no call limit, below threshold).
+ * \retval -1 on rejection of call.
  *
  */
 static int update_call_counter(struct sip_pvt *fup, int event)
@@ -8856,8 +8862,6 @@
  *
  * \param pvt SIP private structure to change callid
  * \param callid Specified new callid to use.  NULL if generate new callid.
- *
- * \return Nothing
  */
 static void change_callid_pvt(struct sip_pvt *pvt, const char *callid)
 {
@@ -9144,7 +9148,7 @@
 	return 0;
 }
 
-/* \brief arguments used for Request/Response to matching */
+/*! \brief arguments used for Request/Response to matching */
 struct match_req_args {
 	int method;
 	const char *callid;
@@ -9171,7 +9175,7 @@
 	SIP_REQ_FORKED, /* An outgoing request has been forked as result of receiving two differing 200ok responses. */
 };
 
-/*
+/*!
  * \brief Match a incoming Request/Response to a dialog
  *
  * \retval enum match_req_res indicating if the dialog matches the arg
@@ -10048,7 +10052,8 @@
 /*!
   \brief Determine whether a SIP message contains an SDP in its body
   \param req the SIP request to process
-  \return 1 if SDP found, 0 if not found
+  \retval 1 if SDP found.
+  \retval 0 if not found.
 
   Also updates req->sdp_start and req->sdp_count to indicate where the SDP
   lives in the message body.
@@ -12777,7 +12782,9 @@
 
 /*!
  \brief Extract domain from SIP To/From header
- \return -1 on error, 1 if domain string is empty, 0 if domain was properly extracted
+ \retval -1 on error.
+ \retval 1 if domain string is empty.
+ \retval 0 if domain was properly extracted.
  \note TODO: Such code is all over SIP channel, there is a sense to organize
       this patern in one function
 */
@@ -12883,8 +12890,6 @@
  * \brief Destroy all additional MESSAGE headers.
  *
  * \param pvt SIP private dialog struct.
- *
- * \return Nothing
  */
 static void destroy_msg_headers(struct sip_pvt *pvt)
 {
@@ -12902,8 +12907,6 @@
  * \param pvt SIP private dialog struct.
  * \param hdr_name Name of header for MESSAGE.
  * \param hdr_value Value of header for MESSAGE.
- *
- * \return Nothing
  */
 static void add_msg_header(struct sip_pvt *pvt, const char *hdr_name, const char *hdr_value)
 {
@@ -14122,7 +14125,7 @@
 }
 
 /*! \brief Used for 200 OK and 183 early media
-	\return Will return XMIT_ERROR for network errors.
+	\retval XMIT_ERROR for network errors.
 */
 static int transmit_response_with_sdp(struct sip_pvt *p, const char *msg, const struct sip_request *req, enum xmittype reliable, int oldsdp, int rpid)
 {
@@ -14273,7 +14276,7 @@
 	return send_request(p, &req, XMIT_CRITICAL, p->ocseq);
 }
 
-/* \brief Remove URI parameters at end of URI, not in username part though */
+/*! \brief Remove URI parameters at end of URI, not in username part though */
 static char *remove_uri_parameters(char *uri)
 {
 	char *atsign;
@@ -19977,7 +19980,9 @@
 }
 
 /*! \brief  Report Peer status in character string
- *  \return 0 if peer is unreachable, 1 if peer is online, -1 if unmonitored
+ * \retval 0 if peer is unreachable.
+ * \retval 1 if peer is online.
+ * \retval -1 if unmonitored.
  */
 
 
@@ -23058,7 +23063,7 @@
 }
 
 /*! \brief  reply to authentication for outbound registrations
-\return	Returns -1 if we have no auth
+\retval	-1 if we have no auth
 \note	This is used for register= servers in sip.conf, SIP proxies we register
 	with  for receiving calls from.  */
 static int reply_digest(struct sip_pvt *p, struct sip_request *req, char *header, int sipmethod,  char *digest, int digest_len)
@@ -23134,7 +23139,7 @@
 }
 
 /*! \brief  Build reply digest
-\return	Returns -1 if we have no auth
+\retval -1 if we have no auth
 \note	Build digest challenge for authentication of registrations and calls
 	Also used for authentication of BYE
 */
@@ -23977,8 +23982,6 @@
  * \param cause Hangup cause to queue.  Zero if no cause.
  *
  * \pre p and p->owner are locked.
- *
- * \return Nothing
  */
 static void sip_queue_hangup_cause(struct sip_pvt *p, int cause)
 {
@@ -24562,7 +24565,7 @@
 	}
 }
 
-/* \brief Handle SIP response in NOTIFY transaction
+/*! \brief Handle SIP response in NOTIFY transaction
        We've sent a NOTIFY, now handle responses to it
   */
 static void handle_response_notify(struct sip_pvt *p, int resp, const char *rest, struct sip_request *req, uint32_t seqno)
@@ -24616,7 +24619,7 @@
 	}
 }
 
-/* \brief Handle SIP response in SUBSCRIBE transaction */
+/*! \brief Handle SIP response in SUBSCRIBE transaction */
 static void handle_response_subscribe(struct sip_pvt *p, int resp, const char *rest, struct sip_request *req, uint32_t seqno)
 {
 	if (p->subscribed == CALL_COMPLETION) {
@@ -24703,7 +24706,7 @@
 	}
 }
 
-/* \brief Handle SIP response in REFER transaction
+/*! \brief Handle SIP response in REFER transaction
 	We've sent a REFER, now handle responses to it
   */
 static void handle_response_refer(struct sip_pvt *p, int resp, const char *rest, struct sip_request *req, uint32_t seqno)
@@ -25067,7 +25070,7 @@
 /*!
  * \internal
  * \brief Handle auth requests to a MESSAGE request
- * \return TRUE if authentication failed.
+ * \retval TRUE if authentication failed.
  */
 static int do_message_auth(struct sip_pvt *p, int resp, const char *rest, struct sip_request *req, uint32_t seqno)
 {
@@ -25650,8 +25653,8 @@
 
 /*! \brief Get tag from packet
  *
- * \return Returns the pointer to the provided tag buffer,
- *         or NULL if the tag was not found.
+ * \return pointer to the provided tag buffer.
+ * \retval NULL if the tag was not found.
  */
 static const char *gettag(const struct sip_request *req, const char *header, char *tagbuf, int tagbufsize)
 {
@@ -26201,8 +26204,9 @@
 	return 0;
 }
 
-/*
- * \internal \brief Check Session Timers for an INVITE request
+/*!
+ * \internal
+ * \brief Check Session Timers for an INVITE request
  *
  * \retval 0 ok
  * \retval -1 failure
@@ -27245,7 +27249,7 @@
  * we may send out.
  *
  * \param chan The new outbound channel
- * \param user_data A blind_transfer_cb_data struct
+ * \param user_data_wrapper A blind_transfer_cb_data struct
  * \param transfer_type Unused
  */
 static void blind_transfer_cb(struct ast_channel *chan, struct transfer_channel_data *user_data_wrapper,
@@ -29380,7 +29384,8 @@
 
 /*! \brief Read data from SIP UDP socket
 \note sipsock_read locks the owner channel while we are processing the SIP message
-\return 1 on error, 0 on success
+\retval 1 on error.
+\retval 0 on success.
 \note Successful messages is connected to SIP call and forwarded to handle_incoming()
 */
 static int sipsock_read(int *id, int fd, short events, void *ignore)
@@ -29757,7 +29762,8 @@
  *  \note Both peer and associated sip_pvt must be unlocked prior to calling this function.
  *  It's possible that this function will get called during peer destruction as final messages
  *  are processed.  The peer will still be valid however.
- *  \returns -1 on failure, 0 on success
+ *  \retval -1 on failure.
+ *  \retval 0 on success.
  */
 static int sip_send_mwi_to_peer(struct sip_peer *peer, int cache_only)
 {
@@ -31076,7 +31082,7 @@
 
 /*!
   \brief Handle T.38 configuration options common to users and peers
-  \returns non-zero if any config options were handled, zero otherwise
+  \return non-zero if any config options were handled, zero otherwise
 */
 static int handle_t38_options(struct ast_flags *flags, struct ast_flags *mask, struct ast_variable *v,
 			      unsigned int *maxdatagram)
@@ -31121,7 +31127,7 @@
   \param flags array of three struct ast_flags
   \param mask array of three struct ast_flags
   \param v linked list of config variables to process
-  \returns non-zero if any config options were handled, zero otherwise
+  \return non-zero if any config options were handled, zero otherwise
 */
 static int handle_common_options(struct ast_flags *flags, struct ast_flags *mask, struct ast_variable *v)
 {
@@ -31355,8 +31361,6 @@
  * \brief Realm authentication container destructor.
  *
  * \param obj Container object to destroy.
- *
- * \return Nothing
  */
 static void destroy_realm_authentication(void *obj)
 {
@@ -31375,8 +31379,6 @@
  * \param credentials Realm authentication container to create/add authentication credentials.
  * \param configuration Credential configuration value.
  * \param lineno Line number in config file.
- *
- * \return Nothing
  */
 static void add_realm_authentication(struct sip_auth_container **credentials, const char *configuration, int lineno)
 {
diff --git a/channels/dahdi/bridge_native_dahdi.c b/channels/dahdi/bridge_native_dahdi.c
index 46fc726..73f2fcf 100644
--- a/channels/dahdi/bridge_native_dahdi.c
+++ b/channels/dahdi/bridge_native_dahdi.c
@@ -133,8 +133,6 @@
  *
  * \param bridge What to operate upon.
  *
- * \return Nothing
- *
  * \note On entry, bridge is already locked.
  */
 static void native_stop(struct ast_bridge *bridge)
@@ -177,8 +175,6 @@
  *
  * \param bridge What to operate upon.
  *
- * \return Nothing
- *
  * \note On entry, bridge is already locked.
  */
 static void native_request_stop(struct ast_bridge *bridge)
@@ -476,8 +472,6 @@
  *
  * \param bridge What to operate upon.
  *
- * \return Nothing
- *
  * \note On entry, bridge may or may not already be locked.
  * However, it can be accessed as if it were locked.
  */
@@ -885,8 +879,6 @@
  * \internal
  * \brief Destroy the DAHDI native bridge support.
  * \since 12.0.0
- *
- * \return Nothing
  */
 void dahdi_native_unload(void)
 {
diff --git a/channels/iax2/codec_pref.c b/channels/iax2/codec_pref.c
index 7811ca8..21cc8b3 100644
--- a/channels/iax2/codec_pref.c
+++ b/channels/iax2/codec_pref.c
@@ -395,8 +395,6 @@
  * \param pref Codec preference list to append the given bitfield.
  * \param bitfield Format bitfield to append.
  * \param framing Framing size of the codec.
- *
- * \return Nothing
  */
 static void iax2_codec_pref_append_bitfield(struct iax2_codec_pref *pref, uint64_t bitfield, unsigned int framing)
 {
diff --git a/channels/iax2/include/firmware.h b/channels/iax2/include/firmware.h
index a211c5d..fba1afb 100644
--- a/channels/iax2/include/firmware.h
+++ b/channels/iax2/include/firmware.h
@@ -32,8 +32,6 @@
  *
  * Searches the IAX firmware directory, adding new firmware that is available
  * and removing firmware that is no longer available.
- *
- * \return Nothing
  */
 void iax_firmware_reload(void);
 
@@ -95,8 +93,6 @@
  *
  * The \c callback function receives a pointer to the firmware header and the
  * value of the \c user_data argument that was passed in, which may be \c NULL.
- *
- * \return Nothing
  */
 void iax_firmware_traverse(const char *prefix,
 	int (*callback)(struct ast_iax2_firmware_header *header, void *user_data),
diff --git a/channels/sig_analog.c b/channels/sig_analog.c
index 33c2699..64f1114 100644
--- a/channels/sig_analog.c
+++ b/channels/sig_analog.c
@@ -595,8 +595,6 @@
  * \note
  * Because deadlock avoidance may have been necessary, you need to confirm
  * the state of things before continuing.
- *
- * \return Nothing
  */
 static void analog_lock_sub_owner(struct analog_pvt *pvt, enum analog_sub sub_idx)
 {
@@ -3994,8 +3992,6 @@
  * \since 1.8
  *
  * \param doomed Analog private structure to delete.
- *
- * \return Nothing
  */
 void analog_delete(struct analog_pvt *doomed)
 {
diff --git a/channels/sip/config_parser.c b/channels/sip/config_parser.c
index 211f600..c7f829a 100644
--- a/channels/sip/config_parser.c
+++ b/channels/sip/config_parser.c
@@ -90,7 +90,8 @@
 
 	ast_copy_string(buf, value, sizeof(buf));
 
-	/*! register => [peer?][transport://]user[@domain][:secret[:authuser]]@host[:port][/extension][~expiry]
+	/*
+	 * register => [peer?][transport://]user[@domain][:secret[:authuser]]@host[:port][/extension][~expiry]
 	 * becomes
 	 *   userpart => [peer?][transport://]user[@domain][:secret[:authuser]]
 	 *   hostpart => host[:port][/extension][~expiry]
@@ -105,7 +106,7 @@
 		return -1;
 	}
 
-	/*!
+	/*
 	 * pre1.peer => peer
 	 * pre1.userpart => [transport://]user[@domain][:secret[:authuser]]
 	 * hostpart => host[:port][/extension][~expiry]
@@ -116,7 +117,7 @@
 		pre1.peer = NULL;
 	}
 
-	/*!
+	/*
 	 * pre1.peer => peer
 	 * pre2.transport = transport
 	 * pre2.userpart => user[@domain][:secret[:authuser]]
@@ -135,7 +136,7 @@
 		return -1;
 	}
 
-	/*!
+	/*
 	 * pre1.peer => peer
 	 * pre2.transport = transport
 	 * user1.userpart => user[@domain]
@@ -145,7 +146,7 @@
 	 */
 	AST_NONSTANDARD_RAW_ARGS(user1, pre2.userpart, ':');
 
-	/*!
+	/*
 	 * pre1.peer => peer
 	 * pre2.transport = transport
 	 * user1.userpart => user[@domain]
@@ -156,7 +157,7 @@
 	 */
 	AST_NONSTANDARD_RAW_ARGS(host1, hostpart, '~');
 
-	/*!
+	/*
 	 * pre1.peer => peer
 	 * pre2.transport = transport
 	 * user1.userpart => user[@domain]
@@ -168,7 +169,7 @@
 	 */
 	AST_NONSTANDARD_RAW_ARGS(host2, host1.hostpart, '/');
 
-	/*!
+	/*
 	 * pre1.peer => peer
 	 * pre2.transport = transport
 	 * user1.userpart => user[@domain]
@@ -181,32 +182,32 @@
 	 */
 	AST_NONSTANDARD_RAW_ARGS(host3, host2.hostpart, ':');
 
-	/*!
-	  * pre1.peer => peer
-	  * pre2.transport = transport
-	  * user2.user => user
-	  * user2.domain => domain
-	  * user1.secret => secret
-	  * user1.authuser => authuser
-	  * host3.host => host
-	  * host3.port => port
-	  * host2.extension => extension
-	  * host1.expiry => expiry
+	/*
+	 * pre1.peer => peer
+	 * pre2.transport = transport
+	 * user2.user => user
+	 * user2.domain => domain
+	 * user1.secret => secret
+	 * user1.authuser => authuser
+	 * host3.host => host
+	 * host3.port => port
+	 * host2.extension => extension
+	 * host1.expiry => expiry
 	 */
 	AST_NONSTANDARD_RAW_ARGS(user2, user1.userpart, '@');
 
-	/*!
-	  * pre1.peer => peer
-	  * pre2.transport = transport
-	  * user2.user => user
-	  * user2.domain => domain
-	  * user1.secret => secret
-	  * user3.authuser => authuser
-	  * user3.domainport => domainport
-	  * host3.host => host
-	  * host3.port => port
-	  * host2.extension => extension
-	  * host1.expiry => expiry
+	/*
+	 * pre1.peer => peer
+	 * pre2.transport = transport
+	 * user2.user => user
+	 * user2.domain => domain
+	 * user1.secret => secret
+	 * user3.authuser => authuser
+	 * user3.domainport => domainport
+	 * host3.host => host
+	 * host3.port => port
+	 * host2.extension => extension
+	 * host1.expiry => expiry
 	 */
 	AST_NONSTANDARD_RAW_ARGS(user3, user1.authuser, ':');
 
diff --git a/channels/sip/include/reqresp_parser.h b/channels/sip/include/reqresp_parser.h
index a0634f6..67d9da4 100644
--- a/channels/sip/include/reqresp_parser.h
+++ b/channels/sip/include/reqresp_parser.h
@@ -85,7 +85,7 @@
 /*!
  * \brief  Get caller id name from SIP headers, copy into output buffer
  *
- * \retval input string pointer placed after display-name field if possible
+ * \return input string pointer placed after display-name field if possible
  */
 const char *get_calleridname(const char *input, char *output, size_t outputsize);
 
@@ -173,9 +173,9 @@
  * item is found that is not supported, it is copied to the unsupported
  * out buffer.
  *
- * \param option list
- * \param unsupported out buffer (optional)
- * \param unsupported out buffer length (optional)
+ * \param options list
+ * \param[in,out] unsupported buffer (optional)
+ * \param[in,out] unsupported_len buffer length
  *
  * \note Because this function can be called multiple times, it will append
  * whatever options are specified in \c options to \c unsupported. Callers
@@ -242,7 +242,7 @@
  */
 struct sip_via *parse_via(const char *header);
 
-/*
+/*!
  * \brief Free parsed Via data.
  */
 void free_via(struct sip_via *v);
diff --git a/channels/sip/include/route.h b/channels/sip/include/route.h
index 3221cce..13acd2c 100644
--- a/channels/sip/include/route.h
+++ b/channels/sip/include/route.h
@@ -57,7 +57,7 @@
  * \param len Length of hop not including null terminator
  * \param inserthead If true then inserted the new route to the top of the list
  *
- * \retval Pointer to null terminated copy of URI on success
+ * \return Pointer to null terminated copy of URI on success
  * \retval NULL on error
  */
 const char *sip_route_add(struct sip_route *route, const char *uri, size_t len, int inserthead);
@@ -65,15 +65,12 @@
 /*!
  * \brief Add routes from header
  *
- * \note This procedure is for headers that require use of <brackets>.
+ * \note This procedure is for headers that require use of \<brackets\>.
  */
 void sip_route_process_header(struct sip_route *route, const char *header, int inserthead);
 
 /*!
  * \brief copy route-set
- *
- * \retval non-zero on failure
- * \retval 0 on success
  */
 void sip_route_copy(struct sip_route *dst, const struct sip_route *src);
 
@@ -94,7 +91,7 @@
  * \param formatcli Add's space after comma's, print's N/A if list is empty.
  * \param skip Number of hops to skip
  *
- * \retval an allocated struct ast_str on success
+ * \return an allocated struct ast_str on success
  * \retval NULL on failure
  */
 struct ast_str *sip_route_list(const struct sip_route *route, int formatcli, int skip)
diff --git a/channels/sip/include/sip.h b/channels/sip/include/sip.h
index 9feeb9e..f04284e 100644
--- a/channels/sip/include/sip.h
+++ b/channels/sip/include/sip.h
@@ -841,7 +841,7 @@
 	unsigned int reqsipoptions; /*!< Items needed for Required header in responses */
 };
 
-/* \brief given a sip_request and an offset, return the char * that resides there
+/*! \brief given a sip_request and an offset, return the char * that resides there
  *
  * It used to be that rlpart1, rlpart2, and the header and line arrays were character
  * pointers. They are now offsets into the ast_str portion of the sip_request structure.
diff --git a/channels/sip/reqresp_parser.c b/channels/sip/reqresp_parser.c
index ca32479..dd730e9 100644
--- a/channels/sip/reqresp_parser.c
+++ b/channels/sip/reqresp_parser.c
@@ -690,7 +690,7 @@
 
 /*! \brief  Get caller id name from SIP headers, copy into output buffer
  *
- *  \retval input string pointer placed after display-name field if possible
+ *  \return input string pointer placed after display-name field if possible
  */
 const char *get_calleridname(const char *input, char *output, size_t outputsize)
 {
@@ -1685,10 +1685,6 @@
  * builds a bit field representing all the SIP options in that field. When an
  * item is found that is not supported, it is copied to the unsupported
  * out buffer.
- *
- * \param options list
- * \param unsupported out buffer (optional)
- * \param unsupported_len out buffer length (optional)
  */
 unsigned int parse_sip_options(const char *options, char *unsupported, size_t unsupported_len)
 {

-- 
To view, visit https://gerrit.asterisk.org/c/asterisk/+/17560
To unsubscribe, or for help writing mail filters, visit https://gerrit.asterisk.org/settings

Gerrit-Project: asterisk
Gerrit-Branch: 16
Gerrit-Change-Id: Ia8811ac12b93ff8c18164699c6fbc604cb0a23f7
Gerrit-Change-Number: 17560
Gerrit-PatchSet: 1
Gerrit-Owner: Alexander Traud <pabstraud at compuserve.com>
Gerrit-MessageType: newchange
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20211119/7324149b/attachment-0001.html>


More information about the asterisk-code-review mailing list