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

Kevin Harwell asteriskteam at digium.com
Thu Nov 18 16:59:50 CST 2021


Kevin Harwell has submitted this change. ( https://gerrit.asterisk.org/c/asterisk/+/17526 )

Change subject: parking: Fix for Doxygen.
......................................................................

parking: Fix for Doxygen.

ASTERISK-29753

Change-Id: I7a61974584f6169502e6860fc711919fe7bbfaa7
---
M include/asterisk/parking.h
M res/parking/parking_applications.c
M res/parking/parking_bridge.c
M res/parking/parking_bridge_features.c
M res/parking/res_parking.h
M res/res_parking.c
6 files changed, 29 insertions(+), 41 deletions(-)

Approvals:
  Kevin Harwell: Looks good to me, but someone else must approve; Approved for Submit
  George Joseph: Looks good to me, approved



diff --git a/include/asterisk/parking.h b/include/asterisk/parking.h
index 512b1da..9f5d280 100644
--- a/include/asterisk/parking.h
+++ b/include/asterisk/parking.h
@@ -85,7 +85,7 @@
  * \param duration how long the parked call has currently been parked
  *
  * \retval NULL if the parked call payload can't be allocated
- * \retval reference to a newly created parked call payload
+ * \return reference to a newly created parked call payload
  */
 struct ast_parked_call_payload *ast_parked_call_payload_create(enum ast_parked_call_event_type event_type,
 		struct ast_channel_snapshot *parkee_snapshot, const char *parker_dial_string,
@@ -101,7 +101,7 @@
  * \since 12
  *
  * \retval NULL if the parking topic hasn't been created or has been disabled
- * \retval a pointer to the parking topic
+ * \return a pointer to the parking topic
  */
 struct stasis_topic *ast_parking_topic(void);
 
@@ -110,7 +110,7 @@
  * \since 12
  *
  * \retval NULL if the parking topic hasn't been created or has been canceled
- * \retval a pointer to the parked call message type
+ * \return a pointer to the parked call message type
  */
 struct stasis_message_type *ast_parked_call_type(void);
 
@@ -149,7 +149,7 @@
 	/*!
 	 * \brief Park the bridge and/or callers that this channel is in
 	 *
-	 * \param parker The bridge_channel parking the bridge
+	 * \param parker The \p bridge_channel parking the bridge
 	 * \param exten Optional. The extension the channel or bridge was parked at if the
 	 * call succeeds.
 	 * \param length Optional. If \c exten is specified, the size of the buffer.
@@ -164,13 +164,13 @@
 	/*!
 	 * \brief Perform a blind transfer to a parking extension.
 	 *
-	 * \param parker The \ref bridge_channel object that is initiating the parking
+	 * \param parker The \p bridge_channel object that is initiating the parking
 	 * \param context The context to blind transfer to
 	 * \param exten The extension to blind transfer to
 	 * \param parked_channel_cb Execute the following function on the channel that gets parked
 	 * \param parked_channel_data Data for the parked_channel_cb
 	 *
-	 * \note If the bridge \ref parker is in has more than one other occupant, the entire
+	 * \note If the bridge \p parker is in has more than one other occupant, the entire
 	 * bridge will be parked using a Local channel
 	 *
 	 * \note This is safe to be called outside of the \ref AstBridging Bridging API.
@@ -235,14 +235,13 @@
 /*!
  * \brief Perform a blind transfer to a parking extension.
  *
- * \param parker The \ref bridge_channel object that is initiating the parking
+ * \param parker The ast_bridge_channel object that is initiating the parking
  * \param context The context to blind transfer to
  * \param exten The extension to blind transfer to
- * \param exten The extension to blind transfer to
  * \param parked_channel_cb Execute the following function on the channel that gets parked
  * \param parked_channel_data Data for the parked_channel_cb
  *
- * \note If the bridge \ref parker is in has more than one other occupant, the entire
+ * \note If the bridge \p parker is in has more than one other occupant, the entire
  * bridge will be parked using a Local channel
  *
  * \note This is safe to be called outside of the \ref AstBridging Bridging API.
@@ -283,7 +282,7 @@
 /*!
  * \brief Unregister the current parking provider
  *
- * \param The module name of the provider to unregister
+ * \param module_name The module name of the provider to unregister
  *
  * \retval 0 if the parking provider \c module_name was unregsistered
  * \retval -1 on error
diff --git a/res/parking/parking_applications.c b/res/parking/parking_applications.c
index f9b3e85..29878f8 100644
--- a/res/parking/parking_applications.c
+++ b/res/parking/parking_applications.c
@@ -740,8 +740,6 @@
  *
  * \param oh outgoing helper struct we are bestowing inheritable variables to
  * \param channel_id name or uniqueID of the channel to inherit variables from
- *
- * \return Nothing
  */
 static void inherit_channel_vars_from_id(struct outgoing_helper *oh, const char *channel_id)
 {
diff --git a/res/parking/parking_bridge.c b/res/parking/parking_bridge.c
index 4e56d58..934d1b0 100644
--- a/res/parking/parking_bridge.c
+++ b/res/parking/parking_bridge.c
@@ -48,8 +48,6 @@
  * \param self Bridge to operate upon.
  *
  * \note XXX Stub... and it might go unused.
- *
- * \return Nothing
  */
 static void bridge_parking_destroy(struct ast_bridge_parking *self)
 {
@@ -92,7 +90,7 @@
  * \brief Construct a parked_user struct assigned to the specified parking lot
  *
  * \param lot The parking lot we are assigning the user to
- * \param parkee The channel being parked
+ * \param chan The channel being parked
  * \param parker_channel_name The name of the parker of this channel
  * \param parker_dial_string Takes priority over parker for setting the parker dial string if included
  * \param use_random_space if true, prioritize using a random parking space instead
@@ -102,7 +100,7 @@
  *        use the parking lot limit instead.
  *
  * \retval NULL on failure
- * \retval reference to the parked user
+ * \return reference to the parked user
  *
  * \note ao2_cleanup this reference when you are done using it or you'll cause leaks.
  */
@@ -336,8 +334,6 @@
  * \param bridge_channel Bridge channel to pull.
  *
  * \note On entry, self is already locked.
- *
- * \return Nothing
  */
 static void bridge_parking_pull(struct ast_bridge_parking *self, struct ast_bridge_channel *bridge_channel)
 {
@@ -412,8 +408,6 @@
  *
  * \note On entry, self is already locked.
  * \note XXX Stub... and it will probably go unused.
- *
- * \return Nothing
  */
 static void bridge_parking_notify_masquerade(struct ast_bridge_parking *self, struct ast_bridge_channel *bridge_channel)
 {
diff --git a/res/parking/parking_bridge_features.c b/res/parking/parking_bridge_features.c
index 5347e6f..f6f8177 100644
--- a/res/parking/parking_bridge_features.c
+++ b/res/parking/parking_bridge_features.c
@@ -320,7 +320,7 @@
  * \brief Perform a blind transfer to a parking lot
  *
  * In general, most parking features should work to call this function. This will safely
- * park either a channel in the bridge with \ref bridge_channel or will park the entire
+ * park either a channel in the bridge with \p bridge_channel or will park the entire
  * bridge if more than one channel is in the bridge. It will create the correct data to
  * pass to the \ref AstBridging Bridging API to safely park the channel.
  *
@@ -490,7 +490,7 @@
  * \param length Optional. If \c exten is specified, the length of the buffer.
  *
  * \note This will determine the context and extension to park the channel based on
- * the configuration of the \ref ast_channel associated with \ref parker. It will then
+ * the configuration of the \ref ast_channel associated with \p parker. It will then
  * park either the channel or the entire bridge.
  *
  * \retval 0 on success
@@ -536,8 +536,6 @@
  *
  * \param chan Parked channel leaving the parking lot.
  * \param cfg Parking lot configuration.
- *
- * \return Nothing
  */
 static void parking_timeout_set_caller_features(struct ast_channel *chan, struct parking_lot_cfg *cfg)
 {
diff --git a/res/parking/res_parking.h b/res/parking/res_parking.h
index cd0b79f..2c025af 100644
--- a/res/parking/res_parking.h
+++ b/res/parking/res_parking.h
@@ -137,7 +137,7 @@
  * \param cfg The configuration being used as a reference to build the parking lot from.
  * \param dynamic non-zero if creating a dynamic parking lot with this. Don't replace existing parking lots. Ever.
  *
- * \retval A reference to the new parking lot
+ * \return A reference to the new parking lot
  * \retval NULL if it was not found and could not be allocated
  *
  * \note The parking lot will need to be unreffed if it ever falls out of scope
@@ -166,7 +166,7 @@
  * \param bridge_lot Parking lot which the new bridge should be based on
  *
  * \retval NULL if the bridge can not be created
- * \retval Newly created parking bridge
+ * \return Newly created parking bridge
  */
 struct ast_bridge *bridge_parking_new(struct parking_lot *bridge_lot);
 
@@ -176,7 +176,7 @@
  *
  * \param lot Which parking lot we need the bridge from. This parking lot must be locked before calling this function.
  *
- * \retval A reference to the ast_bridge associated with the parking lot
+ * \return A reference to the ast_bridge associated with the parking lot
  * \retval NULL if it didn't already have a bridge and one couldn't be created
  *
  * \note This bridge will need to be unreffed if it ever falls out of scope.
@@ -191,7 +191,7 @@
  * \param target_override If there is a specific slot we want, provide it here and we'll start from that position
  *
  * \retval -1 if No slot can be found
- * \retval integer value of parking space selected
+ * \return integer value of parking space selected
  *
  * \note lot should be locked before this is called and unlocked only after a parked_user with the space
  *       returned has been added to the parking lot.
@@ -206,7 +206,7 @@
  *               If >= 0  Only pull from the indicated target
  *
  * \retval NULL if no parked user could be pulled from the requested parking lot at the requested parking space
- * \retval reference to the requested parked user
+ * \return reference to the requested parked user
  *
  */
 struct parked_user *parking_lot_inspect_parked_user(struct parking_lot *lot, int target);
@@ -220,7 +220,7 @@
  *               If >= 0  Only pull from the indicated target
  *
  * \retval NULL if no parked user could be pulled from the requested parking lot at the requested parking space
- * \retval reference to the requested parked user
+ * \return reference to the requested parked user
  *
  * \note The parked user will be removed from parking lot as part of this process
  * \note Remove this reference with ao2_cleanup once it falls out of scope.
@@ -271,7 +271,7 @@
  * \since 12.0.0
  * \brief Get a pointer to the parking lot container for purposes such as iteration
  *
- * \retval pointer to the parking lot container.
+ * \return pointer to the parking lot container.
  */
 struct ao2_container *get_parking_lot_container(void);
 
@@ -281,7 +281,7 @@
  *
  * \param lot_name Name of the parking lot sought
  *
- * \retval The parking lot if found
+ * \return The parking lot if found
  * \retval NULL if no parking lot with the name specified exists
  *
  * \note ao2_cleanup this reference when you are done using it or you'll cause leaks.
@@ -295,7 +295,7 @@
  * \param name Dynamic parking lot name to create
  * \param chan Channel parkee to get dynamic parking lot parameters from
  *
- * \retval dynamically created parking lot on success
+ * \return dynamically created parking lot on success
  * \retval NULL on error
  *
  * \note This should be called only after verifying that the named parking lot doesn't already exist in a non-dynamic way.
@@ -310,7 +310,7 @@
  * \param name Dynamic parking lot name to create
  * \param chan Channel parkee to get the dynamic parking lot parameters from
  *
- * \retval dynamically created parking lot on success
+ * \return dynamically created parking lot on success
  * \retval NULL on error
  *
  * \note This should be called only after verifying that the named parking lot doesn't already exist in a non-dynamic way.
@@ -336,7 +336,7 @@
  * \since 12.0.0
  * \brief Flattens a dial string so that it can be written to/found from PBX extensions
  *
- * \param peername unflattened dial string. This will be flattened in place.
+ * \param dialstring unflattened dial string. This will be flattened in place.
  */
 void flatten_dial_string(char *dialstring);
 
@@ -437,7 +437,7 @@
  * \param silence_announcements optional pointer to an integer where we want to store the silence option flag
  *        this value should be initialized to 0 prior to calling park_common_setup.
  *
- * \retval reference to a parking bridge if successful
+ * \return reference to a parking bridge if successful
  * \retval NULL on failure
  *
  * \note ao2_cleanup this reference when you are done using it or you'll cause leaks.
@@ -460,7 +460,7 @@
  *
  * \param parkee The channel entering parking with the datastore we are checking
  *
- * \retval Pointer to a copy of the park common datastore for parkee if it could be cloned. This needs to be free'd with park_common_datastore free.
+ * \return Pointer to a copy of the park common datastore for parkee if it could be cloned. This needs to be free'd with park_common_datastore free.
  * \retval NULL if the park_common_datastore could not be copied off of the channel.
  */
 struct park_common_datastore *get_park_common_datastore_copy(struct ast_channel *parkee);
@@ -573,8 +573,6 @@
 /*!
  * \since 12.0.0
  * \brief Unregister parking unit tests
- *
- * \return Nothing
  */
 void unload_parking_tests(void);
 
diff --git a/res/res_parking.c b/res/res_parking.c
index 2aa19c9..2e4ea31 100644
--- a/res/res_parking.c
+++ b/res/res_parking.c
@@ -492,9 +492,10 @@
  * \brief find an item in a container by its name
  *
  * \param container ao2container where we want the item from
- * \param key name of the item wanted to be found
+ * \param name name of the item wanted to be found
  *
- * \retval pointer to the parking lot if available. NULL if not found.
+ * \return pointer to the parking lot if available.
+ * \retval NULL if not found.
  */
 static void *named_item_find(struct ao2_container *container, const char *name)
 {

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

Gerrit-Project: asterisk
Gerrit-Branch: 16
Gerrit-Change-Id: I7a61974584f6169502e6860fc711919fe7bbfaa7
Gerrit-Change-Number: 17526
Gerrit-PatchSet: 2
Gerrit-Owner: Alexander Traud <pabstraud at compuserve.com>
Gerrit-Reviewer: Friendly Automation
Gerrit-Reviewer: George Joseph <gjoseph at digium.com>
Gerrit-Reviewer: Kevin Harwell <kharwell at digium.com>
Gerrit-MessageType: merged
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20211118/c7afe3ce/attachment-0001.html>


More information about the asterisk-code-review mailing list