Robert Shearman : kernel: Document some file functions.

[Alexandre Julliard]

Module: wine
Branch: refs/heads/master
Commit: 277dfb87710445e256d3c59f408062045078c8a7
URL:    http://source.winehq.org/git/?p=wine.git;a=commit;h=277dfb87710445e256d3c59f408062045078c8a7

Author: Robert Shearman <rob at codeweavers.com>
Date:   Mon Apr  3 16:26:10 2006 +0100

kernel: Document some file functions.

---

 dlls/kernel/file.c |   50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 50 insertions(+), 0 deletions(-)

diff --git a/dlls/kernel/file.c b/dlls/kernel/file.c
index 7f0edf3..0a70e14 100644
--- a/dlls/kernel/file.c
+++ b/dlls/kernel/file.c
@@ -614,6 +614,15 @@ BOOL WINAPI GetOverlappedResult(HANDLE h
 
 /***********************************************************************
  *             CancelIo                   (KERNEL32.@)
+ *
+ * Cancels pending I/O operations initiated by the current thread on a file.
+ *
+ * PARAMS
+ *  handle [I] File handle.
+ *
+ * RETURNS
+ *  Success: TRUE.
+ *  Failure: FALSE, check GetLastError().
  */
 BOOL WINAPI CancelIo(HANDLE handle)
 {
@@ -820,6 +829,17 @@ BOOL WINAPI GetFileInformationByHandle( 
 
 /***********************************************************************
  *           GetFileSize   (KERNEL32.@)
+ *
+ * Retrieve the size of a file.
+ *
+ * PARAMS
+ *  hFile        [I] File to retrieve size of.
+ *  filesizehigh [O] On return, the high bits of the file size.
+ *
+ * RETURNS
+ *  Success: The low bits of the file size.
+ *  Failure: INVALID_FILE_SIZE. As this is could also be a success value,
+ *           check GetLastError() for values other than ERROR_SUCCESS.
  */
 DWORD WINAPI GetFileSize( HANDLE hFile, LPDWORD filesizehigh )
 {
@@ -833,6 +853,16 @@ DWORD WINAPI GetFileSize( HANDLE hFile, 
 
 /***********************************************************************
  *           GetFileSizeEx   (KERNEL32.@)
+ *
+ * Retrieve the size of a file.
+ *
+ * PARAMS
+ *  hFile        [I] File to retrieve size of.
+ *  lpFileSIze   [O] On return, the size of the file.
+ *
+ * RETURNS
+ *  Success: TRUE.
+ *  Failure: FALSE, check GetLastError().
  */
 BOOL WINAPI GetFileSizeEx( HANDLE hFile, PLARGE_INTEGER lpFileSize )
 {
@@ -853,6 +883,15 @@ BOOL WINAPI GetFileSizeEx( HANDLE hFile,
 
 /**************************************************************************
  *           SetEndOfFile   (KERNEL32.@)
+ *
+ * Sets the current position as the end of the file.
+ *
+ * PARAMS
+ *  hFile [I] File handle.
+ *
+ * RETURNS
+ *  Success: TRUE.
+ *  Failure: FALSE, check GetLastError().
  */
 BOOL WINAPI SetEndOfFile( HANDLE hFile )
 {
@@ -1415,6 +1454,15 @@ HANDLE WINAPI CreateFileA( LPCSTR filena
 
 /***********************************************************************
  *           DeleteFileW   (KERNEL32.@)
+ *
+ * Delete a file.
+ *
+ * PARAMS
+ *  path [I] Path to the file to delete.
+ *
+ * RETURNS
+ *  Success: TRUE.
+ *  Failure: FALSE, check GetLastError().
  */
 BOOL WINAPI DeleteFileW( LPCWSTR path )
 {
@@ -1450,6 +1498,8 @@ BOOL WINAPI DeleteFileW( LPCWSTR path )
 
 /***********************************************************************
  *           DeleteFileA   (KERNEL32.@)
+ *
+ * See DeleteFileW.
  */
 BOOL WINAPI DeleteFileA( LPCSTR path )
 {