diff --git a/dlls/shell32/brsfolder.c b/dlls/shell32/brsfolder.c
index 7aff4362a04..241f579932a 100644
--- a/dlls/shell32/brsfolder.c
+++ b/dlls/shell32/brsfolder.c
@@ -665,7 +665,7 @@ LPITEMIDLIST WINAPI SHBrowseForFolderA (LPBROWSEINFOA lpbi)
 /*************************************************************************
  * SHBrowseForFolderW [SHELL32.@]
  *
- * NOTES:
+ * NOTES
  *  crashes when passed a null pointer
  */
 LPITEMIDLIST WINAPI SHBrowseForFolderW (LPBROWSEINFOW lpbi)
diff --git a/dlls/shell32/pidl.c b/dlls/shell32/pidl.c
index 7468a3fdde6..02a9676127d 100644
--- a/dlls/shell32/pidl.c
+++ b/dlls/shell32/pidl.c
@@ -885,6 +885,9 @@ LPITEMIDLIST WINAPI ILAppend(LPITEMIDLIST pidl, LPCITEMIDLIST item, BOOL bEnd)
  * PARAMS
  *  pidl         [I]
  *
+ * RETURNS
+ *  Nothing
+ *
  * NOTES
  *  exported by ordinal
  */
@@ -903,6 +906,9 @@ void WINAPI ILFree(LPITEMIDLIST pidl)
  * PARAMS
  *  pidl         [I]
  *
+ * RETURNS
+ *  Nothing
+ *
  * NOTES
  *  exported by ordinal.
  */
@@ -941,6 +947,8 @@ LPITEMIDLIST WINAPI ILCreateFromPathA (LPCSTR path)
 
 /*************************************************************************
  * ILCreateFromPathW         [SHELL32.190]
+ *
+ * See ILCreateFromPathA.
  */
 LPITEMIDLIST WINAPI ILCreateFromPathW (LPCWSTR path)
 {
@@ -1238,6 +1246,8 @@ BOOL WINAPI SHGetPathFromIDListA(LPCITEMIDLIST pidl, LPSTR pszPath)
 
 /*************************************************************************
  * SHGetPathFromIDListW             [SHELL32.@]
+ *
+ * See SHGetPathFromIDListA.
  */
 BOOL WINAPI SHGetPathFromIDListW(LPCITEMIDLIST pidl, LPWSTR pszPath)
 {
diff --git a/dlls/shell32/shell.c b/dlls/shell32/shell.c
index 533756680cb..0a6ceb74602 100644
--- a/dlls/shell32/shell.c
+++ b/dlls/shell32/shell.c
@@ -335,12 +335,13 @@ SEGPTR WINAPI FindEnvironmentString16(LPSTR str)
  * from "DOS" environment. If it is not found the %KEYWORD% is left
  * intact. If the buffer is too small, str is not modified.
  *
- * str         [I] '\0' terminated string with %keyword%.
+ * PARAMS
+ *  str        [I] '\0' terminated string with %keyword%.
  *             [O] '\0' terminated string with %keyword% substituted.
- * length      [I] size of str.
+ *  length     [I] size of str.
  *
- * Return
- *     str length in the LOWORD and 1 in HIWORD if subst was successful.
+ * RETURNS
+ *  str length in the LOWORD and 1 in HIWORD if subst was successful.
  */
 DWORD WINAPI DoEnvironmentSubst16(LPSTR str,WORD length)
 {
diff --git a/dlls/shell32/shellole.c b/dlls/shell32/shellole.c
index 4447049dca2..9b92c26f12b 100644
--- a/dlls/shell32/shellole.c
+++ b/dlls/shell32/shellole.c
@@ -693,8 +693,8 @@ BOOL WINAPI DragQueryPoint(HDROP hDrop, POINT *p)
 }
 
 /*************************************************************************
- *  DragQueryFile 		[SHELL32.@]
  *  DragQueryFileA		[SHELL32.@]
+ *  DragQueryFile 		[SHELL32.@]
  */
 UINT WINAPI DragQueryFileA(
 	HDROP hDrop,
diff --git a/dlls/shell32/shellord.c b/dlls/shell32/shellord.c
index 56d3301bcc7..5c705568673 100644
--- a/dlls/shell32/shellord.c
+++ b/dlls/shell32/shellord.c
@@ -622,6 +622,8 @@ static INT SHADD_create_add_mru_data(HANDLE mruhandle, LPSTR doc_name, LPSTR new
 /*************************************************************************
  * SHAddToRecentDocs				[SHELL32.@]
  *
+ * Modify (add/clear) Shell's list of recently used documents.
+ *
  * PARAMETERS
  *   uFlags  [IN] SHARD_PATHA, SHARD_PATHW or SHARD_PIDL
  *   pv      [IN] string or pidl, NULL clears the list
@@ -629,7 +631,8 @@ static INT SHADD_create_add_mru_data(HANDLE mruhandle, LPSTR doc_name, LPSTR new
  * NOTES
  *     exported by name
  *
- * FIXME: convert to unicode
+ * FIXME
+ *  convert to unicode
  */
 void WINAPI SHAddToRecentDocs (UINT uFlags,LPCVOID pv)
 {
@@ -972,6 +975,12 @@ void WINAPI SHAddToRecentDocs (UINT uFlags,LPCVOID pv)
 /*************************************************************************
  * SHCreateShellFolderViewEx			[SHELL32.174]
  *
+ * Create a new instance of the default Shell folder view object.
+ *
+ * RETURNS
+ *  Success: S_OK
+ *  Failure: error value
+ *
  * NOTES
  *  see IShellFolder::CreateViewObject
  */
@@ -1336,10 +1345,11 @@ BOOL WINAPI SHWaitForFileToOpen(
 /************************************************************************
  *	@				[SHELL32.654]
  *
- * NOTES: first parameter seems to be a pointer (same as passed to WriteCabinetState)
- * second one could be a size (0x0c). The size is the same as the structure saved to
- * HCU\Software\Microsoft\Windows\CurrentVersion\Explorer\CabinetState
- * I'm (js) guessing: this one is just ReadCabinetState ;-)
+ * NOTES
+ *  first parameter seems to be a pointer (same as passed to WriteCabinetState)
+ *  second one could be a size (0x0c). The size is the same as the structure saved to
+ *  HCU\Software\Microsoft\Windows\CurrentVersion\Explorer\CabinetState
+ *  I'm (js) guessing: this one is just ReadCabinetState ;-)
  */
 HRESULT WINAPI shell32_654 (CABINETSTATE *cs, int length)
 {
@@ -1374,11 +1384,12 @@ HRESULT WINAPI SHValidateUNC (DWORD x, DWORD y, DWORD z)
  * from environment. If it is not found the %KEYWORD% is left
  * intact. If the buffer is too small, str is not modified.
  *
- * pszString   [I] '\0' terminated string with %keyword%.
+ * PARAMS
+ *  pszString  [I] '\0' terminated string with %keyword%.
  *             [O] '\0' terminated string with %keyword% substituted.
- * cchString   [I] size of str.
+ *  cchString  [I] size of str.
  *
- * Return
+ * RETURNS
  *     cchString length in the HIWORD;
  *     TRUE in LOWORD if subst was successful and FALSE in other case
  */
@@ -1405,6 +1416,7 @@ DWORD WINAPI DoEnvironmentSubstA(LPSTR pszString, UINT cchString)
 /************************************************************************
  *	DoEnvironmentSubstW			[SHELL32.@]
  *
+ * See DoEnvironmentSubstA.  
  */
 DWORD WINAPI DoEnvironmentSubstW(LPWSTR pszString, UINT cchString)
 {
@@ -1415,6 +1427,7 @@ DWORD WINAPI DoEnvironmentSubstW(LPWSTR pszString, UINT cchString)
 /************************************************************************
  *	DoEnvironmentSubst			[SHELL32.53]
  *
+ * See DoEnvironmentSubstA.  
  */
 DWORD WINAPI DoEnvironmentSubstAW(LPVOID x, UINT y)
 {
@@ -1580,6 +1593,9 @@ BOOL WINAPI SHFindFiles( LPCITEMIDLIST pidlFolder, LPCITEMIDLIST pidlSaveFile )
  *  uFlags      [I] Flags determining the icon attributes. See notes.
  *  iImageIndex [I] Index of the icon in the system image list.
  *
+ * RETURNS
+ *  Nothing
+ *
  * NOTES
  *  uFlags can be one or more of the following flags:
  *  GIL_NOTFILENAME - pszHashItem is not a file name.
@@ -1590,6 +1606,11 @@ void WINAPI SHUpdateImageW(LPCWSTR pszHashItem, int iIndex, UINT uFlags, int iIm
     FIXME("%s, %d, 0x%x, %d - stub\n", debugstr_w(pszHashItem), iIndex, uFlags, iImageIndex);
 }
 
+/*************************************************************************
+ *		SHUpdateImageA (SHELL32.191)
+ *
+ * See SHUpdateImageW.
+ */
 VOID WINAPI SHUpdateImageA(LPCSTR pszHashItem, INT iIndex, UINT uFlags, INT iImageIndex)
 {
     FIXME("%s, %d, 0x%x, %d - stub\n", debugstr_a(pszHashItem), iIndex, uFlags, iImageIndex);
diff --git a/dlls/shell32/shellpath.c b/dlls/shell32/shellpath.c
index 008ef2a72a2..ab1d3d7825b 100644
--- a/dlls/shell32/shellpath.c
+++ b/dlls/shell32/shellpath.c
@@ -1675,8 +1675,14 @@ end:
 /*************************************************************************
  * SHGetFolderPathW			[SHELL32.@]
  *
+ * Convert nFolder to path.  
+ *
+ * RETURNS
+ *  Success: S_OK
+ *  Failure: standard HRESULT error codes.
+ *
  * NOTES
- * Converts nFolder to path.  Most values can be overridden in either
+ * Most values can be overridden in either
  * HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders
  * or in the same location in HKLM.
  * The registry usage is explained by the following tech note:
@@ -1690,13 +1696,13 @@ end:
  * http://www.microsoft.com/windows2000/techinfo/reskit/en-us/default.asp?url=/windows2000/techinfo/reskit/en-us/regentry/36276.asp
  * the HKCU paths take precedence over the HKLM paths.
  *
- **********************************************************************/
+ */
 HRESULT WINAPI SHGetFolderPathW(
-	HWND hwndOwner,
-	int nFolder,
-	HANDLE hToken,
-	DWORD dwFlags,
-	LPWSTR pszPath)
+	HWND hwndOwner,    /* [I] owner window */
+	int nFolder,       /* [I] CSIDL identifing the folder */
+	HANDLE hToken,     /* [I] access token */
+	DWORD dwFlags,     /* [I] which path to return */
+	LPWSTR pszPath)    /* [O] converted path */
 {
     HRESULT    hr;
     WCHAR      szBuildPath[MAX_PATH], szTemp[MAX_PATH];
@@ -1802,6 +1808,8 @@ end:
 
 /*************************************************************************
  * SHGetFolderPathA			[SHELL32.@]
+ *
+ * See SHGetFolderPathW.
  */
 HRESULT WINAPI SHGetFolderPathA(
 	HWND hwndOwner,
@@ -2041,11 +2049,7 @@ BOOL WINAPI SHGetSpecialFolderPathAW (
 /*************************************************************************
  * SHGetFolderLocation [SHELL32.@]
  *
- * NOTES
  * Gets the folder locations from the registry and creates a pidl.
- * Creates missing reg keys and directories.
- * Mostly forwards to SHGetFolderPathW, but a few values of nFolder return
- * virtual folders that are handled here.
  *
  * PARAMS
  *   hwndOwner  [I]
@@ -2055,7 +2059,14 @@ BOOL WINAPI SHGetSpecialFolderPathAW (
  *   dwReserved [I] must be zero
  *   ppidl      [O] PIDL of a special folder
  *
+ * RETURNS
+ *  Success: S_OK
+ *  Failure: Standard OLE-defined error result, S_FALSE or E_INVALIDARG
+ *
  * NOTES
+ *  Creates missing reg keys and directories.
+ *  Mostly forwards to SHGetFolderPathW, but a few values of nFolder return
+ *  virtual folders that are handled here.
  */
 HRESULT WINAPI SHGetFolderLocation(
 	HWND hwndOwner,
diff --git a/dlls/shell32/shellstring.c b/dlls/shell32/shellstring.c
index 3581768d72d..a41b0b94636 100644
--- a/dlls/shell32/shellstring.c
+++ b/dlls/shell32/shellstring.c
@@ -260,7 +260,7 @@ static const WCHAR strEscapedChars[] = {' ','"',',',';','^',0};
 /*************************************************************************
  * CheckEscapesW             [SHELL32.@]
  *
- * see CheckEscapesA
+ * See CheckEscapesA.
  */
 DWORD WINAPI CheckEscapesW(
 	LPWSTR	string,
diff --git a/dlls/shell32/shlfileop.c b/dlls/shell32/shlfileop.c
index 0f9d9b2d45b..b6139b8696e 100644
--- a/dlls/shell32/shlfileop.c
+++ b/dlls/shell32/shlfileop.c
@@ -236,7 +236,7 @@ BOOL SHELL_DeleteFileW(LPCWSTR pszFile, BOOL bShowUI)
  * RETURNS
  *  TRUE if successful, FALSE otherwise
  *
- * NOTES:
+ * NOTES
  *  Verified on Win98 / IE 5 (SHELL32 4.72, March 1999 build) to be ANSI.
  *  This is Unicode on NT/2000
  */
@@ -290,7 +290,7 @@ BOOL WINAPI Win32CreateDirectoryAW(LPCVOID path, LPSECURITY_ATTRIBUTES sec)
  * RETURNS
  *  TRUE if successful, FALSE otherwise
  *
- * NOTES:
+ * NOTES
  *  Verified on Win98 / IE 5 (SHELL32 4.72, March 1999 build) to be ANSI.
  *  This is Unicode on NT/2000
  */
@@ -354,7 +354,7 @@ BOOL WINAPI Win32RemoveDirectoryAW(LPCVOID path)
  * RETURNS
  *  TRUE if successful, FALSE otherwise
  *
- * NOTES:
+ * NOTES
  *  Verified on Win98 / IE 5 (SHELL32 4.72, March 1999 build) to be ANSI.
  *  This is Unicode on NT/2000
  */
@@ -560,6 +560,8 @@ int WINAPI SHCreateDirectoryExA(HWND hWnd, LPCSTR path, LPSECURITY_ATTRIBUTES se
 
 /*************************************************************************
  * SHCreateDirectoryExW      [SHELL32.@]
+ *
+ * See SHCreateDirectoryExA.
  */
 int WINAPI SHCreateDirectoryExW(HWND hWnd, LPCWSTR path, LPSECURITY_ATTRIBUTES sec)
 {
@@ -792,6 +794,10 @@ DWORD SHNameTranslate(LPWSTR* wString, LPCWSTR* pWToFrom, BOOL more)
  * PARAMS
  *  lpFileOp   [I/O] pointer to a structure containing all the necessary information
  *
+ * RETURNS
+ *  Success: zero
+ *  Failure: nonzero
+ *
  * NOTES
  *  exported by name
  */
@@ -998,7 +1004,7 @@ static DWORD shfileops_get_parent_attr(LPWSTR pFile,LPWSTR pTemp)
 /*************************************************************************
  * SHFileOperationW          [SHELL32.@]
  *
- * See SHFileOperationA
+ * See SHFileOperationA.
  */
 int WINAPI SHFileOperationW(LPSHFILEOPSTRUCTW lpFileOp)
 {
@@ -1394,6 +1400,8 @@ shfileop_end:
  * PARAMS
  *  hNameMapping [I] handle to the name mappings used during renaming of files
  *
+ * RETURNS
+ *  Nothing
  */
 void WINAPI SHFreeNameMappings(HANDLE hNameMapping)
 {
diff --git a/dlls/shell32/shlmenu.c b/dlls/shell32/shlmenu.c
index 99810dc45a8..1a451008f92 100644
--- a/dlls/shell32/shlmenu.c
+++ b/dlls/shell32/shlmenu.c
@@ -818,6 +818,8 @@ void WINAPI FileMenu_AbortInitMenu (void)
 /*************************************************************************
  * SHFind_InitMenuPopup				[SHELL32.149]
  *
+ * Get the IContextMenu instance for the submenu of options displayed
+ * for the Search entry in the Classic style Start menu.
  *
  * PARAMETERS
  *  hMenu		[in] handle of menu previously created
diff --git a/dlls/shell32/systray.c b/dlls/shell32/systray.c
index 1fdef45abd7..8dd241f8190 100644
--- a/dlls/shell32/systray.c
+++ b/dlls/shell32/systray.c
@@ -380,8 +380,8 @@ BOOL WINAPI Shell_NotifyIconW(DWORD dwMessage, PNOTIFYICONDATAW pnid )
 }
 
 /*************************************************************************
- * Shell_NotifyIcon			[SHELL32.296]
  * Shell_NotifyIconA			[SHELL32.297]
+ * Shell_NotifyIcon			[SHELL32.296]
  */
 BOOL WINAPI Shell_NotifyIconA (DWORD dwMessage, PNOTIFYICONDATAA pnid )
 {