[asterisk-dev] Doxygen \since

[asterisk at phreaknet.org]

n 1/13/2022 1:12 PM, Kevin Harwell wrote:
> Greetings,
>
> Looking for opinions.
>
> When documenting API calls in Asterisk one can use the Doxygen \since 
> command [1] to specify which version of Asterisk the function was 
> added in. For example: \since 13.25.0 [2]
>
> Do folks find this helpful, and worth having? As a developer, when 
> adding a new API does trying to figure out what version of Asterisk 
> things will go in become too cumbersome?
>
> Personally, I've found having the version number on a function only 
> slightly helpful. I've used that info once, maybe twice, but feel it's 
> not worth the upfront cost (figuring out version info at patch time 
> for each branch, having to update a review if it doesn't make it in 
> before the expected release, etc...)
>
> So my vote is to drop its usage. Certainly though if many others find 
> it useful, or have a good reason to continue using the command we can.

I remember adding the \since once (I think I did \since 18) and was told 
that I had not done it correctly, and just to remove it, so I would say 
that \since is not intuitive and use of it seems to be being avoided 
from what I have seen. If a new API went in now, is it since 16, 18, or 
19? Or 16.19, 18.9, etc.? I don't think it's *unhelpful* but it hasn't 
affected me a lot either way.

Something more useful I think is having a <since> in the xmldocs for 
individual applications, functions, and other user-facing things (not 
entire modules), to inform users about when certain things were added to 
Asterisk. That seems more useful in practice than \since in doxygen, and 
I think would have more of a beneficial impact, especially if it showed 
up on the wiki. (On my list of things to add at some point.)

NA

> Thoughts?
>
> [1] https://www.doxygen.nl/manual/commands.html#cmdsince
> [2] 
> https://github.com/asterisk/asterisk/blob/master/include/asterisk/stasis.h#L305
>