[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: An unexpected effect of new 'deprecated' tags.

From: Stefan Küng <tortoisesvn_at_gmail.com>
Date: Thu, 28 Aug 2008 17:57:05 +0200

Arfrever Frehtes Taifersar Arahesis wrote:
> 2008-08-28 05:44:38 Karl Fogel napisał(a):
>> The new 'deprecated' tags produce a slew of warnings in our build now.
>> That's great -- in some places we're still using deprecated functions,
>> and those places need to be fixed.
>> But even after we fix them all, there will still be warnings from the
>> compatibility wrapper functions. For example, imagine these:
>> svn_foo_bar5()
>> svn_foo_bar4()
>> svn_foo_bar3()
>> svn_foo_bar2()
>> svn_foo_bar()
>> How would we usually implement that compatibility stack? Like this:
>> svn_foo_bar5() { ...; }
>> svn_foo_bar4() { return svn_foo_bar5(); }
>> svn_foo_bar3() { return svn_foo_bar4(); }
>> svn_foo_bar2() { return svn_foo_bar3(); }
>> svn_foo_bar() { return svn_foo_bar2(); }
>> The discerning reader will spot the problem immediately :-).
>> Now, what do we do to avoid being spammed with compilation warnings
>> for the rest of our lives? Just always reimplement everything in
>> terms of the newest function?

One thing that bugged me about the deprecated functions for some time
now is the doxygen comment. All deprecated functions only have a text
like "\deprecated: provided for backward compatibility with the 1.x
API". But it doesn't say which function to use instead.

For most functions, that's not a big problem: only look for a function
with the same name but a higher number at the end (e.g.,
svn_client_merge3 instead of svn_client_merge2). But there are some
functions which don't have that:

svn_client_ls3 is deprecated, but there is no svn_client_ls4
svn_client_get_* (auth provider functions) also have no 'higher number

For svn_client_ls3, the function to use would be svn_client_list2, and
for the auth provider functions it would be the svn_auth_get_* functions.

A user who doesn't follow the commits has to search the whole docs to
find the new function to use.

So I suggest to extend those doxygen comments like this:
"\deprecated: provided for backward compatibility with the 1.x API. Use
svn_client_list() instead."

This would make it immediately clear which function superseeds the
deprecated one.



  oo  // \\      "De Chelonian Mobile"
 (_,\/ \_/ \     TortoiseSVN
   \ \_/_\_/>    The coolest Interface to (Sub)Version Control
   /_/   \_\     http://tortoisesvn.net

Received on 2008-08-28 17:57:38 CEST

This is an archived mail posted to the Subversion Dev mailing list.

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.