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
--
_____________________________________________________________________
-- Bandwidth and Colocation Provided by http://www.api-digital.com --
asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
http://lists.digium.com/mailman/listinfo/asterisk-dev
