Re: [AD] Deprecated functions

[Peter Wang <novalazy@xxxxxxxxxx>]

On 2007-06-23, Matthew Leverton <meffer@xxxxxxxxxx> wrote:
> On 6/23/07, Peter Wang <novalazy@xxxxxxxxxx> wrote:
> > That reminds me, removing the documentation of deprecated functions was
> > a bad idea.  Especially if you're trying to transition from the old
> > function to the new, you'd want to be able to look them up.
> >
> I think this page is sufficient:
> 
> http://www.allegro.cc/manual/miscellaneous/api-compatibility-information/

That's too light on details.  Also, you can't just press K in vim (for
example) to bring up the man page for a deprecated function.  Consider
if you're writing an addon library just after version x was released,
and wanted to retain compatibility with version (x-k).

> If there are missing details, then they could be added. I don't think
> they should stay in the manual next to the other entries, as the whole
> point is to discourage usage of them.

I think the deprecated warnings plus some sort of marker in the
documentation would be enough discouragement.

Another thing I have thought would be nice is for the documentation of
every API entry to indicate which version of Allegro they were first
introduced in (going back as far as 1.0 if possible!), and when they
became deprecated.  It might be an interesting exercise for someone to
extract this information automatically :-)

Peter