Enhance SFTP client & server docs re: posix_rename and its relation t…

…o rename

Fixes paramiko#1016, re paramiko#1012

paramiko/sftp_client.py

@@ -366,6 +366,11 @@ def rename(self, oldpath, newpath):
         """
         Rename a file or folder from ``oldpath`` to ``newpath``.
 
+        .. note::
+            This method implements 'standard' SFTP ``RENAME`` behavior; those
+            seeking the OpenSSH "POSIX rename" extension behavior should use
+            `posix_rename`.
+
         :param str oldpath:
             existing name of the file or folder
         :param str newpath:
@@ -392,6 +397,8 @@ def posix_rename(self, oldpath, newpath):
         :raises:
             ``IOError`` -- if ``newpath`` is a folder, posix-rename is not
             supported by the server or something else goes wrong
+
+        :versionadded: 2.2
         """
         oldpath = self._adjust_cwd(oldpath)
         newpath = self._adjust_cwd(newpath)

paramiko/sftp_si.py

@@ -194,6 +194,11 @@ def rename(self, oldpath, newpath):
             ``newpath`` already exists.  (The rename operation should be
             non-desctructive.)
 
+        .. note::
+            This method implements 'standard' SFTP ``RENAME`` behavior; those
+            seeking the OpenSSH "POSIX rename" extension behavior should use
+            `posix_rename`.
+
         :param str oldpath:
             the requested path (relative or absolute) of the existing file.
         :param str newpath: the requested new path of the file.
@@ -210,6 +215,8 @@ def posix_rename(self, oldpath, newpath):
             the requested path (relative or absolute) of the existing file.
         :param str newpath: the requested new path of the file.
         :return: an SFTP error code `int` like ``SFTP_OK``.
+
+        :versionadded: 2.2
         """
         return SFTP_OP_UNSUPPORTED