clarified

docs/libssh2_sftp_write.3

@@ -11,21 +11,26 @@ ssize_t
 libssh2_sftp_write(LIBSSH2_SFTP_HANDLE *handle, const char *buffer, size_t count);
 
 .SH DESCRIPTION
-\fIhandle\fP - SFTP File Handle as returned by 
-.BR libssh2_sftp_open_ex(3)
+\fIhandle\fP - SFTP file handle as returned by \fIlibssh2_sftp_open_ex(3)\fP.
 
-\fIbuffer\fP - Pre-initialized data buffer to write to the LIBSSH2_SFTP_HANDLE.
+\fIbuffer\fP - points to the data to send off
 
-\fIcount\fP - Number of bytes from buffer to write. Note that it may not 
-be possible to write all bytes as requested.
-
-Write a block of data to a LIBSSH2_SFTP_HANDLE. This method is modeled after the POSIX write() function and uses the same calling semantics.
+\fIcount\fP - Number of bytes from 'buffer' to write. Note that it may not be
+possible to write all bytes as requested.
 
+\fBlibssh2_sftp_write(3)\fP writes a block of data to the SFTP server. This
+method is modeled after the POSIX write() function and uses the same calling
+semantics.
 .SH RETURN VALUE
-Actual number of bytes written or negative on failure.  It returns
-LIBSSH2_ERROR_EAGAIN when it would otherwise block. While
-LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se.
+Actual number of bytes written or negative on failure.
 
+If used in non-blocking mode, it returns LIBSSH2_ERROR_EAGAIN when it would
+otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it isn't
+really a failure per se.
+
+If this function returns 0 (zero) it should not be considered an error, but
+simply that there was no error but yet no payload data got sent to the other
+end.
 .SH ERRORS
 \fILIBSSH2_ERROR_ALLOC\fP -  An internal memory allocation call failed.
 
@@ -36,6 +41,5 @@ LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se.
 \fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was 
 received on the socket, or an SFTP operation caused an errorcode to 
 be returned by the server.
-
 .SH SEE ALSO
 .BR libssh2_sftp_open_ex(3)