Improve c2man Documented-Total count. Changes:

dlls/kernel/comm.c

@@ -2122,7 +2122,7 @@ static BOOL COMM_WaitCommEvent(
  * Interesting things (events) are set by calling SetCommMask before
  * this function is called.
  *
- * RETURNS:
+ * RETURNS
  *   TRUE if successful
  *   FALSE if failure
  *
@@ -2286,7 +2286,7 @@ BOOL WINAPI CommConfigDialogA(
 /***********************************************************************
  *           CommConfigDialogW   (KERNEL32.@)
  *
- * see CommConfigDialogA for more info
+ * See CommConfigDialogA.
  */
 BOOL WINAPI CommConfigDialogW(
     LPCWSTR lpszDevice,        /* [in] name of communications device */

dlls/kernel/computername.c

@@ -564,10 +564,14 @@ static WCHAR netbios_char ( WCHAR wc )
 /******************************************************************************
  * SetComputerNameW [KERNEL32.@]
  *
+ * Set a new NetBIOS name for the local computer.
+ *
  * PARAMS
  *    lpComputerName [I] Address of new computer name
  *
- * RETURNS STD
+ * RETURNS
+ *    Success: TRUE
+ *    Failure: FALSE
  */
 BOOL WINAPI SetComputerNameW( LPCWSTR lpComputerName )
 {
@@ -634,6 +638,8 @@ out:
 
 /******************************************************************************
  * SetComputerNameA [KERNEL32.@]
+ *
+ * See SetComputerNameW.
  */
 BOOL WINAPI SetComputerNameA( LPCSTR lpComputerName )
 {

dlls/kernel/console.c

@@ -456,15 +456,9 @@ BOOL WINAPI WriteConsoleOutputW( HANDLE hConsoleOutput, const CHAR_INFO *lpBuffe
 
 
 /******************************************************************************
- * WriteConsoleOutputCharacterA [KERNEL32.@]  Copies character to consecutive
- * 					      cells in the console screen buffer
+ * WriteConsoleOutputCharacterA [KERNEL32.@]
  *
- * PARAMS
- *    hConsoleOutput    [I] Handle to screen buffer
- *    str               [I] Pointer to buffer with chars to write
- *    length            [I] Number of cells to write to
- *    coord             [I] Coords of first cell
- *    lpNumCharsWritten [O] Pointer to number of cells written
+ * See WriteConsoleOutputCharacterW.
  */
 BOOL WINAPI WriteConsoleOutputCharacterA( HANDLE hConsoleOutput, LPCSTR str, DWORD length,
                                           COORD coord, LPDWORD lpNumCharsWritten )
@@ -533,16 +527,7 @@ BOOL WINAPI WriteConsoleOutputAttribute( HANDLE hConsoleOutput, CONST WORD *attr
 /******************************************************************************
  * FillConsoleOutputCharacterA [KERNEL32.@]
  *
- * PARAMS
- *    hConsoleOutput    [I] Handle to screen buffer
- *    ch                [I] Character to write
- *    length            [I] Number of cells to write to
- *    coord             [I] Coords of first cell
- *    lpNumCharsWritten [O] Pointer to number of cells written
- *
- * RETURNS
- *    Success: TRUE
- *    Failure: FALSE
+ * See FillConsoleOutputCharacterW.
  */
 BOOL WINAPI FillConsoleOutputCharacterA( HANDLE hConsoleOutput, CHAR ch, DWORD length,
                                          COORD coord, LPDWORD lpNumCharsWritten )
@@ -928,6 +913,8 @@ BOOL WINAPI SetConsoleTitleA( LPCSTR title )
 
 /***********************************************************************
  *            GetConsoleTitleA   (KERNEL32.@)
+ *
+ * See GetConsoleTitleW.
  */
 DWORD WINAPI GetConsoleTitleA(LPSTR title, DWORD size)
 {
@@ -1308,8 +1295,9 @@ BOOL WINAPI ReadConsoleInputW(HANDLE hConsoleInput, PINPUT_RECORD lpBuffer,
 
 
 /******************************************************************************
- * WriteConsoleOutputCharacterW [KERNEL32.@]  Copies character to consecutive
- * 					      cells in the console screen buffer
+ * WriteConsoleOutputCharacterW [KERNEL32.@]
+ * 
+ * Copy character to consecutive cells in the console screen buffer.
  *
  * PARAMS
  *    hConsoleOutput    [I] Handle to screen buffer
@@ -2040,7 +2028,9 @@ BOOL WINAPI WriteConsoleA(HANDLE hConsoleOutput, LPCVOID lpBuffer, DWORD nNumber
  *    hConsoleOutput   [I] Handle of console screen buffer
  *    dwCursorPosition [I] New cursor position coordinates
  *
- * RETURNS STD
+ * RETURNS
+ *    Success: TRUE
+ *    Failure: FALSE
  */
 BOOL WINAPI SetConsoleCursorPosition(HANDLE hcon, COORD pos)
 {

dlls/kernel/environ.c

@@ -94,8 +94,8 @@ LPWSTR WINAPI GetCommandLineW(void)
 
 
 /***********************************************************************
- *           GetEnvironmentStrings    (KERNEL32.@)
  *           GetEnvironmentStringsA   (KERNEL32.@)
+ *           GetEnvironmentStrings    (KERNEL32.@)
  */
 LPSTR WINAPI GetEnvironmentStringsA(void)
 {

dlls/kernel/file.c

@@ -1397,6 +1397,8 @@ HANDLE WINAPI CreateFileW( LPCWSTR filename, DWORD access, DWORD sharing,
 
 /*************************************************************************
  *              CreateFileA              (KERNEL32.@)
+ *
+ * See CreateFileW.
  */
 HANDLE WINAPI CreateFileA( LPCSTR filename, DWORD access, DWORD sharing,
                            LPSECURITY_ATTRIBUTES sa, DWORD creation,
@@ -1976,6 +1978,8 @@ BOOL WINAPI GetFileAttributesExA( LPCSTR name, GET_FILEEX_INFO_LEVELS level, LPV
 /******************************************************************************
  *           GetCompressedFileSizeW   (KERNEL32.@)
  *
+ * Get the actual number of bytes used on disk.
+ *
  * RETURNS
  *    Success: Low-order doubleword of number of bytes
  *    Failure: INVALID_FILE_SIZE
@@ -2023,6 +2027,8 @@ DWORD WINAPI GetCompressedFileSizeW(
 
 /******************************************************************************
  *           GetCompressedFileSizeA   (KERNEL32.@)
+ *
+ * See GetCompressedFileSizeW.
  */
 DWORD WINAPI GetCompressedFileSizeA( LPCSTR name, LPDWORD size_high )
 {

dlls/kernel/file16.c

@@ -449,11 +449,16 @@ UINT16 WINAPI GetSystemDirectory16( LPSTR path, UINT16 count )
 
 /***********************************************************************
  *           GetDriveType   (KERNEL.136)
- * This function returns the type of a drive in Win16.
- * Note that it returns DRIVE_REMOTE for CD-ROMs, since MSCDEX uses the
- * remote drive API. The return value DRIVE_REMOTE for CD-ROMs has been
- * verified on Win 3.11 and Windows 95. Some programs rely on it, so don't
- * do any pseudo-clever changes.
+ * Get the type of a drive in Win16.
+ *
+ * RETURNS
+ *  The type of the Drive. For a list see GetDriveTypeW from kernel32.
+ *
+ * NOTES
+ *  Note that it returns DRIVE_REMOTE for CD-ROMs, since MSCDEX uses the
+ *  remote drive API. The return value DRIVE_REMOTE for CD-ROMs has been
+ *  verified on Win 3.11 and Windows 95. Some programs rely on it, so don't
+ *  do any pseudo-clever changes.
  */
 UINT16 WINAPI GetDriveType16( UINT16 drive ) /* [in] number (NOT letter) of drive */
 {

dlls/kernel/global16.c

@@ -257,6 +257,9 @@ HGLOBAL16 GLOBAL_Alloc( UINT16 flags, DWORD size, HGLOBAL16 hOwner, unsigned cha
 /***********************************************************************
  *           GlobalAlloc     (KERNEL.15)
  *           GlobalAlloc16   (KERNEL32.24)
+ *
+ * Allocate a global memory object.
+ *
  * RETURNS
  *	Handle: Success
  *	NULL: Failure
@@ -275,6 +278,9 @@ HGLOBAL16 WINAPI GlobalAlloc16(
 
 /***********************************************************************
  *           GlobalReAlloc     (KERNEL.16)
+ *
+ * Change the size or attributes of a global memory object.
+ *
  * RETURNS
  *	Handle: Success
  *	NULL: Failure
@@ -568,6 +574,9 @@ void WINAPI GlobalChangeLockCount16( HGLOBAL16 handle, INT16 delta,
 /***********************************************************************
  *           GlobalSize     (KERNEL.20)
  *           GlobalSize16   (KERNEL32.32)
+ * 
+ * Get the current size of a global memory object.
+ *
  * RETURNS
  *	Size in bytes of object
  *	0: Failure
@@ -585,6 +594,9 @@ DWORD WINAPI GlobalSize16(
 
 /***********************************************************************
  *           GlobalHandle   (KERNEL.21)
+ *
+ * Get the handle associated with a pointer to the global memory block.
+ *
  * NOTES
  *	Why is GlobalHandleToSel used here with the sel as input?
  *
@@ -620,6 +632,8 @@ DWORD WINAPI GlobalHandleNoRIP16( WORD sel )
 /***********************************************************************
  *           GlobalFlags     (KERNEL.22)
  *
+ * Get information about a global memory object.
+ *
  * NOTES
  *	Should this return GMEM_INVALID_HANDLE instead of 0 on invalid
  *	handle?
@@ -767,6 +781,9 @@ DWORD WINAPI GetFreeSpace16( UINT16 wFlags )
 
 /***********************************************************************
  *           GlobalDOSAlloc   (KERNEL.184)
+ *
+ * Allocate memory in the first MB.
+ *
  * RETURNS
  *	Address (HW=Paragraph segment; LW=Selector)
  */
@@ -793,6 +810,9 @@ DWORD WINAPI GlobalDOSAlloc16(
 
 /***********************************************************************
  *           GlobalDOSFree      (KERNEL.185)
+ *
+ * Free memory allocated with GlobalDOSAlloc
+ *
  * RETURNS
  *	NULL: Success
  *	sel: Failure

dlls/kernel/heap.c

@@ -117,6 +117,9 @@ inline static HANDLE HEAP_CreateSystemHeap(void)
 
 /***********************************************************************
  *           HeapCreate   (KERNEL32.@)
+ *
+ * Create a heap object.
+ *
  * RETURNS
  *	Handle of heap: Success
  *	NULL: Failure
@@ -145,6 +148,9 @@ HANDLE WINAPI HeapCreate(
 
 /***********************************************************************
  *           HeapDestroy   (KERNEL32.@)
+ *
+ * Destroy a heap object.
+ *
  * RETURNS
  *	TRUE: Success
  *	FALSE: Failure
@@ -323,6 +329,9 @@ typedef struct __GLOBAL32_INTERN
 
 /***********************************************************************
  *           GlobalAlloc   (KERNEL32.@)
+ *
+ * Allocate a global memory object.
+ *
  * RETURNS
  *      Handle: Success
  *      NULL: Failure
@@ -384,6 +393,9 @@ HGLOBAL WINAPI GlobalAlloc(
 
 /***********************************************************************
  *           GlobalLock   (KERNEL32.@)
+ *
+ * Lock a global memory object.
+ *
  * RETURNS
  *      Pointer to first byte of block
  *      NULL: Failure
@@ -429,6 +441,9 @@ LPVOID WINAPI GlobalLock(
 
 /***********************************************************************
  *           GlobalUnlock   (KERNEL32.@)
+ *
+ * Unlock a global memory object.
+ *
  * RETURNS
  *      TRUE: Object is still locked
  *      FALSE: Object is unlocked
@@ -474,7 +489,8 @@ BOOL WINAPI GlobalUnlock(
 
 /***********************************************************************
  *           GlobalHandle   (KERNEL32.@)
- * Returns the handle associated with the specified pointer.
+ *
+ * Get the handle associated with the pointer to a global memory block.
  *
  * RETURNS
  *      Handle: Success
@@ -535,6 +551,9 @@ HGLOBAL WINAPI GlobalHandle(
 
 /***********************************************************************
  *           GlobalReAlloc   (KERNEL32.@)
+ *
+ * Change the size or attributes of a global memory object.
+ *
  * RETURNS
  *      Handle: Success
  *      NULL: Failure
@@ -648,6 +667,9 @@ HGLOBAL WINAPI GlobalReAlloc(
 
 /***********************************************************************
  *           GlobalFree   (KERNEL32.@)
+ *
+ * Free a global memory object.
+ *
  * RETURNS
  *      NULL: Success
  *      Handle: Failure
@@ -700,6 +722,9 @@ HGLOBAL WINAPI GlobalFree(
 
 /***********************************************************************
  *           GlobalSize   (KERNEL32.@)
+ *
+ * Get the size of a global memory object.
+ *
  * RETURNS
  *      Size in bytes of the global memory object
  *      0: Failure
@@ -783,7 +808,8 @@ VOID WINAPI GlobalUnfix(HGLOBAL hmem)
 
 /***********************************************************************
  *           GlobalFlags   (KERNEL32.@)
- * Returns information about the specified global memory object
+ *
+ * Get information about a global memory object.
  *
  * NOTES
  *      Should this return GMEM_INVALID_HANDLE on invalid handle?
@@ -834,9 +860,16 @@ SIZE_T WINAPI GlobalCompact( DWORD minfree )
 
 /***********************************************************************
  *           LocalAlloc   (KERNEL32.@)
+ *
+ * Allocate a local memory object.
+ *
  * RETURNS
  *	Handle: Success
  *	NULL: Failure
+ *
+ * NOTES
+ *  Windows memory management does not provide a separate local heap
+ *  and global heap.
  */
 HLOCAL WINAPI LocalAlloc(
                 UINT flags, /* [in] Allocation attributes */
@@ -857,9 +890,16 @@ SIZE_T WINAPI LocalCompact( UINT minfree )
 
 /***********************************************************************
  *           LocalFlags   (KERNEL32.@)
+ *
+ * Get information about a local memory object.
+ *
  * RETURNS
  *	Value specifying allocation flags and lock count.
  *	LMEM_INVALID_HANDLE: Failure
+ *
+ * NOTES
+ *  Windows memory management does not provide a separate local heap
+ *  and global heap.
  */
 UINT WINAPI LocalFlags(
               HLOCAL handle /* [in] Handle of memory object */
@@ -870,9 +910,16 @@ UINT WINAPI LocalFlags(
 
 /***********************************************************************
  *           LocalFree   (KERNEL32.@)
+ *
+ * Free a local memory object.
+ *
  * RETURNS
  *	NULL: Success
  *	Handle: Failure
+ *
+ * NOTES
+ *  Windows memory management does not provide a separate local heap
+ *  and global heap.
  */
 HLOCAL WINAPI LocalFree(
                 HLOCAL handle /* [in] Handle of memory object */
@@ -883,12 +930,19 @@ HLOCAL WINAPI LocalFree(
 
 /***********************************************************************
  *           LocalHandle   (KERNEL32.@)
+ *
+ * Get the handle associated with the pointer to a local memory block.
+ *
  * RETURNS
  *	Handle: Success
  *	NULL: Failure
+ *
+ * NOTES
+ *  Windows memory management does not provide a separate local heap
+ *  and global heap.
  */
 HLOCAL WINAPI LocalHandle(
-                LPCVOID ptr /* [in] Address of local memory object */
+                LPCVOID ptr /* [in] Address of local memory block */
 ) {
     return (HLOCAL)GlobalHandle( ptr );
 }
@@ -902,6 +956,10 @@ HLOCAL WINAPI LocalHandle(
  * RETURNS
  *	Pointer: Success
  *	NULL: Failure
+ *
+ * NOTES
+ *  Windows memory management does not provide a separate local heap
+ *  and global heap.
  */
 LPVOID WINAPI LocalLock(
               HLOCAL handle /* [in] Address of local memory object */
@@ -912,9 +970,16 @@ LPVOID WINAPI LocalLock(
 
 /***********************************************************************
  *           LocalReAlloc   (KERNEL32.@)
+ *
+ * Change the size or attributes of a local memory object.
+ *
  * RETURNS
  *	Handle: Success
  *	NULL: Failure
+ *
+ * NOTES
+ *  Windows memory management does not provide a separate local heap
+ *  and global heap.
  */
 HLOCAL WINAPI LocalReAlloc(
                 HLOCAL handle, /* [in] Handle of memory object */
@@ -936,9 +1001,16 @@ SIZE_T WINAPI LocalShrink( HGLOBAL handle, UINT newsize )
 
 /***********************************************************************
  *           LocalSize   (KERNEL32.@)
+ *
+ * Get the size of a local memory object.
+ *
  * RETURNS
  *	Size: Success
  *	0: Failure
+ *
+ * NOTES
+ *  Windows memory management does not provide a separate local heap
+ *  and global heap.
  */
 SIZE_T WINAPI LocalSize(
               HLOCAL handle /* [in] Handle of memory object */
@@ -949,9 +1021,16 @@ SIZE_T WINAPI LocalSize(
 
 /***********************************************************************
  *           LocalUnlock   (KERNEL32.@)
+ *
+ * Unlock a local memory object.
+ *
  * RETURNS
  *	TRUE: Object is still locked
  *	FALSE: Object is unlocked
+ *
+ * NOTES
+ *  Windows memory management does not provide a separate local heap
+ *  and global heap.
  */
 BOOL WINAPI LocalUnlock(
               HLOCAL handle /* [in] Handle of memory object */
@@ -966,10 +1045,11 @@ BOOL WINAPI LocalUnlock(
  * This is an undocumented KERNEL32 function that
  * SMapLS's a GlobalAlloc'ed buffer.
  *
- * Input:   EDI register: size of buffer to allocate
- * Output:  EDI register: pointer to buffer
+ * RETURNS
+ *       EDI register: pointer to buffer
  *
- * Note: The buffer is preceded by 8 bytes:
+ * NOTES
+ *       The buffer is preceded by 8 bytes:
  *        ...
  *       edi+0   buffer
  *       edi-4   SEGPTR to buffer
@@ -978,8 +1058,9 @@ BOOL WINAPI LocalUnlock(
  *
  *       The SEGPTR is used by the caller!
  */
-void WINAPI __regs_AllocMappedBuffer( CONTEXT86 *context )
-{
+void WINAPI __regs_AllocMappedBuffer(
+              CONTEXT86 *context /* [in] EDI register: size of buffer to allocate */
+) {
     HGLOBAL handle = GlobalAlloc(0, context->Edi + 8);
     DWORD *buffer = (DWORD *)GlobalLock(handle);
     DWORD ptr = 0;
@@ -1011,10 +1092,12 @@ DEFINE_REGS_ENTRYPOINT( AllocMappedBuffer, 0, 0 );
  *
  * Free a buffer allocated by AllocMappedBuffer
  *
- * Input: EDI register: pointer to buffer
+ * RETURNS
+ *  Nothing.
  */
-void WINAPI __regs_FreeMappedBuffer( CONTEXT86 *context )
-{
+void WINAPI __regs_FreeMappedBuffer(
+              CONTEXT86 *context /* [in] EDI register: pointer to buffer */
+) {
     if (context->Edi)
     {
         DWORD *buffer = (DWORD *)context->Edi - 2;

dlls/kernel/locale.c

@@ -1766,7 +1766,7 @@ LCID WINAPI ConvertDefaultLocale( LCID lcid )
  *  lcid  [I] LCID of the locale to check
  *  flags [I] LCID_SUPPORTED = Valid, LCID_INSTALLED = Valid and installed on the system
  *
- * RETURN
+ * RETURNS
  *  TRUE,  if lcid is valid,
  *  FALSE, otherwise.
  *

dlls/kernel/module.c

@@ -456,6 +456,8 @@ BOOL WINAPI GetBinaryTypeW( LPCWSTR lpApplicationName, LPDWORD lpBinaryType )
 /***********************************************************************
  *             GetBinaryTypeA                     [KERNEL32.@]
  *             GetBinaryType                      [KERNEL32.@]
+ *
+ * See GetBinaryTypeW.
  */
 BOOL WINAPI GetBinaryTypeA( LPCSTR lpApplicationName, LPDWORD lpBinaryType )
 {

dlls/kernel/path.c

@@ -810,6 +810,8 @@ DWORD WINAPI SearchPathW( LPCWSTR path, LPCWSTR name, LPCWSTR ext, DWORD buflen,
 
 /***********************************************************************
  *           SearchPathA   (KERNEL32.@)
+ *
+ * See SearchPathW.
  */
 DWORD WINAPI SearchPathA( LPCSTR path, LPCSTR name, LPCSTR ext,
                           DWORD buflen, LPSTR buffer, LPSTR *lastpart )

dlls/kernel/string.c

@@ -170,8 +170,8 @@ SEGPTR WINAPI lstrcat16( SEGPTR dst, LPCSTR src )
 
 
 /***********************************************************************
- *           lstrcat    (KERNEL32.@)
  *           lstrcatA   (KERNEL32.@)
+ *           lstrcat    (KERNEL32.@)
  */
 LPSTR WINAPI lstrcatA( LPSTR dst, LPCSTR src )
 {
@@ -234,8 +234,8 @@ SEGPTR WINAPI lstrcpy16( SEGPTR dst, LPCSTR src )
 
 
 /***********************************************************************
- *           lstrcpy    (KERNEL32.@)
  *           lstrcpyA   (KERNEL32.@)
+ *           lstrcpy    (KERNEL32.@)
  */
 LPSTR WINAPI lstrcpyA( LPSTR dst, LPCSTR src )
 {
@@ -284,8 +284,8 @@ SEGPTR WINAPI lstrcpyn16( SEGPTR dst, LPCSTR src, INT16 n )
 
 
 /***********************************************************************
- *           lstrcpyn    (KERNEL32.@)
  *           lstrcpynA   (KERNEL32.@)
+ *           lstrcpyn    (KERNEL32.@)
  *
  * Note: this function differs from the UNIX strncpy, it _always_ writes
  * a terminating \0.
@@ -362,8 +362,8 @@ INT16 WINAPI lstrlen16( LPCSTR str )
 
 
 /***********************************************************************
- *           lstrlen    (KERNEL32.@)
  *           lstrlenA   (KERNEL32.@)
+ *           lstrlen    (KERNEL32.@)
  */
 INT WINAPI lstrlenA( LPCSTR str )
 {

dlls/kernel/sync.c

@@ -1596,6 +1596,8 @@ BOOL WINAPI CreatePipe( PHANDLE hReadPipe, PHANDLE hWritePipe,
 
 /******************************************************************************
  * CreateMailslotA [KERNEL32.@]
+ *
+ * See CreatMailslotW.
  */
 HANDLE WINAPI CreateMailslotA( LPCSTR lpName, DWORD nMaxMessageSize,
                                DWORD lReadTimeout, LPSECURITY_ATTRIBUTES sa )

dlls/kernel/thread.c

@@ -649,6 +649,9 @@ __ASM_GLOBAL_FUNC( GetCurrentThreadId, ".byte 0x64\n\tmovl 0x24,%eax\n\tret" )
  *		SetLastError (KERNEL32.@)
  *
  * Sets the last-error code.
+ *
+ * RETURNS
+ * Nothing.
  */
 void WINAPI SetLastError( DWORD error ) /* [in] Per-thread error code */
 {
@@ -659,7 +662,10 @@ void WINAPI SetLastError( DWORD error ) /* [in] Per-thread error code */
  *		GetLastError (KERNEL.148)
  *              GetLastError (KERNEL32.@)
  *
- * Returns last-error code.
+ * Get the last-error code.
+ *
+ * RETURNS
+ *  last-error code.
  */
 DWORD WINAPI GetLastError(void)
 {
@@ -670,7 +676,10 @@ DWORD WINAPI GetLastError(void)
  *		GetCurrentProcessId (KERNEL.471)
  *		GetCurrentProcessId (KERNEL32.@)
  *
- * Returns process identifier.
+ * Get the current process identifier.
+ *
+ * RETURNS
+ *  current process identifier
  */
 DWORD WINAPI GetCurrentProcessId(void)
 {
@@ -681,7 +690,10 @@ DWORD WINAPI GetCurrentProcessId(void)
  *		GetCurrentThreadId (KERNEL.462)
  *		GetCurrentThreadId (KERNEL32.@)
  *
- * Returns thread identifier.
+ * Get the current thread identifier.
+ *
+ * RETURNS
+ *  current thread identifier
  */
 DWORD WINAPI GetCurrentThreadId(void)
 {

dlls/kernel/thunk.c

@@ -996,6 +996,9 @@ DEFINE_REGS_ENTRYPOINT( QT_ThunkPrime, 0, 0 );
  * 	00: DWORD	length
  *	04: SEGPTR	address for thunkbuffer pointer
  * [ok probably]
+ *
+ * RETURNS
+ *  Nothing.
  */
 VOID WINAPI ThunkInitSL(
 	LPBYTE thunk,		/* [in] start of thunkbuffer */
@@ -1055,6 +1058,9 @@ void WINAPI SSConfirmSmallStack( CONTEXT86 *context )
  *
  * And YES, I've seen nr=48 (somewhere in the Win95 32<->16 OLE coupling)
  * [ok]
+ *
+ * RETURNS
+ *  Thunked function result.
  */
 DWORD WINAPIV SSCall(
 	DWORD nr,	/* [in] number of argument bytes */
@@ -1129,6 +1135,8 @@ DEFINE_REGS_ENTRYPOINT( W32S_BackTo32, 0, 0 );
 /**********************************************************************
  *			AllocSLCallback		(KERNEL32.@)
  *
+ * Allocate a 16->32 callback.
+ *
  * NOTES
  * Win95 uses some structchains for callbacks. It allocates them
  * in blocks of 100 entries, size 32 bytes each, layout:
@@ -1182,6 +1190,9 @@ AllocSLCallback(
 /**********************************************************************
  * 		FreeSLCallback		(KERNEL32.@)
  * Frees the specified 16->32 callback
+ *
+ * RETURNS
+ *  Nothing.
  */
 void WINAPI
 FreeSLCallback(

dlls/kernel/time.c

@@ -592,7 +592,6 @@ int WINAPI GetCalendarInfoA(LCID lcid, CALID Calendar, CALTYPE CalType,
 /*********************************************************************
  *	GetCalendarInfoW				(KERNEL32.@)
  *
- * See GetCalendarInfoA.
  */
 int WINAPI GetCalendarInfoW(LCID Locale, CALID Calendar, CALTYPE CalType,
 			    LPWSTR lpCalData, int cchData, LPDWORD lpValue)
@@ -736,7 +735,7 @@ int WINAPI	SetCalendarInfoA(LCID Locale, CALID Calendar, CALTYPE CalType, LPCSTR
 /*********************************************************************
  *	SetCalendarInfoW				(KERNEL32.@)
  *
- * See SetCalendarInfoA.
+ *
  */
 int WINAPI	SetCalendarInfoW(LCID Locale, CALID Calendar, CALTYPE CalType, LPCWSTR lpCalData)
 {

dlls/kernel/virtual.c

@@ -78,6 +78,10 @@ LPVOID WINAPI VirtualAlloc(
  *             VirtualAllocEx   (KERNEL32.@)
  *
  * Seems to be just as VirtualAlloc, but with process handle.
+ *
+ * RETURNS
+ *	Base address of allocated region of pages
+ *	NULL: Failure
  */
 LPVOID WINAPI VirtualAllocEx(
               HANDLE hProcess, /* [in] Handle of process to do mem operation */
@@ -286,7 +290,7 @@ HANDLE WINAPI CreateFileMappingA(
 
 /***********************************************************************
  *             CreateFileMappingW   (KERNEL32.@)
- * See CreateFileMappingA
+ * See CreateFileMappingA.
  */
 HANDLE WINAPI CreateFileMappingW( HANDLE hFile, LPSECURITY_ATTRIBUTES sa,
                                   DWORD protect, DWORD size_high,
@@ -383,7 +387,7 @@ HANDLE WINAPI OpenFileMappingA(
 
 /***********************************************************************
  *             OpenFileMappingW   (KERNEL32.@)
- * See OpenFileMappingA
+ * See OpenFileMappingA.
  */
 HANDLE WINAPI OpenFileMappingW( DWORD access, BOOL inherit, LPCWSTR name)
 {
@@ -517,6 +521,8 @@ BOOL WINAPI FlushViewOfFile( LPCVOID base,  /* [in] Start address of byte range
 /***********************************************************************
  *             IsBadReadPtr   (KERNEL32.@)
  *
+ * Check for read access on a memory block.
+ *
  * RETURNS
  *	FALSE: Process has read access to entire block
  *      TRUE: Otherwise
@@ -557,6 +563,8 @@ BOOL WINAPI IsBadReadPtr(
 /***********************************************************************
  *             IsBadWritePtr   (KERNEL32.@)
  *
+ * Check for write access on a memory block.
+ *
  * RETURNS
  *	FALSE: Process has write access to entire block
  *      TRUE: Otherwise
@@ -595,6 +603,9 @@ BOOL WINAPI IsBadWritePtr(
 
 /***********************************************************************
  *             IsBadHugeReadPtr   (KERNEL32.@)
+ *
+ * Check for read access on a memory block.
+ *
  * RETURNS
  *	FALSE: Process has read access to entire block
  *      TRUE: Otherwise
@@ -609,6 +620,9 @@ BOOL WINAPI IsBadHugeReadPtr(
 
 /***********************************************************************
  *             IsBadHugeWritePtr   (KERNEL32.@)
+ *
+ * Check for write access on a memory block.
+ *
  * RETURNS
  *	FALSE: Process has write access to entire block
  *      TRUE: Otherwise
@@ -624,6 +638,8 @@ BOOL WINAPI IsBadHugeWritePtr(
 /***********************************************************************
  *             IsBadCodePtr   (KERNEL32.@)
  *
+ * Check for read access on a memory address.
+ *
  * RETURNS
  *	FALSE: Process has read access to specified memory
  *	TRUE: Otherwise
@@ -637,6 +653,8 @@ BOOL WINAPI IsBadCodePtr( FARPROC ptr ) /* [in] Address of function */
 /***********************************************************************
  *             IsBadStringPtrA   (KERNEL32.@)
  *
+ * Check for read access on a range of memory pointed to by a string pointer.
+ *
  * RETURNS
  *	FALSE: Read access to all bytes in string
  *	TRUE: Else
@@ -664,7 +682,7 @@ BOOL WINAPI IsBadStringPtrA(
 
 /***********************************************************************
  *             IsBadStringPtrW   (KERNEL32.@)
- * See IsBadStringPtrA
+ * See IsBadStringPtrA.
  */
 BOOL WINAPI IsBadStringPtrW( LPCWSTR str, UINT max )
 {

dlls/kernel/volume.c

@@ -1240,6 +1240,8 @@ UINT WINAPI GetDriveTypeW(LPCWSTR root) /* [in] String describing drive */
 
 /***********************************************************************
  *           GetDriveTypeA   (KERNEL32.@)
+ *
+ * See GetDriveTypeW.
  */
 UINT WINAPI GetDriveTypeA( LPCSTR root )
 {
@@ -1294,6 +1296,8 @@ BOOL WINAPI GetDiskFreeSpaceExW( LPCWSTR root, PULARGE_INTEGER avail,
 
 /***********************************************************************
  *           GetDiskFreeSpaceExA   (KERNEL32.@)
+ *
+ * See GetDiskFreeSpaceExW.
  */
 BOOL WINAPI GetDiskFreeSpaceExA( LPCSTR root, PULARGE_INTEGER avail,
                                  PULARGE_INTEGER total, PULARGE_INTEGER totalfree )