deprecated_function should offer an explanation

[Ian Bicking]

There should be an optional (but generally used) second argument to deprecated_function that suggests what should be used in lieu of the deprecated function.

My first thought seeing a deprecation: deprecated for what?

[Aaron Bentley (abentley)]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Ian Bicking wrote:
| Public bug reported:
| https://launchpad.net/malone/bugs/35947
|
| Affects: bzr (upstream)
| Severity: Normal
| Priority: (none set)
| Status: Unconfirmed
|
| Description:
| There should be an optional (but generally used) second argument to
| deprecated_function that suggests what should be used in lieu of the
| deprecated function.
|
| My first thought seeing a deprecation: deprecated for what?

Our style is to put an explanation of the reasons for
deprecation/alternatives to examine in the doctext of the deprecated
function.

Deprecations are for development versions only. Released versions
should produce no deprecation warnings.

Aaron

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFEIMmp0F+nu1YWqI0RAsmHAJwOeMCHCn2Rtc4P4i0nKlYyuh6D5ACfbJNC
K0r3dt7R6ra9/QKof9/NCjU=
=1/yp
-----END PGP SIGNATURE-----

[Robert Collins (lifeless)]

On Wed, 2006-03-22 at 03:08 +0000, Ian Bicking wrote:
> Public bug reported:
> https://launchpad.net/malone/bugs/35947
>
> Affects: bzr (upstream)
> Severity: Normal
> Priority: (none set)
> Status: Unconfirmed
>
> Description:
> There should be an optional (but generally used) second argument to
> deprecated_function that suggests what should be used in lieu of the
> deprecated function.
>
> My first thought seeing a deprecation: deprecated for what?

Thats a good point. We have been putting that in the docstring as Aaron
says, but having it in the decorator still allows it to be put in the
docstring (by the decorator) and does not mean it needs to be put in the
Warning: output.

Patches accepted :).

Rob

--
GPG key available at: <http://www.robertcollins.net/keys.txt>.