shell32: improve c2man documentation
Markus Amsler
markus.amsler at oribi.org
Wed Nov 9 18:30:54 CST 2005
This patch improves the c2man Documented-Total count of shell32 from
29(10%) to 48(16%) and of shell from 1(4%) to 2(8%).
Changelog:
Markus Amsler <markus.amsler at oribi.org>
Improve c2man Documented-Total count. Changes:
- add missing description
- add missing returns section
- complete missing A/W pairs
- reformate comments, to match c2man requirements
-------------- next part --------------
Index: dlls/shell32/brsfolder.c
===================================================================
RCS file: /home/wine/wine/dlls/shell32/brsfolder.c,v
retrieving revision 1.66
diff -u -r1.66 brsfolder.c
--- dlls/shell32/brsfolder.c 9 Nov 2005 10:30:28 -0000 1.66
+++ dlls/shell32/brsfolder.c 10 Nov 2005 00:28:37 -0000
@@ -665,7 +665,7 @@
/*************************************************************************
* SHBrowseForFolderW [SHELL32.@]
*
- * NOTES:
+ * NOTES
* crashes when passed a null pointer
*/
LPITEMIDLIST WINAPI SHBrowseForFolderW (LPBROWSEINFOW lpbi)
Index: dlls/shell32/pidl.c
===================================================================
RCS file: /home/wine/wine/dlls/shell32/pidl.c,v
retrieving revision 1.136
diff -u -r1.136 pidl.c
--- dlls/shell32/pidl.c 7 Sep 2005 09:22:49 -0000 1.136
+++ dlls/shell32/pidl.c 10 Nov 2005 00:28:38 -0000
@@ -885,6 +885,9 @@
* PARAMS
* pidl [I]
*
+ * RETURNS
+ * Nothing
+ *
* NOTES
* exported by ordinal
*/
@@ -903,6 +906,9 @@
* PARAMS
* pidl [I]
*
+ * RETURNS
+ * Nothing
+ *
* NOTES
* exported by ordinal.
*/
@@ -941,6 +947,8 @@
/*************************************************************************
* ILCreateFromPathW [SHELL32.190]
+ *
+ * See ILCreateFromPathA.
*/
LPITEMIDLIST WINAPI ILCreateFromPathW (LPCWSTR path)
{
@@ -1238,6 +1246,8 @@
/*************************************************************************
* SHGetPathFromIDListW [SHELL32.@]
+ *
+ * See SHGetPathFromIDListA.
*/
BOOL WINAPI SHGetPathFromIDListW(LPCITEMIDLIST pidl, LPWSTR pszPath)
{
Index: dlls/shell32/shell.c
===================================================================
RCS file: /home/wine/wine/dlls/shell32/shell.c,v
retrieving revision 1.67
diff -u -r1.67 shell.c
--- dlls/shell32/shell.c 18 Oct 2005 14:11:17 -0000 1.67
+++ dlls/shell32/shell.c 10 Nov 2005 00:28:38 -0000
@@ -335,12 +335,13 @@
* 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)
{
Index: dlls/shell32/shellole.c
===================================================================
RCS file: /home/wine/wine/dlls/shell32/shellole.c,v
retrieving revision 1.86
diff -u -r1.86 shellole.c
--- dlls/shell32/shellole.c 26 Aug 2005 10:05:34 -0000 1.86
+++ dlls/shell32/shellole.c 10 Nov 2005 00:28:38 -0000
@@ -693,8 +693,8 @@
}
/*************************************************************************
- * DragQueryFile [SHELL32.@]
* DragQueryFileA [SHELL32.@]
+ * DragQueryFile [SHELL32.@]
*/
UINT WINAPI DragQueryFileA(
HDROP hDrop,
Index: dlls/shell32/shellord.c
===================================================================
RCS file: /home/wine/wine/dlls/shell32/shellord.c,v
retrieving revision 1.136
diff -u -r1.136 shellord.c
--- dlls/shell32/shellord.c 27 Oct 2005 10:22:38 -0000 1.136
+++ dlls/shell32/shellord.c 10 Nov 2005 00:28:38 -0000
@@ -622,6 +622,8 @@
/*************************************************************************
* 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 @@
* NOTES
* exported by name
*
- * FIXME: convert to unicode
+ * FIXME
+ * convert to unicode
*/
void WINAPI SHAddToRecentDocs (UINT uFlags,LPCVOID pv)
{
@@ -972,6 +975,12 @@
/*************************************************************************
* 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 @@
/************************************************************************
* @ [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 @@
* 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 @@
/************************************************************************
* DoEnvironmentSubstW [SHELL32.@]
*
+ * See DoEnvironmentSubstA.
*/
DWORD WINAPI DoEnvironmentSubstW(LPWSTR pszString, UINT cchString)
{
@@ -1415,6 +1427,7 @@
/************************************************************************
* DoEnvironmentSubst [SHELL32.53]
*
+ * See DoEnvironmentSubstA.
*/
DWORD WINAPI DoEnvironmentSubstAW(LPVOID x, UINT y)
{
@@ -1580,6 +1593,9 @@
* 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 @@
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);
Index: dlls/shell32/shellpath.c
===================================================================
RCS file: /home/wine/wine/dlls/shell32/shellpath.c,v
retrieving revision 1.106
diff -u -r1.106 shellpath.c
--- dlls/shell32/shellpath.c 10 Oct 2005 10:29:53 -0000 1.106
+++ dlls/shell32/shellpath.c 10 Nov 2005 00:28:39 -0000
@@ -1675,8 +1675,14 @@
/*************************************************************************
* 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 @@
* 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 @@
/*************************************************************************
* SHGetFolderPathA [SHELL32.@]
+ *
+ * See SHGetFolderPathW.
*/
HRESULT WINAPI SHGetFolderPathA(
HWND hwndOwner,
@@ -2041,11 +2049,7 @@
/*************************************************************************
* 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 @@
* 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,
Index: dlls/shell32/shellstring.c
===================================================================
RCS file: /home/wine/wine/dlls/shell32/shellstring.c,v
retrieving revision 1.29
diff -u -r1.29 shellstring.c
--- dlls/shell32/shellstring.c 10 Feb 2004 02:18:50 -0000 1.29
+++ dlls/shell32/shellstring.c 10 Nov 2005 00:28:39 -0000
@@ -260,7 +260,7 @@
/*************************************************************************
* CheckEscapesW [SHELL32.@]
*
- * see CheckEscapesA
+ * See CheckEscapesA.
*/
DWORD WINAPI CheckEscapesW(
LPWSTR string,
Index: dlls/shell32/shlfileop.c
===================================================================
RCS file: /home/wine/wine/dlls/shell32/shlfileop.c,v
retrieving revision 1.55
diff -u -r1.55 shlfileop.c
--- dlls/shell32/shlfileop.c 6 May 2005 15:44:32 -0000 1.55
+++ dlls/shell32/shlfileop.c 10 Nov 2005 00:28:39 -0000
@@ -236,7 +236,7 @@
* 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 @@
* 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 @@
* 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 @@
/*************************************************************************
* SHCreateDirectoryExW [SHELL32.@]
+ *
+ * See SHCreateDirectoryExA.
*/
int WINAPI SHCreateDirectoryExW(HWND hWnd, LPCWSTR path, LPSECURITY_ATTRIBUTES sec)
{
@@ -792,6 +794,10 @@
* 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 @@
/*************************************************************************
* SHFileOperationW [SHELL32.@]
*
- * See SHFileOperationA
+ * See SHFileOperationA.
*/
int WINAPI SHFileOperationW(LPSHFILEOPSTRUCTW lpFileOp)
{
@@ -1394,6 +1400,8 @@
* PARAMS
* hNameMapping [I] handle to the name mappings used during renaming of files
*
+ * RETURNS
+ * Nothing
*/
void WINAPI SHFreeNameMappings(HANDLE hNameMapping)
{
Index: dlls/shell32/shlmenu.c
===================================================================
RCS file: /home/wine/wine/dlls/shell32/shlmenu.c,v
retrieving revision 1.41
diff -u -r1.41 shlmenu.c
--- dlls/shell32/shlmenu.c 2 Sep 2005 11:32:17 -0000 1.41
+++ dlls/shell32/shlmenu.c 10 Nov 2005 00:28:39 -0000
@@ -818,6 +818,8 @@
/*************************************************************************
* 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
Index: dlls/shell32/systray.c
===================================================================
RCS file: /home/wine/wine/dlls/shell32/systray.c,v
retrieving revision 1.32
diff -u -r1.32 systray.c
--- dlls/shell32/systray.c 8 Nov 2005 19:57:27 -0000 1.32
+++ dlls/shell32/systray.c 10 Nov 2005 00:28:40 -0000
@@ -380,8 +380,8 @@
}
/*************************************************************************
- * Shell_NotifyIcon [SHELL32.296]
* Shell_NotifyIconA [SHELL32.297]
+ * Shell_NotifyIcon [SHELL32.296]
*/
BOOL WINAPI Shell_NotifyIconA (DWORD dwMessage, PNOTIFYICONDATAA pnid )
{
More information about the wine-patches
mailing list