Patch by Thom Holwerda:

"Phase III .diff for BlockCache.dox.

Not much to change here, some really minor things only. The thing
that makes the .diff large is the fact that many lines were more like
70char than 80char."

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

docs/user/support/BlockCache.dox

@@ -7,6 +7,7 @@
  *
  * Proofreading:
  *   David Weizades <[email protected]>
+ *   Thom Holwerda <[email protected]>
  * 
  * Corresponds to:
  *   /trunk/headers/os/support/BlockCache.h  rev 19972
@@ -15,7 +16,7 @@
  
  /*!
   \file BlockCache.h
-  \brief Implements a mechanism to store and retrieve memory blocks
+  \brief Implements a mechanism to store and retrieve memory blocks.
 */
 
 /*!
@@ -36,52 +37,50 @@
   \ingroup libbe
   \brief A class that creates and maintains a pool of memory blocks.
 
-  In some performance critical code there might come a time where you
+  In some performance critical code there might come a time where you require a
-  require a lot of little blocks of memory that you want to access and
+  lot of little blocks of memory that you want to access and dispose of
-  dispose of continuously. Since allocating and freeing memory are 
+  continuously. Since allocating and freeing memory are 'expensive' operations,
-  'expensive' operations, it's better to have a pool of memory blocks at
+  it is better to have a pool of memory blocks at your disposal. Luckily, the
-  your disposal. Luckily, the Haiku API provides a class that will act
+  Haiku API provides a class that will act as the administrator of your memory
-  as the administrator of your memory pool, so you will not have to reinvent
+  pool, so you will not have to reinvent the wheel every time.
-  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
+  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 one uses C++ operators \c new[] and \c delete[], the second one
+  The first one uses C++ operators \c new[] and \c delete[], while the second
-  uses \c malloc() and \c free(). Unless you have specific demands on
+  one uses \c malloc() and \c free(). Unless you have specific demands on
   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
+  pre-allocated memory blocks run out, BBlockCache will allocate new ones, so
-  new ones, so you will not have to worry about availability. As soon as
+  you will not have to worry about availability. As soon as you are done you can
-  you are done you can Save() the memory back into the pool. BBlockCache will
+  Save() the memory back into the pool. BBlockCache will make sure that no more
-  make sure that there will not be more blocks saved than the initial number you
+  blocks will be saved than the initial number you requested when you created
-  requested when you created the object, so be aware of that.
+  the object, so be aware of that.
 
-  As soon as you got a pointer from the Get() method, you own that
+  As soon as you got a pointer from the Get() method, you own that block of
-  block of memory, this means that you have the liberty to dispose
+  memory; this means that you have the liberty to dispose of it yourself. It
-  of it yourself. It also means that when you delete your BBlockCache
+  also means that when you delete your BBlockCache instance, any blocks of
-  instance, any blocks of memory that are checked out will not be destroyed.
+  memory that are checked out will not be destroyed. In case you might want to
-  In case you might want to delete your objects yourself, make sure you 
+  delete your objects yourself, make sure you free the memory the right way. If
-  free the memory the right way. If you created the object as #B_OBJECT_CACHE,
+  you created the object as #B_OBJECT_CACHE, use \c delete[] to free your
-  use \c delete[]  to free your object. If you created the object as
+  object. If you created the object as #B_MALLOC_CACHE, use \c free(). Please
-  #B_MALLOC_CACHE, use \c free(). Please note that it defeats the purpose of
+  note that it defeats the purpose of this class if your are going to free all
-  this class if your are going to free all the objects yourself since it
+  the objects yourself since it basically means that when the pool runs out,
-  basically means that when the pool runs out, Get() will be allocating the
+  Get() will be allocating the objects by itself.
-  objects by itself.
 
   \note BBlockCache is thread-safe.
 */
 
 /*!
   \fn BBlockCache::BBlockCache(uint32 blockCount, size_t blockSize, uint32 allocationType)
-  \brief Allocate a new memory pool. 
+  \brief Allocate a new memory pool.
 
   \param blockCount The number of free memory blocks you want to allocate
     initially. This number is also used as the maximum number of free blocks
     that will be kept.
-  \param blockSize The size of the blocks. 
+  \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().
 */
@@ -101,8 +100,8 @@
 
   If the pool runs out of free blocks, a new one will be allocated. Please note
   that if the size given in the \c blockSize parameter is different from the
-  size given in the constructor, that a new block of memory will be created.
+  size given in the constructor, a new block of memory will be created. Only
-  Only sizes that match the blocks in the memory pool will come from the pool.
+  sizes that match the blocks in the memory pool will come from the pool.
 
   \param blockSize The required size of the memory block.
   \return Returns a pointer to a memory block, or \c NULL if locking the object
@@ -114,13 +113,14 @@
   \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 of
-  free blocks in the list will not be exceeded. If not the memory will be freed.
+  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 those you got from
   Get(), but please note that the way it was created conforms to the way memory
-  is allocated and freed in this pool. Therefor only feed blocks that were
+  is allocated and freed in this pool. Therefore, 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,
   you should only use objects allocated with \c malloc() when the allocation
   type is #B_MALLOC_CACHE.
 */