[Home]

Summary:ASTERISK-29751: channel: Fix for Doxygen
Reporter:Alexander Traud (traud)Labels:
Date Opened:2021-11-16 12:09:14.000-0600Date Closed:2021-11-18 14:12:28.000-0600
Priority:TrivialRegression?
Status:Closed/CompleteComponents:Core/Channels Documentation
Versions:16.22.0 18.8.0 19.0.0 Frequency of
Occurrence
Related
Issues:
Environment:Attachments:
Description:If all {{WARN_}} are enabled in the file {{doc/asterisk-ng-doxygen.in}}, the following appears in the file {{doxygen.log}}:
{code}
main/channel.c:6771: warning: documented empty return type of ast_change_name
include/asterisk/channel.h:4609: warning: argument 'Clear' of command @param is not found in the argument list of ast_channel_clear_flag(struct ast_channel *chan, unsigned int flag)
main/channel.c:2433: warning: documented empty return type of ast_channel_clear_softhangup
main/channel.c:10993: warning: documented empty return type of ast_channel_end_dtmf
main/channel.c:9125: warning: documented empty return type of ast_channel_queue_connected_line_update
main/channel.c:10315: warning: documented empty return type of ast_channel_queue_redirecting_update
main/channel.c:6443: warning: documented empty return type of ast_channel_req_accountcodes
main/channel.c:6448: warning: documented empty return type of ast_channel_req_accountcodes_precious
main/channel.c:7376: warning: documented empty return type of ast_channel_set_caller
main/channel.c:7389: warning: documented empty return type of ast_channel_set_caller_event
main/channel.c:8327: warning: documented empty return type of ast_channel_set_connected_line
main/channel.c:9138: warning: documented empty return type of ast_channel_set_redirecting
main/channel.c:464: warning: documented empty return type of ast_channel_softhangup_withcause_locked
main/channel.c:8229: warning: documented empty return type of ast_channel_stop_silence_generator
main/channel.c:9112: warning: documented empty return type of ast_channel_update_connected_line
main/channel.c:10302: warning: documented empty return type of ast_channel_update_redirecting
main/channel.c:8312: warning: documented empty return type of ast_connected_line_copy_from_caller
main/channel.c:8319: warning: documented empty return type of ast_connected_line_copy_to_caller
main/channel.c:1982: warning: documented empty return type of ast_party_caller_copy
main/channel.c:2011: warning: documented empty return type of ast_party_caller_free
main/channel.c:1974: warning: documented empty return type of ast_party_caller_init
main/channel.c:2003: warning: documented empty return type of ast_party_caller_set
main/channel.c:1995: warning: documented empty return type of ast_party_caller_set_init
main/channel.c:2059: warning: documented empty return type of ast_party_connected_line_collect_caller
main/channel.c:2027: warning: documented empty return type of ast_party_connected_line_copy
main/channel.c:2068: warning: documented empty return type of ast_party_connected_line_free
main/channel.c:2018: warning: documented empty return type of ast_party_connected_line_init
main/channel.c:2050: warning: documented empty return type of ast_party_connected_line_set
main/channel.c:2041: warning: documented empty return type of ast_party_connected_line_set_init
main/channel.c:1932: warning: documented empty return type of ast_party_dialed_copy
main/channel.c:1967: warning: documented empty return type of ast_party_dialed_free
main/channel.c:1924: warning: documented empty return type of ast_party_dialed_init
main/channel.c:1954: warning: documented empty return type of ast_party_dialed_set
main/channel.c:1946: warning: documented empty return type of ast_party_dialed_set_init
main/channel.c:1761: warning: documented empty return type of ast_party_id_copy
main/channel.c:1807: warning: documented empty return type of ast_party_id_free
main/channel.c:1753: warning: documented empty return type of ast_party_id_init
main/channel.c:1885: warning: documented empty return type of ast_party_id_invalidate
main/channel.c:1916: warning: documented empty return type of ast_party_id_merge_copy
main/channel.c:1892: warning: documented empty return type of ast_party_id_reset
main/channel.c:1784: warning: documented empty return type of ast_party_id_set
main/channel.c:1776: warning: documented empty return type of ast_party_id_set_init
main/channel.c:1595: warning: documented empty return type of ast_party_name_copy
main/channel.c:1634: warning: documented empty return type of ast_party_name_free
main/channel.c:1587: warning: documented empty return type of ast_party_name_init
main/channel.c:1617: warning: documented empty return type of ast_party_name_set
main/channel.c:1609: warning: documented empty return type of ast_party_name_set_init
main/channel.c:1648: warning: documented empty return type of ast_party_number_copy
main/channel.c:1687: warning: documented empty return type of ast_party_number_free
main/channel.c:1640: warning: documented empty return type of ast_party_number_init
main/channel.c:1670: warning: documented empty return type of ast_party_number_set
main/channel.c:1662: warning: documented empty return type of ast_party_number_set_init
main/channel.c:2131: warning: documented empty return type of ast_party_redirecting_copy
main/channel.c:2175: warning: documented empty return type of ast_party_redirecting_free
main/channel.c:2118: warning: documented empty return type of ast_party_redirecting_init
main/channel.c:2081: warning: documented empty return type of ast_party_redirecting_reason_copy
main/channel.c:2112: warning: documented empty return type of ast_party_redirecting_reason_free
main/channel.c:2075: warning: documented empty return type of ast_party_redirecting_reason_init
main/channel.c:2098: warning: documented empty return type of ast_party_redirecting_reason_set
main/channel.c:2092: warning: documented empty return type of ast_party_redirecting_reason_set_init
main/channel.c:2162: warning: documented empty return type of ast_party_redirecting_set
main/channel.c:2149: warning: documented empty return type of ast_party_redirecting_set_init
main/channel.c:1701: warning: documented empty return type of ast_party_subaddress_copy
main/channel.c:1740: warning: documented empty return type of ast_party_subaddress_free
main/channel.c:1693: warning: documented empty return type of ast_party_subaddress_init
main/channel.c:1723: warning: documented empty return type of ast_party_subaddress_set
main/channel.c:1715: warning: documented empty return type of ast_party_subaddress_set_init
main/channel.c:1746: warning: documented empty return type of ast_set_party_id_all
main/channel.c:489: warning: documented empty return type of ast_softhangup_all
main/channel.c:5876: warning: documented empty return type of call_forward_inherit
main/channel.c:6385: warning: documented empty return type of channel_req_accountcodes
main/channel.c:10342: warning: documented empty return type of channel_set_intercept_mode
main/channel.c:7829: warning: documented empty return type of prnt_channel_key
main/channel.c:2633: warning: documented empty return type of set_channel_answer_time
include/asterisk/channel.h:2611: warning: documented empty return type of ast_autoservice_chan_hangup_peer
include/asterisk/channel.h:2385: warning: argument 'state' of command @param is not found in the argument list of ast_cause2str(int cause)
include/asterisk/channel.h:2390: warning: The following parameter of ast_cause2str(int cause) is not documented:
 parameter 'cause'
include/asterisk/channel.h:1424: warning: documented empty return type of ast_change_name
include/asterisk/channel.h:4609: warning: argument 'Clear' of command @param is not found in the argument list of ast_channel_clear_flag(struct ast_channel *chan, unsigned int flag)
include/asterisk/channel.h:1644: warning: documented empty return type of ast_channel_clear_softhangup
include/asterisk/channel.h:4946: warning: documented empty return type of ast_channel_end_dtmf
include/asterisk/channel.h:5050: warning: argument 'channel' of command @param is not found in the argument list of ast_channel_get_default_stream(struct ast_channel *chan, enum ast_media_type type)
include/asterisk/channel.h:5058: warning: The following parameter of ast_channel_get_default_stream(struct ast_channel *chan, enum ast_media_type type) is not documented:
 parameter 'chan'
include/asterisk/channel.h:2743: warning: documented empty return type of ast_channel_internal_copy_linkedid
include/asterisk/channel.h:2801: warning: documented empty return type of ast_channel_internal_set_fake_ids
include/asterisk/channel.h:2777: warning: documented empty return type of ast_channel_internal_swap_endpoint_forward
include/asterisk/channel.h:2788: warning: documented empty return type of ast_channel_internal_swap_snapshots
include/asterisk/channel.h:2765: warning: documented empty return type of ast_channel_internal_swap_topics
include/asterisk/channel.h:2754: warning: documented empty return type of ast_channel_internal_swap_uniqueid_and_linkedid
include/asterisk/channel.h:5063: warning: argument 'channel' of command @param is not found in the argument list of ast_channel_is_multistream(struct ast_channel *chan)
include/asterisk/channel.h:5069: warning: The following parameter of ast_channel_is_multistream(struct ast_channel *chan) is not documented:
 parameter 'chan'
include/asterisk/channel.h:3885: warning: documented empty return type of ast_channel_queue_connected_line_update
include/asterisk/channel.h:3955: warning: documented empty return type of ast_channel_queue_redirecting_update
include/asterisk/channel.h:1498: warning: documented empty return type of ast_channel_req_accountcodes
include/asterisk/channel.h:1514: warning: documented empty return type of ast_channel_req_accountcodes_precious
include/asterisk/channel.h:2553: warning: documented empty return type of ast_channel_set_caller
include/asterisk/channel.h:2568: warning: documented empty return type of ast_channel_set_caller_event
include/asterisk/channel.h:3828: warning: documented empty return type of ast_channel_set_connected_line
include/asterisk/channel.h:3899: warning: documented empty return type of ast_channel_set_redirecting
include/asterisk/channel.h:1776: warning: documented empty return type of ast_channel_setwhentohangup_tv
include/asterisk/channel.h:1748: warning: documented empty return type of ast_channel_softhangup_withcause_locked
include/asterisk/channel.h:2727: warning: documented empty return type of ast_channel_stop_silence_generator
include/asterisk/channel.h:1580: warning: documented empty return type of ast_channel_unregister
include/asterisk/channel.h:3873: warning: documented empty return type of ast_channel_update_connected_line
include/asterisk/channel.h:3943: warning: documented empty return type of ast_channel_update_redirecting
include/asterisk/channel.h:3801: warning: documented empty return type of ast_connected_line_copy_from_caller
include/asterisk/channel.h:3814: warning: documented empty return type of ast_connected_line_copy_to_caller
include/asterisk/channel.h:1598: warning: documented empty return type of ast_hangup
include/asterisk/channel.h:3537: warning: documented empty return type of ast_party_caller_copy
include/asterisk/channel.h:3581: warning: documented empty return type of ast_party_caller_free
include/asterisk/channel.h:3526: warning: documented empty return type of ast_party_caller_init
include/asterisk/channel.h:3571: warning: documented empty return type of ast_party_caller_set
include/asterisk/channel.h:3556: warning: documented empty return type of ast_party_caller_set_init
include/asterisk/channel.h:3651: warning: documented empty return type of ast_party_connected_line_collect_caller
include/asterisk/channel.h:3602: warning: documented empty return type of ast_party_connected_line_copy
include/asterisk/channel.h:3661: warning: documented empty return type of ast_party_connected_line_free
include/asterisk/channel.h:3591: warning: documented empty return type of ast_party_connected_line_init
include/asterisk/channel.h:3636: warning: documented empty return type of ast_party_connected_line_set
include/asterisk/channel.h:3621: warning: documented empty return type of ast_party_connected_line_set_init
include/asterisk/channel.h:3473: warning: documented empty return type of ast_party_dialed_copy
include/asterisk/channel.h:3516: warning: documented empty return type of ast_party_dialed_free
include/asterisk/channel.h:3462: warning: documented empty return type of ast_party_dialed_init
include/asterisk/channel.h:3506: warning: documented empty return type of ast_party_dialed_set
include/asterisk/channel.h:3492: warning: documented empty return type of ast_party_dialed_set_init
include/asterisk/channel.h:3341: warning: documented empty return type of ast_party_id_copy
include/asterisk/channel.h:3382: warning: documented empty return type of ast_party_id_free
include/asterisk/channel.h:3330: warning: documented empty return type of ast_party_id_init
include/asterisk/channel.h:3402: warning: documented empty return type of ast_party_id_invalidate
include/asterisk/channel.h:3452: warning: documented empty return type of ast_party_id_merge_copy
include/asterisk/channel.h:3412: warning: documented empty return type of ast_party_id_reset
include/asterisk/channel.h:3372: warning: documented empty return type of ast_party_id_set
include/asterisk/channel.h:3360: warning: documented empty return type of ast_party_id_set_init
include/asterisk/channel.h:3148: warning: documented empty return type of ast_party_name_copy
include/asterisk/channel.h:3188: warning: documented empty return type of ast_party_name_free
include/asterisk/channel.h:3137: warning: documented empty return type of ast_party_name_init
include/asterisk/channel.h:3178: warning: documented empty return type of ast_party_name_set
include/asterisk/channel.h:3167: warning: documented empty return type of ast_party_name_set_init
include/asterisk/channel.h:3209: warning: documented empty return type of ast_party_number_copy
include/asterisk/channel.h:3249: warning: documented empty return type of ast_party_number_free
include/asterisk/channel.h:3198: warning: documented empty return type of ast_party_number_init
include/asterisk/channel.h:3239: warning: documented empty return type of ast_party_number_set
include/asterisk/channel.h:3228: warning: documented empty return type of ast_party_number_set_init
include/asterisk/channel.h:3744: warning: documented empty return type of ast_party_redirecting_copy
include/asterisk/channel.h:3788: warning: documented empty return type of ast_party_redirecting_free
include/asterisk/channel.h:3733: warning: documented empty return type of ast_party_redirecting_init
include/asterisk/channel.h:3680: warning: documented empty return type of ast_party_redirecting_reason_copy
include/asterisk/channel.h:3723: warning: documented empty return type of ast_party_redirecting_reason_free
include/asterisk/channel.h:3670: warning: documented empty return type of ast_party_redirecting_reason_init
include/asterisk/channel.h:3713: warning: documented empty return type of ast_party_redirecting_reason_set
include/asterisk/channel.h:3699: warning: documented empty return type of ast_party_redirecting_reason_set_init
include/asterisk/channel.h:3778: warning: documented empty return type of ast_party_redirecting_set
include/asterisk/channel.h:3763: warning: documented empty return type of ast_party_redirecting_set_init
include/asterisk/channel.h:3270: warning: documented empty return type of ast_party_subaddress_copy
include/asterisk/channel.h:3310: warning: documented empty return type of ast_party_subaddress_free
include/asterisk/channel.h:3259: warning: documented empty return type of ast_party_subaddress_init
include/asterisk/channel.h:3300: warning: documented empty return type of ast_party_subaddress_set
include/asterisk/channel.h:3289: warning: documented empty return type of ast_party_subaddress_set_init
include/asterisk/channel.h:3320: warning: documented empty return type of ast_set_party_id_all
include/asterisk/channel.h:1609: warning: argument 'reason' of command @param is not found in the argument list of ast_softhangup(struct ast_channel *chan, int cause)
include/asterisk/channel.h:1623: warning: The following parameter of ast_softhangup(struct ast_channel *chan, int cause) is not documented:
 parameter 'cause'
include/asterisk/channel.h:1606: warning: documented empty return type of ast_softhangup_all
include/asterisk/channel.h:1626: warning: argument 'reason' of command @param is not found in the argument list of ast_softhangup_nolock(struct ast_channel *chan, int cause)
include/asterisk/channel.h:1630: warning: The following parameter of ast_softhangup_nolock(struct ast_channel *chan, int cause) is not documented:
 parameter 'cause'
main/channel.c:634: warning: argument 'ast_channel_state' of command @param is not found in the argument list of ast_state2str(enum ast_channel_state state)
include/asterisk/channel.h:2664: warning: argument 'chan' from the argument list of ast_transfer_protocol has multiple @param documentation sections
include/asterisk/channel.h:2664: warning: argument 'dest' from the argument list of ast_transfer_protocol has multiple @param documentation sections
include/asterisk/channel.h:2664: warning: argument 'protocol' from the argument list of ast_transfer_protocol has multiple @param documentation sections
include/asterisk/channel.h:1997: warning: argument 'chan' of command @param is not found in the argument list of ast_waitfor_nandfds(struct ast_channel **c, int n, int *fds, int nfds, int *exception, int *outfd, int *ms)
include/asterisk/channel.h:2012: warning: The following parameter of ast_waitfor_nandfds(struct ast_channel **c, int n, int *fds, int nfds, int *exception, int *outfd, int *ms) is not documented:
 parameter 'c'
include/asterisk/channel.h:5050: warning: argument 'channel' of command @param is not found in the argument list of ast_channel_get_default_stream(struct ast_channel *chan, enum ast_media_type type)
main/channel_internal_api.c:1619: warning: The following parameter of ast_channel_get_default_stream(struct ast_channel *chan, enum ast_media_type type) is not documented:
 parameter 'chan'
main/channel_internal_api.c:1404: warning: documented empty return type of ast_channel_internal_copy_linkedid
main/channel_internal_api.c:1465: warning: documented empty return type of ast_channel_internal_set_fake_ids
main/channel_internal_api.c:1447: warning: documented empty return type of ast_channel_internal_swap_endpoint_forward
main/channel_internal_api.c:1456: warning: documented empty return type of ast_channel_internal_swap_snapshots
main/channel_internal_api.c:1433: warning: documented empty return type of ast_channel_internal_swap_topics
main/channel_internal_api.c:1416: warning: documented empty return type of ast_channel_internal_swap_uniqueid_and_linkedid
include/asterisk/channel.h:5063: warning: argument 'channel' of command @param is not found in the argument list of ast_channel_is_multistream(struct ast_channel *chan)
main/channel_internal_api.c:1643: warning: The following parameter of ast_channel_is_multistream(struct ast_channel *chan) is not documented:
 parameter 'chan'
include/asterisk/channel.h:113: warning: unable to resolve reference to 'AstRTPbridge' for \ref command
{code}
Although this module is responsible for 180 warnings, the solutions were mostly \return statements. However, again a lesson to be learned: The statements included ‘Nothing’, ‘Nothing.’ (with a period), ‘No return value’, ‘void’, and ‘Nada’. Such an inconsistency makes it difficult to replace all statements at once.

Another interesting issue: Doxygen seems to require the prototype and the implementation to use the same parameter name. Therefore, in this case, I had to change not only comments but even code.
Comments:By: Asterisk Team (asteriskteam) 2021-11-16 12:09:16.103-0600

Thanks for creating a report! The issue has entered the triage process. That means the issue will wait in this status until a Bug Marshal has an opportunity to review the issue. Once the issue has been reviewed you will receive comments regarding the next steps towards resolution. Please note that log messages and other files should not be sent to the Sangoma Asterisk Team unless explicitly asked for. All files should be placed on this issue in a sanitized fashion as needed.

A good first step is for you to review the [Asterisk Issue Guidelines|https://wiki.asterisk.org/wiki/display/AST/Asterisk+Issue+Guidelines] if you haven't already. The guidelines detail what is expected from an Asterisk issue report.

Then, if you are submitting a patch, please review the [Patch Contribution Process|https://wiki.asterisk.org/wiki/display/AST/Patch+Contribution+Process].

Please note that once your issue enters an open state it has been accepted. As Asterisk is an open source project there is no guarantee or timeframe on when your issue will be looked into. If you need expedient resolution you will need to find and pay a suitable developer. Asking for an update on your issue will not yield any progress on it and will not result in a response. All updates are posted to the issue when they occur.

Please note that by submitting data, code, or documentation to Sangoma through JIRA, you accept the Terms of Use present at [https://www.asterisk.org/terms-of-use/|https://www.asterisk.org/terms-of-use/].

By: Friendly Automation (friendly-automation) 2021-11-18 14:12:29.043-0600

Change 17479 merged by Friendly Automation:
channel: Fix for Doxygen.

[https://gerrit.asterisk.org/c/asterisk/+/17479|https://gerrit.asterisk.org/c/asterisk/+/17479]

By: Friendly Automation (friendly-automation) 2021-11-18 14:47:42.759-0600

Change 17500 merged by Kevin Harwell:
channel: Fix for Doxygen.

[https://gerrit.asterisk.org/c/asterisk/+/17500|https://gerrit.asterisk.org/c/asterisk/+/17500]

By: Friendly Automation (friendly-automation) 2021-11-18 14:48:00.113-0600

Change 17495 merged by Kevin Harwell:
channel: Fix for Doxygen.

[https://gerrit.asterisk.org/c/asterisk/+/17495|https://gerrit.asterisk.org/c/asterisk/+/17495]

By: Friendly Automation (friendly-automation) 2021-11-18 14:48:36.624-0600

Change 17496 merged by Kevin Harwell:
channel: Fix for Doxygen.

[https://gerrit.asterisk.org/c/asterisk/+/17496|https://gerrit.asterisk.org/c/asterisk/+/17496]