* Add documentation for BAutolock, BBlockCache and BList

* Finish up documentation for BString
* Trying to work a bit more on the structure.

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

docs/user/book.dox

@@ -15,3 +15,10 @@
 \defgroup libbe (libbe.so)
 \defgroup libroot (libroot.so)
 */
+
+// Subgroups
+
+/*!
+\defgroup support_globals Global functions in the support kit
+\ingroup support
+*/

docs/user/midi/midi1intro.dox

@@ -35,14 +35,14 @@ To make MIDI data stream through your application, you create a "network" of
 BMidi-derived objects that send and receive MIDI messages.
 
 The old Midi Kit is slowly fading into obscurity. You may want to use the
-\ref midi2 "new kit" instead. Also note that the OpenBeOS implementation
+\ref midi2 "new kit" instead. Also note that the Haiku implementation
 of the kit sometimes behaves differently than the one from BeOS R5 or what
-the BeBook says, but usually for the better ;-)
+the BeBook says, but usually for the better.
 
 Especially the synth classes are not completely functional, but enough to
 play back General MIDI tunes. They should be backwards compatible with the
 majority of BeOS MIDI applications. Not all methods of BSynth, BMidiSynth,
 and BMidiSynthFile are implemented because some of them are rather obscure. 
-BSamples is a complete no-op; in other words, with the OpenBeOS Midi Kit 
+BSamples is a complete no-op; in other words, with the Haiku Midi Kit 
 you cannot push waveform data into the output stream of the softsynth.
 */

docs/user/support/Autolock.dox

@@ -0,0 +1,103 @@
+/*!
+\file Autolock.h
+\brief Implements a handy locking utility.
+*/
+
+/*!
+\class BAutolock
+\ingroup support
+\ingroup libbe
+\brief Convenient utility to make parts of your code thread-safe easily.
+
+The autolocker uses a BLooper or a BLocker in order to protect a part
+of your code. This class is usually used in combination with a BLocker
+that protects a certain part of your code and data that are being
+accessed by multiple threads. While BAutolock does not add any features
+to locking, it provides a mechanism to easily lock and protect a part of your
+code. 
+
+Normally, when you need to protect data, you would have to make sure that
+all your locks are paired with unlocks. Below is a simple example, but you
+can imagine that there are more complex situations where you might spend a
+lot of time debugging a hang because you didn't pair all the Lock()s with an
+Unlock(). See the example:
+
+\code
+status_t
+Receiver::HandleCall(Call *call)
+{
+  ... work on call data ...
+
+  fDataLocker->Lock()
+
+  ... perform changes ...
+
+  if (!success)
+  {
+    fDataLocker->Unlock();
+    return B_ERROR;
+  }
+    
+  fDataLocker->Unlock()
+  return B_OK;
+}
+\endcode
+
+With the BAutolock this example can be rewritten as follows:
+\code
+status_t
+Receiver::HandleCall(Call *call)
+{
+  ... work on call data ...
+  
+  BAutolock autolock(fDataLocker);
+  
+  ... perform changes ...
+  
+  if (!success)
+    return B_ERROR;
+  
+  return B_OK;
+}
+\endcode
+
+Since the object is created on stack, it is destroyed as soon as we leave
+the function. Because the destruction of the object causes it to unlock
+the BLocker or BLooper, you don't have to manually make sure that every
+exit from the function is properly written.
+*/
+
+/*!
+\fn BAutolock::BAutolock(BLooper *looper)
+\brief Create an object and lock the BLooper
+*/
+
+/*!
+\fn BAutolock::BAutolock(BLocker *locker)
+\brief Create an object and lock the BLocker
+*/
+
+/*!
+\fn BAutolock::BAutolock(BLocker &locker)
+\brief Create an object and lock the BLocker
+*/
+
+/*!
+\fn BAutolock::~BAutolock()
+\brief Destroy the object and unlock the associated BLocker or BLooper
+*/
+
+/*!
+\fn bool BAutolock::IsLocked(void)
+\brief Verify whether the  associated BLocker or BLooper are actually locked.
+
+Basically you may assume that when the object is created, you are
+almost always sure the actual locking succeeds. It might fail if the
+BLocker or BLooper are destroyed though. The semaphore will be
+released and the Lock() call will fail. 
+
+If you might get this behaviour, you can use this method to help you
+protect yourself from it.
+\retval true The lock was acquired.
+\retval false Failed to acquire the lock.
+*/

docs/user/support/BlockCache.dox

@@ -0,0 +1,108 @@
+/*!
+\file BlockCache.h
+\brief Implements a mechanism to store and retrieve memory blocks
+*/
+
+/*!
+\var B_OBJECT_CACHE
+\brief Used in the constructor of BBlockCache. Determines that objects will
+  be created using \c new[] and \c delete[].
+*/
+
+/*!
+\var B_MALLOC_CACHE
+\brief Used in the constructor of BBlockCache. Determines that objects will
+  be created using \c malloc() and \c free().
+*/
+
+/*!
+\class BBlockCache
+\ingroup support
+\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
+require a lot of little blocks of memory that you want to access and
+dispose of continuously. Since allocating and freeing memory are an
+'expensive' operation, 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
+the wheel.
+
+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
+\c malloc() and \c free(). Unless you have specific demands on performance
+or you want to take care of freeing the objects yourself, either use is 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
+you're done, you can Save() the memory back into the pool, though
+BBlockCache will make sure that there won't be more blocks saved
+than the initial number you said when you created the object.
+
+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
+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.
+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
+use \c delete[] to free your object. If you created the object
+as #B_MALLOC_CACHE, use \c free(). Please note that it defeats
+the purpose of this class if your are going to free all the objects yourself,
+since it basically means that when the pool runs out, Get() will be allocating
+the objects itself. 
+
+\note BBlockCache is thread-safe.
+*/
+
+/*!
+\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 allocate.
+ This number is also used as a maximum number of free blocks 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().
+*/
+
+/*!
+\fn BBlockCache::~BBlockCache()
+\brief Destroy the empty blocks in the free list.
+
+Note that the blocks you checked out with Get() and not checked back in with
+Save() will not be freed, since ownership belongs to you. Make sure you clean up
+after yourself.
+*/
+
+/*!
+\fn void *BBlockCache::Get(size_t blockSize)
+\brief Get a block from the pool of free blocks.
+
+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. Only 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
+failed.
+*/
+
+/*!
+\fn void BBlockCache::Save(void *pointer, size_t blockSize)
+\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 free blocks
+in the list won't be passed. Else the memory will be freeed. 
+
+Note that it is perfectly valid to pass objects other than you got from Get(), but
+please note that the way it was created confirms with the way memory is allocated
+and freed in this pool. Thus, only feed blocks that were 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 #B_MALLOC_CACHE.
+*/

docs/user/support/List.dox

@@ -0,0 +1,352 @@
+// Documentation by: 
+//   Niels Sascha Reedijk <[email protected]>
+// Corresponds to:
+//   /trunk/headers/os/support/List.h  rev 19972
+//   /trunk/src/kits/support/List.cpp  rev 18649
+
+/*!
+\file List.h
+\brief Implements a list implementation.
+*/
+
+/*!
+\class BList
+\ingroup support
+\ingroup libbe
+\brief An ordered container that is designed to hold generic \c void * objects.
+
+This class is designed to be used for a variety of tasks. Unlike similar
+implementations in other libraries, this class is not based on templates,
+and as such is inherently not typed. So it will be the job of the coder to
+make sure proper data will be entered, since the compiler cannot check this.
+
+BList contains a list of items that will grow and shrink depending on
+how much items are in it. So you will not have to do any of the
+memory management. Furthermore, it's ordered. Those properties make it
+useful in a whole range of situations, for example in the interface kit in 
+the BListView class.
+
+A note on ownership of the objects might come in handy. BList at no time
+assumes ownership of the objects, so removing items from the list will
+only remove those items from the list, it will not delete the item. In the
+same spirit you should also make sure that before you might delete an
+object that's in a list, you will remove it from the list first. 
+
+\warning This class is not thread-safe.
+
+The class implements methods to add and remove items, reorder items,
+retrieve items, querying for items and some advanced methods which let
+you perform a certain tasks to all the items of the list.
+*/
+
+/*!
+\fn BList::BList(int32 count = 20)
+\brief Create a new list with a number of empty slots.
+
+The memory management of this class allocates new memory per block. The
+\c count parameter can be tweaked to determine the size of those blocks.
+In general, if you know your list is only going to contain a fixed maximum
+number of items, pass that value. If you expect your list to have very few items,
+it's probably safe to choose a low number. This is as to prevent the list from
+taking up unneccesary memory. If you expect the list to contain a large
+number of items, choose a higher value, since every time the memory is full, all
+the items have to be copied into a new piece of allocated memory which is
+an expensive operation.
+
+If you are unsure, you don't have to break your head over this. As long as you
+don't use a lot of lists or as long as the list isn't used in one of the
+performance critical parts of the code, you are safe to go with the default
+value.
+
+\param count The size of the blocks of memory allocated.
+*/
+
+/*!
+\fn BList::BList(const BList& anotherList)
+\brief Copy constructor, copies a complete list into this one.
+*/
+
+/*!
+\fn BList::~BList()
+\brief Destroy the list.
+
+Please note that as BList does not assume ownership of the objects,
+only the list will be freed, not the objects that are held in it.
+*/
+
+/*!
+\fn BList& BList::operator=(const BList &list)
+\brief Copy another list into this object.
+*/
+
+/*!
+\name Adding and removing items
+*/
+
+//! @{
+
+/*!
+\fn bool BList::AddItem(void *item, int32 index)
+\brief Add an item at a certain position.
+
+\param item The item to add.
+\param index The place in the list.
+\retval true The item was added.
+\retval false Item was not added. Either the index was  negative or invalid,
+  or resizing the list failed.
+\sa AddItem(void *item)
+*/
+
+/*!
+\fn bool BList::AddItem(void *item)
+\brief Append an item to the list.
+
+\param item The item to add.
+\retval true The item was appended.
+\retval true The item was added.
+\retval false Item was not appended, since resizing the list failed.
+\sa AddItem(void *item, int32 index)
+*/
+
+/*!
+\fn bool BList::AddList(const BList *list, int32 index)
+\brief Add items from another list to this list at a certain position.
+
+Note that the \c list parameter is \c const, so the original list will not be altered.
+
+\param list The list to be added.
+\param index The position in the current list where the new item(s) should be put.
+\retval true The list was added. 
+\retval false Failed to insert the list, due to the fact that resizing our list failed. 
+\sa AddList(const BList *list)
+*/
+
+/*!
+\fn bool BList::AddList(const BList *list)
+\brief Append a list to this list.
+
+Note that the \c list parameter is \c const, so the original list will not be altered.
+
+\param list The list to be appended.
+\retval true The list was appended. 
+\retval false Failed to append the list, due to the fact that resizing our list failed. 
+\sa AddList(const BList *list, int32 index)
+*/
+
+/*!
+\fn bool BList::RemoveItem(void *item)
+\brief Remove an item from the list.
+
+\param item The item that should be removed.
+\retval true The item was found and removed.
+\retval false The item was not in this list and thus not removed.
+\sa RemoveItem(int32 index)
+*/
+
+/*!
+\fn void * BList::RemoveItem(int32 index)
+\brief Remove the item at \c index from the list.
+
+\param index The item that should be removed.
+\return The pointer to the item that was removed, or \c NULL in case the
+  index was invalid.
+\sa RemoveItem(void *item)
+*/
+
+/*!
+\fn bool BList::RemoveItems(int32 index, int32 count)
+\brief Remove a number of items starting at a certain position.
+
+If the count parameter is larger than the number of items in the list,
+all the items from the offset to the end will be removed.
+
+\param index The offset in the list where removal should start.
+\param count The number of items to remove.
+\retval true Removal succeeded.
+\retval false Failed to remove the items because the index was invalid.
+*/
+
+/*!
+\fn bool BList::ReplaceItem(int32 index, void *newItem)
+\brief Replace a item with another one.
+
+\param index The offset in the list where to put the item.
+\param newItem The new item to put in the list.
+\retval true Item replaced.
+\retval false The index was invalid.
+*/
+
+/*!
+\fn void BList::MakeEmpty()
+\brief Clear all the items from the list.
+
+Please note that this does not free the items. 
+*/
+
+//! @}
+
+/*!
+\name Reordering items
+*/
+
+//! @{
+
+/*!
+\fn void BList::SortItems(int (*compareFunc)(const void *, const void *))
+\brief Sort the items with the use of a supplied comparison function.
+
+The function should take two \c const pointers as arguments and should return an
+integer.
+
+For an example, see the Compare(const BString *, const BString *) function. 
+*/
+
+/*!
+\fn bool BList::SwapItems(int32 indexA, int32 indexB)
+\brief Swap two items.
+
+\param indexA The first item.
+\param indexB The second item.
+\retval true Swap succeeded.
+\retval false Swap failed because one of the indexes were invalid.
+*/
+
+/*! 
+\fn bool BList::MoveItem(int32 fromIndex, int32 toIndex)
+\brief Move an item to a new place
+
+This moves a list item from posititon a to position b, moving the appropriate 
+block of list elements to make up for the move.  For example, in the array:
+\verbatim
+A B C D E F G H I J
+\endverbatim
+Moveing 1(B)->6(G) would result in this:
+\verbatim
+A C D E F G B H I J
+\endverbatim
+
+\param fromIndex The original location.
+\param toIndex The new location.
+\retval true Move succeeded.
+\retval false Move failed since the indexes were invalid.
+*/
+
+//! @}
+
+/*!
+\name Retrieving items
+*/
+
+//! @{
+
+/*!
+\fn void *BList::ItemAt(int32 index) const
+\brief Get an item.
+
+\param index The item to retrieve.
+\return A pointer to the item in that position, or \c NULL if the index is out of bounds.
+\sa ItemAtFast(int32 index) const
+*/
+
+/*!
+\fn void *BList::FirstItem() const
+\brief Get the first item.
+\return A pointer to the first item, or \c NULL if the list is empty.
+*/
+
+/*!
+\fn void *BList::ItemAtFast(int32 index) const
+\brief Get an item.
+
+This method does not performs any boundary checks when it retrieves an item.
+Use this method in a performance critical area of your program where you are
+sure you won't get an invalid item.
+
+\return A pointer to the item.
+*/
+
+/*!
+\fn void *BList::LastItem() const
+\brief Get the last item.
+\return A pointer to the last item, or \c NULL if the list is empty.
+*/
+
+/*!
+\fn void *BList::Items() const
+\brief Return the internal list of objects.
+
+This method will return a pointer to the internal pointer list. This means you should be careful
+what you are doing, since you are directly working with the internals of the class.
+
+It is definately not a good idea to make any changes to the list, since it will mess up
+the internal consistency. 
+
+\warning If there is anything you want for which you need the list of objects, please
+  realize that that probably means that what you want to do is a bad idea to begin with.
+  Avoid this method. The list of objects doesn't belong to you. Check if DoForEach() can
+  help you.
+\return The internal list of pointers.
+*/
+
+//! @}
+
+/*!
+\name Querying for items
+*/
+
+//! @{
+
+/*!
+\fn bool BList::HasItem(void *item) const
+\brief Check if an item is in the list.
+*/
+
+/*!
+\fn int32 BList::IndexOf(void *item) const
+\brief Get the index of an item.
+
+\return The index of the item, or -1 when the item is not in the list.
+*/
+
+/*!
+\fn int32 BList::CountItems() const
+\brief Get the number of items in the list.
+*/
+
+/*!
+\fn bool BList::IsEmpty() const
+\brief Check if there are items in the list.
+*/
+
+//! @}
+
+/*!
+\name Iterating over the list
+*/
+
+//! @{
+
+/*!
+\fn void BList::DoForEach(bool (*func)(void* item))
+\brief Perform an action on every item in the list.
+
+If one of the actions on the items fails, meaning that the \c func function
+returned \c false, then the processing of the list will be stopped.
+
+\param func A function that takes a \c void * argument and returns a boolean.
+*/
+
+/*!
+\fn void BList::DoForEach(bool (*func)(void* item, void* arg2), void *arg2)
+\brief Perform an action on every item in the list with an argument.
+
+If one of the actions on the items fails, meaning that the \c func function
+returned \c false, then the processing of the list will be stopped.
+
+\param func A function with the first \c void * argument being the item,
+  and the second \c void * being the argument that you supply. It should
+  return a boolean value on whether it succeeded or not.
+\param arg2 An argument to supply to \c func.
+*/
+
+//! @}

docs/user/support/parsedate.dox

@@ -2,7 +2,7 @@
 \file parsedate.h
 \ingroup support
 \ingroup libroot
-\brief date parsing functions
+\brief Date parsing functions
 
 This is a set a functions for parsing date strings in various formats.
 It's mostly tailored for parsing user given data, although originally,

docs/user/support/stopwatch.dox

@@ -1,7 +1,5 @@
 /*!
 \file StopWatch.h
-\ingroup support
-\ingroup libbe
 \brief Provides the BStopWatch class.
 */
 

docs/user/support/support_intro.dox

@@ -9,7 +9,7 @@ use in your applications.
 	<li>Threading utility classes:</li>
 	<ul>
 		<li>BLocker</li>
-		<li>BAutoLock</li>
+		<li>BAutolock</li>
 		<li>Thread Local Storage</li>
 	</ul>
 	<li>Archiving and IO:</li>

docs/user/support/typeconstants.dox

@@ -58,7 +58,15 @@
 \brief Represents a \c char type used for integer storage
 */
 
+/*!
+\var B_ATOM_TYPE
+\brief Reference to a BAtomic class that was going to be in BeOS R6. Unused in Haiku. 
+*/
 
+/*!
+\var B_ATOMREF_TYPE
+\brief Reference to a BAtomic class that was going to be in BeOS R6. Unused in Haiku. 
+*/
 
 // Todo: the rest of the types