Update according to the latest guideline changes. These files already

passed phase 3, so they wouldn't be updated during the regular process. 
I guess the other files will get that update.


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

docs/user/support/Archivable.dox

@@ -3,22 +3,24 @@
  * Distributed under the terms of the MIT License.
  *
  * Author:
- *   Niels Sascha Reedijk <[email protected]>
+ *   Niels Sascha Reedijk, [email protected]
  *
  * Proofreader:
- *   David Weizades <[email protected]>
+ *   David Weizades, [email protected]
- *   Thom Holwerda <[email protected]>
+ *   Thom Holwerda, [email protected]
  *
  * Corresponds to:
  *   /trunk/headers/os/support/Archivable.h rev 19972
  *   /trunk/src/kits/support/Archivable.cpp rev 19095
  */
 
+
 /*!
 	\file Archivable.h
 	\brief Provides the BArchivable interface.
 */
 
+
 /*!
 	\class BArchivable
 	\ingroup support
@@ -32,58 +34,65 @@
 
 	BArchivable differs from BFlattenable in that BFlattenable is designed to
 	store objects into flat streams of data, the main objective being storage to
-  disk. The objective of this interface, however, is to store objects that will
+	disk. The objective of this interface, however, is to store objects that
-  be restored to other objects. To illustrate this point, BArchivable messages
+	will be restored to other objects. To illustrate this point, BArchivable
-  know how to restore themselves whereas BFlattenables have a datatype which
+	messages know how to restore themselves whereas BFlattenables have a
-  you need to map to classes manually.
+	datatype which you need to map to classes manually.
 
 	Archiving is done with the Archive() method. If your class supports it, the
 	caller can request it to store into a deep archive, meaning that all child
 	objects in it will be stored. Extracting the archive works with the
 	Instantiate() method, which is static. Since the interface is designed to
-  extract objects without the caller knowing what kind of object it actually is,
+	extract objects without the caller knowing what kind of object it actually
-  the global function #instantiate_object() instantiates a message without you
+	is, the global function #instantiate_object() instantiates a message without
-  manually having to determine the class the message is from. This adds
+	you manually having to determine the class the message is from. This adds
-  considerable flexibility and allows BArchivable to be used in combination with
+	considerable flexibility and allows BArchivable to be used in combination
-  other add-ons.
+	with other add-ons.
 
 	To provide this interface in your classes you should publicly inherit this
 	class. You should implement Archive() and Instantiate(), and provide one
 	constructor that takes one BMessage argument.
 */
 
+
 /*!
 	\fn BArchivable::BArchivable(BMessage* from)
 	\brief Constructor. Does nothing.
 	
-  If you inherit this interface you should provide at least one constructor that
+	If you inherit this interface you should provide at least one constructor
-  takes one BMessage argument.
+	that takes one BMessage argument.
 */
 
+
 /*!
 	\fn BArchivable::BArchivable()
 	\brief Constructor. Does nothing.
 */
 
+
 /*!
 	\fn BArchivable::~BArchivable()
 	\brief Destructor. Does nothing.
 */
 
+
 /*!
-  \fn virtual	status_t BArchivable::Archive(BMessage* into, bool deep = true) const
+	\fn virtual status_t BArchivable::Archive(BMessage* into,
+		 bool deep = true) const
 	\brief Archive the object into a BMessage.
 	
 	You should call this method from your derived implementation as it adds the
 	data needed to instantiate your object to the message.
 	
 	\param into The message you store your object in.
-  \param deep If \c true, all children of this object should be stored as well.
+	\param deep If \c true, all children of this object should be stored as
-    Only pay attention to this parameter if you actually have child objects.
+		well. Only pay attention to this parameter if you actually have child
+		objects.
 	\retval B_OK The archiving succeeded.
 	\retval "error codes" The archiving did not succeed.
 */
 
+
 /*!
 	\fn static BArchivable* BArchivable::Instantiate(BMessage* archive)
 	\brief Static member to restore objects from messages.
@@ -96,11 +105,12 @@
 	\retval You should return a pointer to your object, or \c NULL if you 
 		fail.
 	\warning The default implementation will always return \c NULL. Even though
-    it is possible to store plain BArchive objects, it is impossible to restore
+		it is possible to store plain BArchive objects, it is impossible to
-    them. 
+		restore them. 
 	\see instantiate_object(BMessage *from)
 */
 
+
 /*!
 	\fn virtual status_t BArchivable::Perform(perform_code d, void* arg)
 	\brief Internal method.
@@ -108,18 +118,21 @@
 		API issues. Currently nothing of interest is implemented.
 */
 
+
 ///// Global methods /////
 /*!
 	\addtogroup support_globals
 	@{
 */
 
+
 /*!
 	\typedef typedef BArchivable* (*instantiation_func)(BMessage*)
 	\brief Internal definition of a function that can instantiate objects that
 		have been created with the BArchivable API.
 */
 
+
 /*!
 	\fn BArchivable* instantiate_object(BMessage *from, image_id *id)
 	\brief Instantiate an archived object with the object being defined in a
@@ -134,6 +147,7 @@
 		at the kernel API for further information.
 */
 
+
 /*!
 	\fn BArchivable* instantiate_object(BMessage *from)
 	\brief Instantiate an archived object.
@@ -144,33 +158,39 @@
 	
 	\param from The archived object.
 	\return The object returns a pointer to the instantiated object, or \c NULL
-    if the instantiation failed. The global \c errno variable will contain the
+		if the instantiation failed. The global \c errno variable will contain
-    reason why it failed.
+		the reason why it failed.
 	\see instantiate_object(BMessage *from, image_id *id)
 */
 
+
 /*!
 	\fn bool validate_instantiation(BMessage* from, const char* className)
 	\brief Internal function that checks if the \a className is the same as the
 		one stored in the \a from message.
 */
 
+
 /*!
-  \fn instantiation_func find_instantiation_func(const char* className,	const char* signature)
+	\fn instantiation_func find_instantiation_func(const char* className,
+		const char* signature)
 	\brief Internal function that searches for the instantiation func with a
 		specific signature. Use instantiate_object() instead.
 */
 
+
 /*!
 	\fn instantiation_func find_instantiation_func(const char* className)
 	\brief Internal function that searches for the instantiation func of a
 		specific class. Use instantiate_object() instead.
 */
 
+
 /*!
 	\fn instantiation_func find_instantiation_func(BMessage* archive)
 	\brief Internal function that searches for the instantiation func that
 		works on the specified \a archive. Use instantiate_object() instead.
 */
 
+
 //! @}

docs/user/support/BlockCache.dox

@@ -3,46 +3,50 @@
  * Distributed under the terms of the MIT License.
  *
  * Authors:
- *   Niels Sascha Reedijk <[email protected]>
+ *   Niels Sascha Reedijk, [email protected]
  *
  * Proofreading:
- *   David Weizades <[email protected]>
+ *   David Weizades, [email protected]
- *   Thom Holwerda <[email protected]>
+ *   Thom Holwerda, [email protected]
  * 
  * Corresponds to:
  *   /trunk/headers/os/support/BlockCache.h  rev 19972
  *   /trunk/src/kits/support/BlockCache.cpp  rev 4568
  */
 
+
  /*!
 	\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
+	In some performance critical code there might come a time where you require
-  lot of little blocks of memory that you want to access and dispose of
+	a lot of little blocks of memory that you want to access and dispose of
-  continuously. Since allocating and freeing memory are 'expensive' operations,
+	continuously. Since allocating and freeing memory are 'expensive'
-  it is better to have a pool of memory blocks at your disposal. Luckily, the
+	operations, it is better to have a pool of memory blocks at your disposal.
-  Haiku API provides a class that will act as the administrator of your memory
+	Luckily, the Haiku API provides a class that will act as the administrator
-  pool, so you will not have to reinvent the wheel every time.
+	of your memory pool, so you will not have to reinvent 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
@@ -54,17 +58,17 @@
 	
 	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 will not have to worry about availability. As soon as you are done you can
+	you will not have to worry about availability. As soon as you are done you
-  Save() the memory back into the pool. BBlockCache will make sure that no more
+	can Save() the memory back into the pool. BBlockCache will make sure that no
-  blocks will be saved than the initial number you requested when you created
+	more blocks will be saved than the initial number you requested when you
-  the object, so be aware of that.
+	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 of it yourself. It
 	also means that when you delete your BBlockCache 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 free the memory the right way. If
+	delete your objects yourself, make sure you free the memory the right way.
-  you created the object as #B_OBJECT_CACHE, use \c delete[] to free your
+	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,
@@ -73,8 +77,10 @@
 	\note BBlockCache is thread-safe.
 */
 
+
 /*!
-  \fn BBlockCache::BBlockCache(uint32 blockCount, size_t blockSize, uint32 allocationType)
+	\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 allocate
@@ -85,29 +91,32 @@
 		\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
+	Save() will not be freed, since ownership belongs to you. Make sure you
-  up after yourself.
+	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
+	If the pool runs out of free blocks, a new one will be allocated. Please
-  that if the size given in the \c blockSize parameter is different from the
+	note that if the size given in the \c blockSize parameter is different from
-  size given in the constructor, a new block of memory will be created. Only
+	the size given in the constructor, a new block of memory will be created.
-  sizes that match the blocks in the memory pool will come from the pool.
+	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
+	\return Returns a pointer to a memory block, or \c NULL if locking the
-  failed.
+		object failed.
 */
 
+
 /*!
 	\fn void BBlockCache::Save(void *pointer, size_t blockSize)
 	\brief Save a block of memory to the memory pool.
@@ -117,10 +126,10 @@
 	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
+	Note that it is perfectly valid to pass objects other than those you got
-  Get(), but please note that the way it was created conforms to the way memory
+	from Get(), but please note that the way it was created conforms to the way
-  is allocated and freed in this pool. Therefore, only feed blocks that were
+	memory is allocated and freed in this pool. Therefore, only feed blocks that
-  created with \c new[] if the allocation type is #B_OBJECT_CACHE. Likewise,
+	were created with \c new[] if the allocation type is #B_OBJECT_CACHE.
-  you should only use objects allocated with \c malloc() when the allocation
+	Likewise, you should only use objects allocated with \c malloc() when the
-  type is #B_MALLOC_CACHE.
+	allocation type is #B_MALLOC_CACHE.
 */

docs/user/support/List.dox

@@ -3,23 +3,25 @@
  * Distributed under the terms of the MIT License.
  *
  * Authors:
- *   Niels Sascha Reedijk <[email protected]>
+ *   Niels Sascha Reedijk, [email protected]
  * 
  * Proofreading:
- *   David Weizades <[email protected]>
+ *   David Weizades, [email protected]
- *   Thom Holwerda <[email protected]>
+ *   Thom Holwerda, [email protected]
- *   John Drinkwater <[email protected]>
+ *   John Drinkwater, [email protected]
  *
  * Corresponds to:
  *   /trunk/headers/os/support/List.h  rev 19972
  *   /trunk/src/kits/support/List.cpp  rev 18649
  */
 
+
 /*!
 	\file List.h
 	\brief Defines the BList class.
 */
 
+
 /*!
 	\class BList
 	\ingroup support
@@ -34,36 +36,38 @@
 	itself.
 	
 	BList contains a list of items that will grow and shrink depending on how
-  many items are in it. So you will not have to do any of the memory management
+	many items are in it. So you will not have to do any of the memory
-  nor any ordering. These properties makes it useful in a whole range of
+	management nor any ordering. These properties makes it useful in a whole
-  situations such as the interface kit within the BListView class.
+	range of situations such as the interface kit within the BListView class.
 	
 	A note on the ownership of the objects might come in handy. BList never
 	assumes ownership of the objects. As such, removing items from the list will
 	only remove the entries from the list; it will not delete the items
-  themselves. Similarly, you should also make sure that before you might delete
+	themselves. Similarly, you should also make sure that before you might
-  an object that is in a list, you will have to remove it from the list first.
+	delete an object that is in a list, you will have to remove it from the list
+	first.
 	
 	\warning This class is not thread-safe.
 	
 	The class implements methods to add, remove, reorder, retrieve, and query
-  items as well as some advanced methods which let you perform a task on all the
+	items as well as some advanced methods which let you perform a task on all
-  items in the list.
+	the items in 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 these blocks.
-  In general, if you know your list is only going to contain a certain number of
+	In general, if you know your list is only going to contain a certain number
-  items at most, you can pass that value. If you expect your list to have very
+	of items at most, you can pass that value. If you expect your list to have
-  few items, it is safe to choose a low number. This is to prevent the list from
+	very few items, it is safe to choose a low number. This is to prevent the
-  taking up unneeded memory. If you expect the list to contain a large number
+	list from taking up unneeded memory. If you expect the list to contain a
-  of items, choose a higher value. Every time the memory is full, all the items
+	large number of items, choose a higher value. Every time the memory is full,
-  have to be copied into a new piece of allocated memory, which is an expensive
+	all the items have to be copied into a new piece of allocated memory, which
-  operation.
+	is an expensive operation.
 	
 	If you are unsure, you do not have to worry too much. Just make sure you do
 	not use a lot of lists, and as long as the list is not used in one of the
@@ -73,11 +77,13 @@
 	\param count The size of the blocks allocated in memory.
 */
 
+
 /*!
 	\fn BList::BList(const BList& anotherList)
 	\brief Copy constructor. Copy a complete list into this one.
 */
 
+
 /*!
 	\fn BList::~BList()
 	\brief Destroy the list.
@@ -86,17 +92,21 @@
 	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.
@@ -109,6 +119,7 @@
 	\see AddItem(void *item)
 */
 
+
 /*!
 	\fn bool BList::AddItem(void *item)
 	\brief Append an item to the list.
@@ -119,22 +130,24 @@
 	\see 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 \a list parameter is \c const, so the original list will not be
+	Note that the \a list parameter is \c const, so the original list will not
-  altered.
+	be altered.
 	
 	\param list The list to be added.
-  \param index The position in the current list where the new item(s) should be
+	\param index The position in the current list where the new item(s) should
-    put.
+		be put.
 	\retval true The list was added. 
 	\retval false Failed to insert the list, due to the fact that resizing our
 		list failed. 
 	\see AddList(const BList *list)
 */
 
+
 /*!
 	\fn bool BList::AddList(const BList *list)
 	\brief Append a list to this list.
@@ -144,11 +157,12 @@
 	
 	\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 of our
+	\retval false Failed to append the list, due to the fact that resizing of
-    list failed.
+		our list failed.
 	\see AddList(const BList *list, int32 index)
 */
 
+
 /*!
 	\fn bool BList::RemoveItem(void *item)
 	\brief Remove an item from the list.
@@ -159,6 +173,7 @@
 	\see RemoveItem(int32 index)
 */
 
+
 /*!
 	\fn void * BList::RemoveItem(int32 index)
 	\brief Remove the item at \a index from the list.
@@ -169,6 +184,7 @@
 	\see RemoveItem(void *item)
 */
 
+
 /*!
 	\fn bool BList::RemoveItems(int32 index, int32 count)
 	\brief Remove a number of items starting at a certain position.
@@ -182,6 +198,7 @@
 	\retval false Failed to remove the items because the index was invalid.
 */
 
+
 /*!
 	\fn bool BList::ReplaceItem(int32 index, void *newItem)
 	\brief Replace an item with another one.
@@ -192,6 +209,7 @@
 	\retval false The index was invalid.
 */
 
+
 /*!
 	\fn void BList::MakeEmpty()
 	\brief Clear all the items from the list.
@@ -199,24 +217,29 @@
 	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
+	The function should take two \c const pointers as arguments and should
-  an integer.
+	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.
@@ -227,6 +250,7 @@
 	\retval false Swap failed because one of the indexes was invalid.
 */
 
+
 /*!
 	\fn bool BList::MoveItem(int32 fromIndex, int32 toIndex)
 	\brief Move an item to a new place
@@ -248,14 +272,18 @@ A C D E F G B H I J
 	\retval false Move failed due to the indexes being invalid.
 */
 
+
 //! @}
 
+
 /*!
 	\name Retrieving Items
 */
 
+
 //! @{
 
+
 /*!
 	\fn void *BList::ItemAt(int32 index) const
 	\brief Get an item.
@@ -266,6 +294,7 @@ A C D E F G B H I J
 	\see ItemAtFast(int32 index) const
 */
 
+
 /*!
 	\fn void *BList::FirstItem() const
 	\brief Get the first item.
@@ -274,6 +303,7 @@ A C D E F G B H I J
 	\see LastItem() const
 */
 
+
 /*!
 	\fn void *BList::ItemAtFast(int32 index) const
 	\brief Get an item.
@@ -285,6 +315,7 @@ A C D E F G B H I J
 	\return A pointer to the item.
 */
 
+
 /*!
 	\fn void *BList::LastItem() const
 	\brief Get the last item.
@@ -292,38 +323,44 @@ A C D E F G B H I J
 	\see FirstItem() const
 */
 
+
 /*!
 	\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
-  that you should be careful what you are doing, since you are working with the
+	that you should be careful what you are doing, since you are working with
-  internals of the class directly.
+	the internals of the class directly.
 	
 	It is not a good idea to make any changes to the list, since that 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
+		objects, please realize that that probably means that what you want to
-    a bad idea to begin with and that you should avoid this method. The list of
+		do is a bad idea to begin with and that you should avoid this method.
-    objects does not belong to you. See also DoForEach() for an alternate
+		The list of objects does not belong to you. See also DoForEach() for an
-    method.
+		alternate method.
 	\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.
@@ -331,24 +368,30 @@ A C D E F G B H I J
 	\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.
@@ -356,10 +399,12 @@ A C D E F G B H I J
 	If one of the actions on the items fails it means that the \a func function
 	returned \c false and the processing of the list will be stopped.
 	
-  \param func A function that takes a \c void * argument and returns a boolean.
+	\param func A function that takes a \c void * argument and returns a
+		boolean.
 	\see DoForEach(bool (*func)(void* item, void* arg2), void *arg2)
 */
 
+
 /*!
 	\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.
@@ -374,4 +419,5 @@ A C D E F G B H I J
 	\see DoForEach(bool (*func)(void* item))
 */
 
+
 //! @}