[PATCH 1 of 2] util: state docstring of rename more precisely

[Adrian Buehlmann]

On 07.10.2009 22:19, Greg Ward wrote:
> On Wed, Oct 7, 2009 at 4:11 PM, Adrian Buehlmann <adrian at cadifra.com> wrote:
>> # HG changeset patch
>> # User Adrian Buehlmann <adrian at cadifra.com>
>> # Date 1254939403 -7200
>> # Node ID 0a8a3f3fadbb925f0e28f716a5544b68d803709f
>> # Parent  98feea5659d902bdca558ea7c9fed7670eb4f5e9
>> util: state docstring of rename more precisely
>>
>> diff --git a/mercurial/util.py b/mercurial/util.py
>> --- a/mercurial/util.py
>> +++ b/mercurial/util.py
>> @@ -400,7 +400,7 @@ def lexists(filename):
>>     return True
>>
>>  def rename(src, dst):
>> -    """forcibly rename a file"""
>> +    '''atomically rename file src to dst, replacing dst if it exists'''
> 
> Isn't this patch rather pointless, given that you're about to move the
> code in question wholesale?  Why not just rewrite the docstring in the
> move-to-windows.py patch?

What I was thinking:

I prefer not to change code blocks that I just move.
The whole rename function is moved into windows.py in the second
patch without changing it.

The new docstring is a more stringent specification of what
the function is really supposed to do. And it actually does
it (as close as possible on Windows, if dst already exists).

Changing the docstring in a first separate step emphasizes
the fact that I have first thought about what that function
is really supposed to do and I have verified that that is
compatible with the spec of os.rename for posix systems
(i.e. unix) in the second step.

The later move then tries to make clear that I haven't changed
the function "behind your back" while moving it.

BTW, thanks for proposing to move this into windows.py.
The new separation of posix.py and windows.py is really
neat.