[Asterisk-code-review] res: Fix for Doxygen. (asterisk[master])

[Alexander Traud]

Attention is currently required from: George Joseph, Josh Soref.
Alexander Traud has posted comments on this change. ( https://gerrit.asterisk.org/c/asterisk/+/17511 )

Change subject: res: Fix for Doxygen.
......................................................................


Patch Set 4:

(6 comments)

File include/asterisk/http_websocket.h:

https://gerrit.asterisk.org/c/asterisk/+/17511/comment/879cc301_459511f4 
PS4, Line 224:  * \param server Name of the sub-protocol to unregister
> Same comment as before (sorry, should have commented on all of them)
Done


https://gerrit.asterisk.org/c/asterisk/+/17511/comment/f9c33c1c_818a5c44 
PS4, Line 258:  * \return number of bytes read on success
> General question: is there a convention to have a blank line between `\param` and one of `\retval` o […]
That is a style related question. I am not aware of a style guide for Doxygen from the Asterisk Team. So no, the fields (and blanks) can be placed everywhere, even their order, even the order of the parameter do not matter for Doxygen.

Sometimes, I added a blank line. The goal of the overall change was primarily syntactic, I fixed warnings emitted by Doxygen. The second goal was to fix *obvious* semantic issues which Doxygen cannot detect, like this one because retval has one parameter/argument; and number does not make sense as that, therefore return. The third goal was to add a bit of consistency in the style.

Perhaps this series of changes lead to a style guide, for new code. I am not so sure about existing code because the primary goal of Doxygen code should not be looking good in code but creating usable HTML/PDF documentation.


File include/asterisk/http_websocket.h:

https://gerrit.asterisk.org/c/asterisk/+/17511/comment/dd97ff40_ff17b0c4 
PS1, Line 132:  * \return New \ref ast_websocket_server instance
             :  * \retval NULL on error
> Shouldn't this just be […]
Done


File include/asterisk/res_mwi_external.h:

https://gerrit.asterisk.org/c/asterisk/+/17511/comment/00081678_121d28b7 
PS1, Line 93:  * \return copy on success.  The object is an ao2 object.
            :  * \retval NULL on error.
            :  */
> Same as above?
Done


https://gerrit.asterisk.org/c/asterisk/+/17511/comment/fd0d6abb_d96accc8 
PS1, Line 166: * \return requested mailbox on success.  The object is an ao2 object.
             :  * \retval NULL on error or no mailbox.
             :  *
> Same
Done


https://gerrit.asterisk.org/c/asterisk/+/17511/comment/27a5c9be_f20ebfa0 
PS1, Line 181:  * \return container of struct ast_mwi_mailbox_object on success.
             :  * \retval NULL on error.
> Same
Done



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

Gerrit-Project: asterisk
Gerrit-Branch: master
Gerrit-Change-Id: I572e6019c422780dde5ce8448b6c85c77af6046d
Gerrit-Change-Number: 17511
Gerrit-PatchSet: 4
Gerrit-Owner: Alexander Traud <pabstraud at compuserve.com>
Gerrit-Reviewer: Friendly Automation
Gerrit-CC: George Joseph <gjoseph at digium.com>
Gerrit-CC: Josh Soref <jsoref at gmail.com>
Gerrit-Attention: George Joseph <gjoseph at digium.com>
Gerrit-Attention: Josh Soref <jsoref at gmail.com>
Gerrit-Comment-Date: Thu, 25 Nov 2021 08:53:09 +0000
Gerrit-HasComments: Yes
Gerrit-Has-Labels: No
Comment-In-Reply-To: George Joseph <gjoseph at digium.com>
Comment-In-Reply-To: Josh Soref <jsoref at gmail.com>
Gerrit-MessageType: comment
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20211125/cd655419/attachment-0001.html>