[Asterisk-code-review] progdocs: Fix for Doxygen, the hidden parts. (asterisk[master])

[Alexander Traud]

Attention is currently required from: Kevin Harwell.
Alexander Traud has posted comments on this change. ( https://gerrit.asterisk.org/c/asterisk/+/17587 )

Change subject: progdocs: Fix for Doxygen, the hidden parts.
......................................................................


Patch Set 1:

(4 comments)

File include/asterisk/test.h:

https://gerrit.asterisk.org/c/asterisk/+/17587/comment/c1ef6927_cb557fee 
PS1, Line 179:  * \param s The state the application has changed to
             :  * \param f The message with format parameters to add to the manager event
             :  */
             : #define ast_test_suite_event_notify(s, f, ...) \
             : 	__ast_test_suite_event_notify(__FILE__, __PRETTY_FUNCTION__, __LINE__, (s), (f), ## __VA_ARGS__)
> I assume the '... […]
Yes, no warning.

I figured that out quite late, Doxygen does not require a documentation for variable parameters, therefore no warning. I (tried) to keep the way I found, sometimes it makes sense to describe that there are variable arguments. However, as I explained to George when it comes to the return/retval, this is somehow a local ‘Asterisk Doxygen Style Guide’ topic: Should there be a documentation for variable parameters always, never, or in case? Cannot decide on that. So I kept what I found, when it added something.


https://gerrit.asterisk.org/c/asterisk/+/17587/comment/490181c7_65db0a0a 
PS1, Line 362:  * \param t currently executing test
             :  * \param f printf type format string
             :  *
             :  * \retval 0 success
             :  * \retval -1 failure
             :  */
             : #define ast_test_status_update(t, f, ...) __ast_test_status_update(__FILE__, __PRETTY_FUNCTION__, __LINE__, (t), (f), ## __VA_ARGS__)
> No need for '... […]
Same as before.


File main/dns_test.c:

https://gerrit.asterisk.org/c/asterisk/+/17587/comment/a4b14d81_68b24ff4 
PS1, Line 148: /*!
             :  * \brief Write a DNS string to a buffer
             :  *
             :  * This writes the DNS string to the buffer and returns the total
             :  * number of bytes written to the buffer.
             :  *
             :  * There is no buffer size passed to this function since we provide
             :  * the data ourselves and have sized the buffer to be way larger
             :  * than necessary for the tests.
             :  *
             :  * \param string The string to write
             :  * \param buf The buffer to write the string into
             :  * \return The number of bytes written to the buffer
             :  */
> Why is this block removed?
It is a duplicate to the Doxygen in include/asterisk/dns_test.h.

Doxygen is a bit picky when it finds multiple parameter (or return) documentation. Even with the same wording, Doxygen emits a warning. Because it is a duplicate, I removed it in the source file and kept the version of the header file. I could have left a ‘brief’. I think Doxygen has no problems with a ‘details’ too. It is just parameter and return/retval. Anyway, I opted to remove it completely because redundant. If you like it otherwise, please, say so.


https://gerrit.asterisk.org/c/asterisk/+/17587/comment/b62eff90_ed7a5def 
PS1, Line 178: 
             : /*!
             :  * \brief Write a DNS domain to a buffer
             :  *
             :  * A DNS domain consists of a series of labels separated
             :  * by dots. Each of these labels gets written as a DNS
             :  * string. A DNS domain ends with a NULL label, which is
             :  * essentially a zero-length DNS string.
             :  *
             :  *
             :  * There is no buffer size passed to this function since we provide
             :  * the data ourselves and have sized the buffer to be way larger
             :  * than necessary for the tests.
             :  *
             :  * \param string The DNS domain to write
             :  * \param buf The buffer to write the domain into
             :  * \return The number of bytes written to the buffer
             :  */
> Same, why remove this one?
Same as with ast_dns_test_write_string, it is a redundant duplicate of what is written in the header file dns_test.



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

Gerrit-Project: asterisk
Gerrit-Branch: master
Gerrit-Change-Id: If338163488498f65fa7248b60e80299c0a928e4b
Gerrit-Change-Number: 17587
Gerrit-PatchSet: 1
Gerrit-Owner: Alexander Traud <pabstraud at compuserve.com>
Gerrit-Reviewer: Friendly Automation
Gerrit-CC: Kevin Harwell <kharwell at digium.com>
Gerrit-Attention: Kevin Harwell <kharwell at digium.com>
Gerrit-Comment-Date: Wed, 01 Dec 2021 09:19:57 +0000
Gerrit-HasComments: Yes
Gerrit-Has-Labels: No
Comment-In-Reply-To: Kevin Harwell <kharwell at digium.com>
Gerrit-MessageType: comment
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20211201/7a16bf17/attachment-0001.html>