From e633b45300f0ced255069348d99c4a15d06aae51 Mon Sep 17 00:00:00 2001
From: Vitaly Lipatov <lav@etersoft.ru>
Date: Thu, 7 Jul 2005 17:21:44 +0000
Subject: [PATCH] Added some documentation.

---
 dlls/ole32/memlockbytes.c | 37 +++++++++++++++++++++++++++++++++----
 dlls/ole32/storage32.c    | 17 +++++++++++++++++
 2 files changed, 50 insertions(+), 4 deletions(-)

diff --git a/dlls/ole32/memlockbytes.c b/dlls/ole32/memlockbytes.c
index 2cc93b4240e..2b5503475d7 100644
--- a/dlls/ole32/memlockbytes.c
+++ b/dlls/ole32/memlockbytes.c
@@ -155,6 +155,24 @@ static const ILockBytesVtbl HGLOBALLockBytesImpl_Vtbl =
 
 /******************************************************************************
  *           CreateILockBytesOnHGlobal     [OLE32.@]
+ *
+ * Create a byte array object which is intended to be the compound file foundation.
+ * This object supports a COM implementation of the ILockBytes interface.
+ *
+ * PARAMS
+ *  hGlobal           [ I] Global memory handle
+ *  fDeleteOnRelease  [ I] Whether the handle should be freed when the object is released. 
+ *  ppLkbyt           [ O] Address of ILockBytes pointer that receives
+ *                         the interface pointer to the new byte array object.
+ *
+ * RETURNS
+ *  Success: S_OK
+ *
+ * NOTES
+ *  The supplied ILockBytes pointer can be used by the StgCreateDocfileOnILockBytes
+ *  function to build a compound file on top of this byte array object.
+ *  The ILockBytes interface instance calls the GlobalReAlloc function to grow
+ *  the memory block as required.
  */
 HRESULT WINAPI CreateILockBytesOnHGlobal(HGLOBAL      hGlobal,
                                          BOOL         fDeleteOnRelease,
@@ -176,6 +194,17 @@ HRESULT WINAPI CreateILockBytesOnHGlobal(HGLOBAL      hGlobal,
 
 /******************************************************************************
  *           GetHGlobalFromILockBytes     [OLE32.@]
+ *
+ * Retrieve a global memory handle to a byte array object created
+ * using the CreateILockBytesOnHGlobal function.
+ *
+ * PARAMS
+ *  plkbyt   [ I]  Pointer to the ILockBytes interface on byte array object
+ *  phglobal [ O]  Address to store a global memory handle
+ * RETURNS
+ *  S_OK          if *phglobal has a correct value
+ *  E_INVALIDARG  if any parameters are invalid
+ *  
  */
 HRESULT WINAPI GetHGlobalFromILockBytes(ILockBytes* plkbyt, HGLOBAL* phglobal)
 {
@@ -224,10 +253,10 @@ HRESULT WINAPI GetHGlobalFromILockBytes(ILockBytes* plkbyt, HGLOBAL* phglobal)
 /******************************************************************************
  * This is the constructor for the HGLOBALLockBytesImpl class.
  *
- * Params:
- *    hGlobal          - Handle that will support the stream. can be NULL.
- *    fDeleteOnRelease - Flag set to TRUE if the HGLOBAL will be released
- *                       when the IStream object is destroyed.
+ * PARAMS
+ *    hGlobal          [ I] Handle that will support the stream. can be NULL.
+ *    fDeleteOnRelease [ I] Flag set to TRUE if the HGLOBAL will be released
+ *                          when the IStream object is destroyed.
  */
 HGLOBALLockBytesImpl* HGLOBALLockBytesImpl_Construct(HGLOBAL hGlobal,
                                                      BOOL    fDeleteOnRelease)
diff --git a/dlls/ole32/storage32.c b/dlls/ole32/storage32.c
index d6e1fedcfbd..a234ce360ba 100644
--- a/dlls/ole32/storage32.c
+++ b/dlls/ole32/storage32.c
@@ -23,6 +23,14 @@
  * You should have received a copy of the GNU Lesser General Public
  * License along with this library; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ *
+ * NOTES
+ *  The compound file implementation of IStorage used for create
+ *  and manage substorages and streams within a storage object
+ *  residing in a compound file object.
+ *
+ * MSDN
+ *  http://msdn.microsoft.com/library/default.asp?url=/library/en-us/stg/stg/istorage_compound_file_implementation.asp
  */
 
 #include <assert.h>
@@ -1583,6 +1591,13 @@ HRESULT WINAPI StorageImpl_MoveElementTo(
 
 /*************************************************************************
  * Commit (IStorage)
+ *
+ * Ensures that any changes made to a storage object open in transacted mode
+ * are reflected in the parent storage
+ *
+ * NOTES
+ *  Wine doesn't implement transacted mode, which seems to be a basic
+ *  optimization, so we can ignore this stub for now.
  */
 HRESULT WINAPI StorageImpl_Commit(
   IStorage*   iface,
@@ -1594,6 +1609,8 @@ HRESULT WINAPI StorageImpl_Commit(
 
 /*************************************************************************
  * Revert (IStorage)
+ *
+ * Discard all changes that have been made since the last commit operation
  */
 HRESULT WINAPI StorageImpl_Revert(
   IStorage* iface)