[asterisk-dev] Doxygen \since

[Dennis Buteyn]

On 1/13/22 20:12, 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.
>
> Thoughts?

Not so much a fan of Doxygen though I think there are two distinct 
documentation requirements. First, there are the user-facing API 
functions. These are dialplan functions, ARI, AMI and so forth. Knowing 
when a particular function was added / removed / changed is pretty 
important, especially when (as a third-party) one has to interface with 
systems running different versions of Asterisk.

Then there are the internal API functions for developing modules or 
making customizations. This is basically everything you'd find in 
include/asterisk. Git is pretty self-documenting when used properly and 
as the Asterisk source code is freely available, it does not take much 
effort to examine the history to know when something was added / removed 
/ changed. Git will usually also tell you who did it, why and how. When 
developing modules and/or making customizations, one will generally have 
the source code checked out anyways.

I think in the case of user-facing API functions, documenting when a 
particular function was added is a must. I have run into cases where 
this was pretty important. Sure, one can compare versions on the 
Asterisk Wiki but it is not that convenient. As for Internal API 
functions, Git already documents changes and you basically end up 
documenting twice.

-- 
Dennis Buteyn
Xorcom Ltd