Patch by David Weizades

git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@21208 a95241bf-73f2-0310-859d-f6bbb57e9c96

docs/user/support/BlockCache.dox

@@ -2,8 +2,12 @@
  * Copyright 2007, Haiku, Inc. All Rights Reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
- *  Niels Sascha Reedijk <[email protected]>
+ *   Niels Sascha Reedijk <[email protected]>
+ *
+ * Proofreading:
+ *   David Weizades <[email protected]>
+ * 
  * Corresponds to:
  *   /trunk/headers/os/support/BlockCache.h  rev 19972
  *   /trunk/src/kits/support/BlockCache.cpp  rev 4568
@@ -34,37 +38,38 @@
 
   In some performance critical code there might come a time where you
   require a lot of little blocks of memory that you want to access and
-  dispose of continuously. Since allocating and freeing memory are an
+  dispose of continuously. Since allocating and freeing memory are 
-  'expensive' operation, it's better to have a pool of memory blocks at
+  'expensive' operations, it's better to have a pool of memory blocks at
   your disposal. Luckily, the Haiku API provides a class that will act
-  as the administrator of your memory pool, so you won't have to reinvent
+  as the administrator of your memory pool, so you will not have to reinvent
-  the wheel.
+  the wheel every time.
 
   The principle is easy. The constructor takes the number of blocks you
   want to create beforehand, the size of the blocks and the method of
   allocation. This can either be #B_OBJECT_CACHE or #B_MALLOC_CACHE.
-  The first uses C++ operators \c new[] and \c delete[], the second uses
+  The first one uses C++ operators \c new[] and \c delete[], the second one
-  \c malloc() and \c free(). Unless you have specific demands on performance
+  uses \c malloc() and \c free(). Unless you have specific demands on
-  or you want to take care of freeing the objects yourself, either use is fine. 
+  performance or you want to take care of freeing the objects yourself, either
+  way works fine.
 
   As soon as you have the memory pool, you can Get() blocks. If the
   pre-allocated memory blocks run out, BBlockCache will allocate
-  new ones, so you won't have to worry about availability. As soon as
+  new ones, so you will not have to worry about availability. As soon as
-  you're done, you can Save() the memory back into the pool, though
+  you are done you can Save() the memory back into the pool. BBlockCache will
-  BBlockCache will make sure that there won't be more blocks saved
+  make sure that there will not be more blocks saved than the initial number you
-  than the initial number you said when you created the object.
+  requested when you created the object, so be aware of that.
 
   As soon as you got a pointer from the Get() method, you own that
-  block of memory. This means that you have the liberty to dispose
+  block of memory, this means that you have the liberty to dispose
   of it yourself. It also means that when you delete your BBlockCache
-  instance, any blocks of memory that are checked out won't be destroyed.
+  instance, any blocks of memory that are checked out will not be destroyed.
   In case you might want to delete your objects yourself, make sure you 
-  use the proper way. If you created the object as #B_OBJECT_CACHE
+  free the memory the right way. If you created the object as #B_OBJECT_CACHE,
-  use \c delete[] to free your object. If you created the object
+  use \c delete[]  to free your object. If you created the object as
-  as #B_MALLOC_CACHE, use \c free(). Please note that it defeats
+  #B_MALLOC_CACHE, use \c free(). Please note that it defeats the purpose of
-  the purpose of this class if your are going to free all the objects yourself,
+  this class if your are going to free all the objects yourself since it
-  since it basically means that when the pool runs out, Get() will be allocating
+  basically means that when the pool runs out, Get() will be allocating the
-  the objects itself. 
+  objects by itself.
 
   \note BBlockCache is thread-safe.
 */
@@ -73,9 +78,9 @@
   \fn BBlockCache::BBlockCache(uint32 blockCount, size_t blockSize, uint32 allocationType)
   \brief Allocate a new memory pool. 
 
-  \param blockCount The number of free memory blocks you want to initially
+  \param blockCount The number of free memory blocks you want to allocate
-    allocate. This number is also used as a maximum number of free blocks that
+    initially. This number is also used as the maximum number of free blocks
-    will be kept.
+    that will be kept.
   \param blockSize The size of the blocks. 
   \param allocationType Either #B_OBJECT_CACHE for using \c new[] and
     \c delete[] or #B_MALLOC_CACHE for \c malloc() and \c free().
@@ -109,13 +114,13 @@
   \brief Save a block of memory to the memory pool.
 
   The block of memory will only be added to the pool if the \c blockSize is
-  equal to the size the object was created with, and if the maximum number
+  equal to the size the object was created with and if the maximum number
-  free blocks in the list won't be passed. Else the memory will be freeed. 
+  free blocks in the list will not be exceeded. If not the memory will be freed.
 
-  Note that it is perfectly valid to pass objects other than you got from
+  Note that it is perfectly valid to pass objects other than those you got from
-  Get(), but please note that the way it was created confirms with the way
+  Get(), but please note that the way it was created conforms to the way memory
-  memory is allocated and freed in this pool. Thus, only feed blocks that were
+  is allocated and freed in this pool. Therefor only feed blocks that were
-  created with \c new[] if the allocation type is #B_OBJECT_CACHE, likewise
+  created with \c new[] if the allocation type is #B_OBJECT_CACHE. Likewise
-  use only objects allocated with \c malloc() when the allocation type is
+  you should only use objects allocated with \c malloc() when the allocation
-  #B_MALLOC_CACHE.
+  type is #B_MALLOC_CACHE.
 */