Summary: | ASTERISK-29751: channel: Fix for Doxygen | ||
Reporter: | Alexander Traud (traud) | Labels: | |
Date Opened: | 2021-11-16 12:09:14.000-0600 | Date Closed: | 2021-11-18 14:12:28.000-0600 |
Priority: | Trivial | Regression? | |
Status: | Closed/Complete | Components: | 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] |