shell32: Document the shell32 "mini-COM" functions.

dlls/shell32/shellole.c

@@ -78,12 +78,6 @@ static const struct {
 	{NULL,NULL}
 };
 
-/*************************************************************************
- * SHCoCreateInstance [SHELL32.102]
- *
- * NOTES
- *     exported by ordinal
- */
 
 /* FIXME: this should be SHLWAPI.24 since we can't yet import by ordinal */
 
@@ -103,8 +97,22 @@ DWORD WINAPI __SHGUIDToStringW (REFGUID guid, LPWSTR str)
 
 }
 
-/************************************************************************/
-
+/*************************************************************************
+ * SHCoCreateInstance [SHELL32.102]
+ *
+ * Equivalent to CoCreateInstance. Under Windows 9x this function could sometimes
+ * use the shell32 built-in "mini-COM" without the need to load ole32.dll - see
+ * SHLoadOLE for details.
+ *
+ * Under wine if a "LoadWithoutCOM" value is present or the object resides in
+ * shell32.dll the function will load the object manually without the help of ole32
+ *
+ * NOTES
+ *     exported by ordinal
+ *
+ * SEE ALSO
+ *     CoCreateInstace, SHLoadOLE
+ */
 HRESULT WINAPI SHCoCreateInstance(
 	LPCWSTR aclsid,
 	const CLSID *clsid,
@@ -253,8 +261,16 @@ HRESULT WINAPI DllGetClassObject(REFCLSID rclsid, REFIID iid, LPVOID *ppv)
 /*************************************************************************
  * SHCLSIDFromString				[SHELL32.147]
  *
+ * Under Windows 9x this was an ANSI version of CLSIDFromString. It also allowed
+ * to avoid dependency on ole32.dll (see SHLoadOLE for details).
+ *
+ * Under Windows NT/2000/XP this is equivalent to CLSIDFromString
+ *
  * NOTES
  *     exported by ordinal
+ *
+ * SEE ALSO
+ *     CLSIDFromString, SHLoadOLE
  */
 DWORD WINAPI SHCLSIDFromStringA (LPCSTR clsid, CLSID *id)
 {
@@ -405,7 +421,9 @@ static const IMallocVtbl VT_Shell_IMalloc32 =
 /*************************************************************************
  *			 SHGetMalloc			[SHELL32.@]
  *
- * Return the shell IMalloc interface.
+ * Equivalent to CoGetMalloc(MEMCTX_TASK, ...). Under Windows 9x this function
+ * could use the shell32 built-in "mini-COM" without the need to load ole32.dll -
+ * see SHLoadOLE for details. 
  *
  * PARAMS
  *  lpmal [O] Destination for IMalloc interface.
@@ -415,8 +433,12 @@ static const IMallocVtbl VT_Shell_IMalloc32 =
  *  Failure. An HRESULT error code.
  *
  * NOTES
- *  This function will use CoGetMalloc() if OLE32.DLL is already loaded.
- *  If not it uses an internal implementation as a fallback.
+ *  wine contains an implementation of an allocator to use when ole32.dll is not
+ *  loaded but it is never used as ole32 is imported by shlwapi which is imported by
+ *  shell32
+ *
+ * SEE ALSO
+ *  CoGetMalloc, SHLoadOLE
  */
 HRESULT WINAPI SHGetMalloc(LPMALLOC *lpmal)
 {
@@ -446,8 +468,15 @@ HRESULT WINAPI SHGetMalloc(LPMALLOC *lpmal)
 /*************************************************************************
  * SHAlloc					[SHELL32.196]
  *
+ * Equivalent to CoTaskMemAlloc. Under Windows 9x this function could use
+ * the shell32 built-in "mini-COM" without the need to load ole32.dll -
+ * see SHLoadOLE for details. 
+ *
  * NOTES
  *     exported by ordinal
+ *
+ * SEE ALSO
+ *     CoTaskMemAlloc, SHLoadOLE
  */
 LPVOID WINAPI SHAlloc(DWORD len)
 {
@@ -464,8 +493,15 @@ LPVOID WINAPI SHAlloc(DWORD len)
 /*************************************************************************
  * SHFree					[SHELL32.195]
  *
+ * Equivalent to CoTaskMemFree. Under Windows 9x this function could use
+ * the shell32 built-in "mini-COM" without the need to load ole32.dll -
+ * see SHLoadOLE for details. 
+ *
  * NOTES
  *     exported by ordinal
+ *
+ * SEE ALSO
+ *     CoTaskMemFree, SHLoadOLE
  */
 void WINAPI SHFree(LPVOID pv)
 {

dlls/shell32/shellord.c

@@ -438,8 +438,15 @@ int WINAPIV ShellMessageBoxA(
 /*************************************************************************
  * SHRegisterDragDrop				[SHELL32.86]
  *
+ * Probably equivalent to RegisterDragDrop but under Windows 9x it could use the
+ * shell32 built-in "mini-COM" without the need to load ole32.dll - see SHLoadOLE
+ * for details
+ *
  * NOTES
  *     exported by ordinal
+ *
+ * SEE ALSO
+ *     RegisterDragDrop, SHLoadOLE
  */
 HRESULT WINAPI SHRegisterDragDrop(
 	HWND hWnd,
@@ -452,8 +459,15 @@ HRESULT WINAPI SHRegisterDragDrop(
 /*************************************************************************
  * SHRevokeDragDrop				[SHELL32.87]
  *
+ * Probably equivalent to RevokeDragDrop but under Windows 9x it could use the
+ * shell32 built-in "mini-COM" without the need to load ole32.dll - see SHLoadOLE
+ * for details
+ *
  * NOTES
  *     exported by ordinal
+ *
+ * SEE ALSO
+ *     RevokeDragDrop, SHLoadOLE
  */
 HRESULT WINAPI SHRevokeDragDrop(HWND hWnd)
 {
@@ -464,8 +478,15 @@ HRESULT WINAPI SHRevokeDragDrop(HWND hWnd)
 /*************************************************************************
  * SHDoDragDrop					[SHELL32.88]
  *
+ * Probably equivalent to DoDragDrop but under Windows 9x it could use the
+ * shell32 built-in "mini-COM" without the need to load ole32.dll - see SHLoadOLE
+ * for details
+ *
  * NOTES
  *     exported by ordinal
+ *
+ * SEE ALSO
+ *     DoDragDrop, SHLoadOLE
  */
 HRESULT WINAPI SHDoDragDrop(
 	HWND hWnd,
@@ -1054,12 +1075,20 @@ HRESULT WINAPI SHGetInstanceExplorer (LPUNKNOWN * lpUnknown)
 /*************************************************************************
  * SHFreeUnusedLibraries			[SHELL32.123]
  *
+ * Probably equivalent to CoFreeUnusedLibraries but under Windows 9x it could use
+ * the shell32 built-in "mini-COM" without the need to load ole32.dll - see SHLoadOLE
+ * for details
+ *
  * NOTES
- *  exported by name
+ *     exported by ordinal
+ *
+ * SEE ALSO
+ *     CoFreeUnusedLibraries, SHLoadOLE
  */
 void WINAPI SHFreeUnusedLibraries (void)
 {
 	FIXME("stub\n");
+	CoFreeUnusedLibraries();
 }
 /*************************************************************************
  * DAD_AutoScroll				[SHELL32.129]
@@ -1284,9 +1313,25 @@ HRESULT WINAPI SetAppStartingCursor(HWND u, DWORD v)
 {	FIXME("hwnd=%p 0x%04lx stub\n",u,v );
 	return 0;
 }
+
 /*************************************************************************
  * SHLoadOLE					[SHELL32.151]
  *
+ * To reduce the memory usage of Windows 95 it's shell32 contained an
+ * internal implementation of a part of COM (see e.g. SHGetMalloc, SHCoCreateInstance,
+ * SHRegisterDragDrop etc.) that allowed to use in-process STA objects without
+ * the need to load OLE32.DLL. If OLE32.DLL was already loaded, the SH* function
+ * would just call the Co* functions.
+ *
+ * The SHLoadOLE was called when OLE32.DLL was being loaded to transfer all the
+ * informations from the shell32 "mini-COM" to ole32.dll.
+ *
+ * See http://blogs.msdn.com/oldnewthing/archive/2004/07/05/173226.aspx for a
+ * detailed description.
+ *
+ * Under wine ole32.dll is always loaded as it is imported by shlwapi.dll which is
+ * imported by shell32 and no "mini-COM" is used (except for the "LoadWithoutCOM"
+ * hack in SHCoCreateInstance)
  */
 HRESULT WINAPI SHLoadOLE(LPARAM lParam)
 {	FIXME("0x%04lx stub\n",lParam);