[FFmpeg-devel] [PATCH 6/6] doc: add API porting guide

[Andreas Cadhalpun]

On 08.08.2015 17:30, Clément Bœsch wrote:
> On Sat, Aug 08, 2015 at 01:37:37PM +0200, Andreas Cadhalpun wrote:
>> Signed-off-by: Andreas Cadhalpun <Andreas.Cadhalpun at googlemail.com>
>> ---
>>
>> It would be great if someone knowledgeable would fix the TODOs.
>> Lacking documentation it might be better to delay removal of those APIs.
>>
>> ---
>>  doc/API-porting-guide.txt | 62 +++++++++++++++++++++++++++++++++++++++++++++++
> 
> Why not, but this looks redundant with APIChange.

In a way it is, but it serves a different purpose.
For someone removing use of deprecated API from an existing program, APIchanges
contains a lot of useless information.
And unfortunately APIchanges doesn't even mention some deprecations, e.g.
FF_API_SWS_CPU_CAPS or FF_API_DEINTERLACE.

> It also gives no time information about when it was deprecated,

This could be added, but I'm not sure it's interesting enough for the target audience.

> when it's due for removal, etc.

I don't think that is known in advance.

But it might make sense to decide that in advance, and then it would
be useful to add that.

> Basically, it looks like a primitive copy of doc/APIChange that will be a
> pain to maintain over time.

But it should make it easier to remove deprecated APIs in the future.
However, that only works well if whenever something is deprecated this file
is updated with information how to replace the deprecated functionality.

Best regards,
Andreas