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

[Anton Khirnov]

On Thu, Nov 04, 2010 at 04:42:02PM +0100, Cyril Russo wrote:
> 
> 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.
> 
You're misunderstanding, that patch didn't deprecate anything. It simply
marked the stuff that _was already_ deprecated, to make transition to
new APIs easier.

> 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.
A simple git log+search reveals
commit 188585c88d0a62d90596847649d76ba6c4beb9f8
Author: stefano <stefano at b3059339-0415-0410-9bf9-f77b7e298cf2>
Date:   Tue Sep 28 22:23:58 2010 +0000

    Deprecate sws_getContext(), use sws_alloc_context() and
        sws_init_context() instead.

> 
> Recently, AVFormatContext::genre was deprecated but again, no
> pointer was added to the right "way" to get the genre's metadata.
Searching for 'genre' in doc/APIChanges shows that a new metadata API
was introduced 1.5 yrs ago and the old one was deprecated at the same
time. Alternatively searching for 'genre' in libavformat/avformat.h
would tell you how exactly to use the new API.

-- 
Anton Khirnov
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: Digital signature
URL: <http://lists.mplayerhq.hu/pipermail/ffmpeg-devel/attachments/20101104/ea64cf1a/attachment.pgp>