[FFmpeg-devel] [RFC] Need an additional maintainer rule when deprecating functions

[Cyril Russo]

Hi all,

   I would like to know if it's possible for those pushing 
"attribute_deprecated" patch to be force to document the reason of the 
change and mainly, what is the "new" way of doing the same thing as the 
previous version.

As an example, recently, the sws_getContext was marked deprecated, but 
there was not any comment whatsoever about what to use instead. By 
digging in the source code, one could find sws_getCachedContext but the 
name is a bit misleading since you might not have a context at first and 
the documentation didn't say if it was valid to use a NULL context.
The other solution is to do what is done in initial getContext 
(initContext and dealing with the context members), but this means more 
code in the user's code, with probably more bug too to all projects 
using this code. When getContext will be removed, it'll be very 
difficult for the end user to figure out how to even *start* using the 
swscale library.

Recently, AVFormatContext::genre was deprecated but again, no pointer 
was added to the right "way" to get the genre's metadata.

So, what do you think, shouldn't adding a "@deprecated" comment above 
with a pointer on the right way to use the function be the new rule for 
deprecating things ?

Cheers,
Cyril