Merge branch 'master' into sam460ex

docs/user/Doxyfile

@@ -639,6 +639,7 @@ INPUT                  = . \
                          media \
                          midi \
                          midi2 \
+                         posix \
                          storage \
                          support \
                          translation \
@@ -738,10 +739,10 @@ EXAMPLE_RECURSIVE      = NO
 # the \image command).
 
 IMAGE_PATH             = . \
-                         interface \
+                         interface/images \
                          keyboard \
-                         midi2 \
+                         midi2/images \
-                         storage
+                         storage/images
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program

docs/user/apidoc.dox

@@ -1,9 +1,12 @@
 /*
  * Copyright 2007 Niels Sascha Reedijk. All rights reserved.
+ * Copyright 2008-2013 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		Niels Sascha Reedijk, [email protected]
+ *		John Scipione, [email protected]
+ *
  * Proofreaders:
  *		Alan Smale, [email protected]
  */
@@ -67,8 +70,8 @@
 			not only means that they get the same name, but also that the order
 			of the methods, variables, functions, etc. will have to be the same.
 		-# The root directory of the public API headers is at \c
-			/trunk/headers/os. In a similar vein, the root of the documentation
+			headers/os. In a similar vein, the root of the documentation
-			files is at \c /trunk/docs/user. The subdirectory
+			files is at \c docs/user. The subdirectory
 			structure, or the division of kits, will also be replicated.
 		-# The name of the files is the same as the base of the header files,
 			with the \c dox extension. So \c Something.h becomes \c
@@ -80,41 +83,52 @@
 	copyright block, with a reference to the author(s) and against which
 	revision the documentation was written.
 
-	\verbatim
+\verbatim
 /*
-* Copyright 2007 Niels Sascha Reedijk. All rights reserved.
+ * Copyright 2007-2013 Haiku, Inc. All rights reserved.
-* Distributed under the terms of the MIT License.
+ * Distributed under the terms of the MIT License.
-*
+ *
-* Authors:
+ * Authors:
-*		Niels Sascha Reedijk, [email protected]
+ *      Niels Sascha Reedijk, [email protected]
-* Proofreaders:
+ *
-*		Alan Smale, [email protected]
+ * Proofreaders:
-* Corresponds to:
+ *      Alan Smale, [email protected]
-*		/trunk/headers/os/support/String.h  rev 19731
+ *
-*		/trunk/src/kits/support/String.cpp  rev 19731
+ * Corresponds to:
-*/
+ *      headers/os/support/String.h  rev 19731
-	\endverbatim
+ *      src/kits/support/String.cpp  rev 19731
+ */
+\endverbatim
 
 	The example above has a few elements that you should take note of:
-	-# The header is put in a standard C comment, which is enclosed between \c
+	-# The header is put in a standard C comment, which is enclosed between
-		/* and \c *\/.
+\verbatim
-	-# Every line starts with a whitespace and an asterix, followed by another
+/*
+\endverbatim
+	and 
+\verbatim
+*/
+\endverbatim
+	-# Every line starts with a whitespace and an asterisk followed by another
 		space. If the text is part of a category, such as <tt>Authors</tt>, put
 		three spaces after the delimiter. 
 	-# The first line is empty, then we get to the copyright notice. You may
 		either retain the copyright yourself, or you can attribute to to Haiku
-		Inc. It's your choice. The next line is the \e MIT licence notice,
+		Inc. It's your choice. The next line is the \e MIT License notice,
 		followed by an empty line.
 	-# Then there is a label <tt>Authors:</tt>, which is followed by
 		lines with names and email addresses. The latter one is optional, but
-		recommended. Each author is preceeded by two tabs after the asterix.
+		recommended. Each author is proceeded by two tabs after the asterisk.
 	-# In the same vein there is the label <tt>Proofreaders:</tt> in case the
 		file has been proofread.
 	-# The final part is underneath the label <tt>Corresponds to:</tt>.
 		Underneath there is a list of files and their svn revisions that the
 		current documentation is known to correspond with.
-	-# The header block ends with the \c *\/, where the asterix is aligned with
+	-# The header block ends with the
-		the ones above it.
+\verbatim
+*/
+\endverbatim
+		where the asterisk is aligned with the ones above it.
 
 	\subsection formalrequirements_blocks Blocks
 	
@@ -126,27 +140,34 @@
 	we need to reproduce them in our \c dox files.
 
 	Blocks should adhere to the following standards:
-	-# All blocks open with \c /*! and close with \c * /
+	-# All blocks open with
+\verbatim
+/*!
+\endverbatim
+		and close with
+\verbatim
+*/
+\endverbatim
 	-# The documentation is placed in between these markers.
 	-# All the contents in between the markers is indented by tabs. The tab
 		length should be four.
 	-# Between blocks, there should be two empty lines.
-	-# The maximum width of the contents between blocks is 80 columns. <em>Try
+	-# The maximum width of the contents between blocks is 80 columns. <b>Try
-		not to cross this limit</em>, because it will severely limit
+		not to cross this limit</b>, because it will severely limit
 		readability.
-	
+
 	Example:
-	\verbatim
+\verbatim
 /*!
-	\fn bool BList::AddItem(void *item)
+    \fn bool BList::AddItem(void *item)
-	\brief Append an item to the list.
+    \brief Append an item to the list.
-	
+
-	\param item The item to add.
+    \param item The item to add.
-	\retval true The item was appended.
+    \retval true The item was appended.
-	\retval false Item was not appended, since resizing the list failed.
+    \retval false Item was not appended, since resizing the list failed.
-	\sa AddItem(void *item, int32 index)
+    \sa AddItem(void *item, int32 index)
 */
-	\endverbatim
+\endverbatim
 	
 	\note Doxygen also allows the use of single line comments, starting with 
 		\c //!, however, we won't use these \b except for group markers, which
@@ -253,7 +274,6 @@
 	There are also a number of things that can be used in pages and member
 	documentation. See the style section to find out the appropriate situations
 	in which to use them.
-
 	- \c \\note {text}
 	- \c \\attention {text}
 	- \c \\warning {text}
@@ -312,7 +332,7 @@
 	same arguments as \c \\page, namely the \c \<name\> and the
 	<tt>(title)</tt>. If you need a deeper hierarchy you may use \c \\subsection
 	and \c \\subsubsection, again, both with the same syntax. If you need to
-	distinguish between sections in subsubsections, you are able to use 
+	distinguish between sections in sub-sub-sections, you are able to use
 	\c \\paragraph, which takes the same arguments.
 
 	\note Before and after each of the commands above, you need to have an empty
@@ -349,17 +369,20 @@
 
 \verbatim
 /*!
-	\\name Appending Methods
+    \name Appending Methods
-	
+
-	These methods append things to the object.
+    These methods append things to the object.
 */
 
 
 //! \@{
 
-... names of the methods ...
+
+... methods ...
+
 
 //! \@}
+
 \endverbatim
 
 	The block preceding the block opening marker, <tt>//! \@{</tt>, contains a
@@ -401,7 +424,7 @@
 	Modules are defined in the main book, and you can add classes to them by
 	using the \c \\ingroup command. This commands adds the class to the module
 	and groups it on a separate page. At this moment, the group handling has yet
-	to be finalised. For now, add the classes to the kit they belong in. In the
+	to be finalized. For now, add the classes to the kit they belong in. In the
 	future this might change.
 
 	Finally, it is a good idea to link between parts of the documentation. There
@@ -431,10 +454,10 @@
 		here, which means you should use the right names. So use \b method
 		instead of function, and data member instead of variable (where
 		appropriate). 
-	- Avoid informalism. Avoid constructs like 'if you want to
+	- Avoid in-formalism. Avoid constructs like 'if you want to
 		disconnect the object', but rather use 'to disconnect the object'. Avoid
-		familiarisms, or jokes.
+		familiarizes, or jokes.
-	
+
 	\remarks It isn't the goal to create dry, legal-style documentation. Just
 		try to find a balance. Read through documentation that's already been
 		approved to get a hint of what you should be aiming for.
@@ -497,15 +520,15 @@
 
 \verbatim
 /*!
-	\file String.h
+    \file String.h
-	\brief Defines the BString class and global operators and functions for 
+    \brief Defines the BString class and global operators and functions for
-		handling strings.
+           handling strings.
 */
 
 
 /*!
-	\file SupportDefs.h
+    \file SupportDefs.h
-	\brief Defines basic types and definitions for the Haiku API.
+    \brief Defines basic types and definitions for the Haiku API.
 */ 
 \endverbatim
 
@@ -619,15 +642,15 @@
 	They are a short phrase that mention what the variable contains. Example:
 
 \verbatim
-	/*!
+/*!
-	\var char* BString::fPrivateData
+    \var char* BString::fPrivateData
-	\brief BString's storage for data.
+    \brief BString's storage for data.
-	
+
-	This member is deprecated and might even become \c private in future
+    This member is deprecated and might even become \c private in future
-	releases.
+    releases.
-	
+
-	If you are planning to derive from this object and you want to manipulate
+    If you are planning to derive from this object and you want to manipulate
-	the raw string data, please have a look at LockBuffer() and UnlockBuffer().
+    the raw string data, please have a look at LockBuffer() and UnlockBuffer().
 */
 \endverbatim
 
@@ -667,18 +690,18 @@
 	documentation belongs to the class description, not to the enumeration.
 
 	\subsection style_groups Groups
-	
+
 	If you subdivide members of classes into groups, you have the ability to
 	apply some general information that will be listed above the listing of the
 	members in that group. See the section \ref commands_grouping on how to
 	define groups. This section is on what to put in the header block.
-	
+
 	First of all, it's probably a good idea to give your group a name. This name
 	will be printed as a title and will enhance the clarity of what the group
 	contains. If you put the \c \\name command as the first command of a group,
 	the rest of the words on that line will be used as the title. You should
 	choose simple titles of no more than three words.
-	
+
 	It's possible to add one or two paragraphs of information. These paragraphs
 	should contain some quick notes on which of the members in that group to use
 	for what purpose. See it as a quick subdivision that a developer could use
@@ -688,17 +711,18 @@
 
 \verbatim
 /*!
-	\name Comparison Methods
+    \name Comparison Methods
-	
+
-	There are two different comparison methods. First of all there is the whole
+    There are two different comparison methods. First of all there is the whole
-	range of operators that return a boolean value, secondly there are methods
+    range of operators that return a boolean value, secondly there are methods
-	that return an integer value, both case sensitive and case insensitive.
+    that return an integer value, both case sensitive and case insensitive.
-	
+
-	There are also global comparison operators and global compare functions.
+    There are also global comparison operators and global compare functions.
-	You might need these in case you have a sort routine that takes a generic
+    You might need these in case you have a sort routine that takes a generic
-	comparison function, such as BList::SortItems().
+    comparison function, such as BList::SortItems().
-	See the String.h documentation file to see the specifics, as they are
+
-	basically the same as implemented in this class.
+    See the String.h documentation file to see the specifics, as they are
+    basically the same as implemented in this class.
 */
 \endverbatim
 
@@ -706,5 +730,4 @@
 	the members up into two groups and refers to other functions the developer
 	might be looking for. The hard limit is two (short) paragraphs. Using more
 	will not improve clarity.
-
 */

docs/user/app/Application.dox

@@ -1,18 +1,20 @@
 /*
- * Copyright 2011, Haiku, Inc. All Rights Reserved.
+ * Copyright 2011 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		John Scipione, [email protected]
  * 
  * Corresponds to:
- *		/trunk/headers/os/app/Application.h	 rev 42794
+ *		headers/os/app/Application.h	rev 42794
- *		/trunk/src/kits/app/Application.cpp	 rev 42794
+ *		src/kits/app/Application.cpp	rev 42794
  */
 
 
 /*!
 	\file Application.h
+	\ingroup app
+	\ingroup libbe
 	\brief Provides the BApplication class.
 */
 

docs/user/app/Clipboard.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2011, Haiku, Inc. All Rights Reserved.
+ * Copyright 2011 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -7,13 +7,15 @@
  *		John Scipione, [email protected]
  * 
  * Corresponds to:
- *		/trunk/headers/os/app/Clipboard.h	 rev 42274
+ *		headers/os/app/Clipboard.h	 rev 42274
- *		/trunk/src/kits/app/Clipboard.cpp	 rev 42274
+ *		src/kits/app/Clipboard.cpp	 rev 42274
  */
 
 
 /*!
 	\file Clipboard.h
+	\ingroup app
+	\ingroup libbe
 	\brief Provides the BClipboard class.
 */
 
@@ -27,6 +29,7 @@
 /*!
 	\class BClipboard
 	\ingroup app
+	\ingroup libbe
 	\brief Used for short-term data storage between documents and
 		applications via copy and paste operations.
 

docs/user/app/Cursor.dox

@@ -1,18 +1,20 @@
 /*
- * Copyright 2012 Haiku, Inc. All Rights Reserved.
+ * Copyright 2012 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		John Scipione, [email protected]
  * 
  * Corresponds to:
- *		/trunk/headers/os/app/Cursor.h	 hrev45039
+ *		headers/os/app/Cursor.h	 hrev45039
- *		/trunk/src/kits/app/Cursor.cpp	 hrev45039
+ *		src/kits/app/Cursor.cpp	 hrev45039
  */
 
 
 /*!
 	\file Cursor.h
+	\ingroup app
+	\ingroup libbe
 	\brief Provides the BCursor class.
 */
 
@@ -200,6 +202,7 @@
 /*!
 	\class BCursor
 	\ingroup app
+	\ingroup libbe
 	\brief BCursor describes a view-wide or application-wide cursor.
 
 	\note As BeOS only supports 16x16 monochrome cursors, to see a nice

docs/user/app/Handler.dox

@@ -1,22 +1,26 @@
 /*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  * 		Niels Sascha Reedijk, [email protected]
  * 
  * Corresponds to:
- *		/trunk/headers/os/app/Handler.h  rev 22577
+ *		headers/os/app/Handler.h	rev 22577
- *		/trunk/src/kits/app/Handler.cpp  rev 21332
+ *		src/kits/app/Handler.cpp	rev 21332
  */
 
 /*!
 	\file Handler.h
+	\ingroup app
+	\ingroup libbe
 	\brief Provides the BHandler class.
 */
 
+
 ///// Globals /////
 
+
 /*!
 	\def B_OBSERVE_WHAT_CHANGE
 	\brief Internal.
@@ -51,6 +55,7 @@
 /*!
 	\class BHandler
 	\ingroup app
+	\ingroup libbe
 	\brief Handles messages that are passed on by a BLooper.
 
 	The BHandler class implements two important pieces of functionality. It

docs/user/app/Looper.dox

@@ -1,17 +1,19 @@
 /*
- * Copyright 2008, Haiku, Inc. All Rights Reserved.
+ * Copyright 2008 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  * 		Niels Sascha Reedijk, [email protected]
  * 
  * Corresponds to:
- *		/trunk/headers/os/app/Looper.h  rev 21863
+ *		headers/os/app/Looper.h	rev 21863
- *		/trunk/src/kits/app/Looper.cpp  rev 21864
+ *		src/kits/app/Looper.cpp	rev 21864
  */
 
 /*!
 	\file Looper.h
+	\ingroup app
+	\ingroup libbe
 	\brief Provides the BLooper class.
 */
 
@@ -25,6 +27,7 @@
 /*!
 	\class BLooper
 	\ingroup app
+	\ingroup libbe
 	\brief Receive and process messages in a separate thread.
 	
 	When an object of this class is created, the message loop can be started

docs/user/app/MessageFilter.dox

@@ -1,14 +1,20 @@
 /*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		Niels Sascha Reedijk, [email protected]
+ * 
+ * Corresponds to:
+ *		headers/os/app/MessageFilter.h
+ *		src/kits/app/MessageFilter.cpp
  */
 
 
 /*!
 	\file MessageFilter.h
+	\ingroup app
+	\ingroup libbe
 	\brief Provides BMessageFilter class.
 */
 
@@ -18,7 +24,7 @@
 	\brief Return Codes and Protocol of the #filter_hook.
 
 	These return codes should be used in your own filter_hook function, or by
-	your overrided BMessageFilter::Filter() function.
+	your overridden BMessageFilter::Filter() method.
 */
 
 
@@ -137,6 +143,7 @@
 /*!
 	\class BMessageFilter
 	\ingroup app
+	\ingroup libbe
 	\brief Describes a message filter for BLooper and BHandler.
 
 	Objects of this class serve as a description of properties that incoming
@@ -327,4 +334,3 @@ looper->AddCommonFilter(filter);
 	\fn BLooper *BMessageFilter::Looper() const
 	\brief Return the looper this filter is associated with.
 */
-

docs/user/app/MessageQueue.dox

@@ -1,10 +1,10 @@
 /*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007, Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
- * 		Niels Sascha Reedijk, [email protected]
+ *		Niels Sascha Reedijk, [email protected]
- * 
+ *
  * Corresponds to:
  *		/trunk/headers/os/app/MessageQueue.h  rev 19956
  *		/trunk/src/kits/app/MessageQueue.cpp  rev 19956
@@ -12,6 +12,8 @@
 
 /*!
 	\file MessageQueue.h
+	\ingroup app
+	\ingroup libbe
 	\brief Provides the BMessageQueue class.
 */
 
@@ -19,17 +21,18 @@
 /*!
 	\class BMessageQueue
 	\ingroup app
+	\ingroup libbe
 	\brief A container that maintains a queue of messages.
-	
+
 	This class is used by BLooper to maintain a queue of messages that need to
 	be processed. This class has been designed as a first in, first out
 	container.
-	
+
 	The default message handling of a BLooper probably suffices for most uses,
 	but if you want more control, you can perform operations using the methods
 	of this class. Use BLooper::MessageQueue() to retrieve the specific
 	BMessageQueue instance. 
-	
+
 	Note that you are encouraged to make sure that whichever operation you
 	perform, that you only do this after the object has been locked (see
 	Lock()). The most important method, NextMessage() will fail if you have not
@@ -65,7 +68,7 @@
 	The message has to be allocated on the heap with \c new, because the queue
 	claims ownership of the message. Messages that were constructed on the
 	stack will corrupt the queue.
-	
+
 	Because a BMessageQueue claims ownership of the \a message, it is important
 	that the message does not belong to another BMessageQueue.
 */
@@ -74,7 +77,7 @@
 /*!
 	\fn void BMessageQueue::RemoveMessage(BMessage* message)
 	\brief Remove a \a message from the queue.
-	
+
 	If the \a message is indeed associated with this queue, it is removed from
 	it. This effectively means that you regain ownership of the message.
 */
@@ -95,9 +98,9 @@
 /*!
 	\fn BMessage *BMessageQueue::FindMessage(int32 index) const
 	\brief Retrieve the message at the \a index of this queue.
-	
+
 	\param index A zero-based index of the message you want to retrieve.
-	
+
 	\return A pointer to a message, or \c NULL if the \a index is out of
 		bounds.
 	\see FindMessage(uint32, int32) for a variant that takes a specific \c what
@@ -112,7 +115,7 @@
 
 	\param index A zero-based index of the message you want to retrieve.
 	\param what The \a what code of the message.
-	
+
 	\return A pointer to a message, or \c NULL if there is no message at the
 		\a index with that \a what constant, or if the \a index is out of
 		bounds.
@@ -122,7 +125,7 @@
 /*!
 	\fn bool BMessageQueue::Lock()
 	\brief Lock the queue so no other thread can perform operations on it.
-	
+
 	\see Unlock()
 */
 
@@ -130,7 +133,7 @@
 /*!
 	\fn void BMessageQueue::Unlock()
 	\brief Unlock the queue after a Lock() request.
-	
+
 	\see Lock()
 */
 
@@ -146,10 +149,10 @@
 /*!
 	\fn BMessage *BMessageQueue::NextMessage()
 	\brief Remove the first BMessage on the queue and return it to the caller.
-	
+
 	After calling this method, you get the ownership of the message, so make
 	sure it is deleted after you are done.
-	
+
 	\return A pointer to a message, or \c NULL if the queue is empty, or the
 		object has not been properly locked.
 	\see Lock()

docs/user/app/_app_intro.dox

@@ -1,21 +1,21 @@
 /*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * 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]
  */
 
 
 /*!
 	\page app_intro Introduction to the Application Kit.
-  
+
 	The Application Kit should be your starting point if you want to write
 	native Haiku applications with a GUI. The application kit does
 	exactly as its name suggests; it is the basis for Haiku	applications.  You
 	should read through this document and the documents referenced here before
 	moving on to any other part of the API. 
-  
+
 	The Application Kit classes can be divided into two groups: the "messaging"
 	classes and the "system interaction" classes.  The larger group contains
 	the messaging classes. Have a look at the \link app_messaging
@@ -29,7 +29,7 @@
 	- BMessageQueue
 	- BMessageRunner
 	- BMessenger
-  
+
 	The second group is the system interaction classes. These classes
 	provide hooks for your application to interact with the rest of the system.
 	The most important class is BApplication. This is a list of all the

docs/user/app/_app_messaging.dox

@@ -1,15 +1,14 @@
 /*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		Niels Sascha Reedijk, [email protected]
  */
 
-
 /*!
 	\page app_messaging Messaging Foundations
-	
+
 	One of the foundations of the Haiku API is the messaging system. This
 	framework is the basis for the efficient multithreaded Haiku applications,
 	because it solves one of the fundamental issues of multithreading: it
@@ -17,21 +16,21 @@
 	framework allows inter-application messaging as well as 
 	intra-application messaging, and it will always use the most effective
 	mechanism for the communication automatically.
-	
+
 	This page will introduce you to the subject of messaging. It is meant as a
 	broad overview to the classes, rather than a tutorial. If you are looking
 	for effective messaging techniques or a tutorial on messaging, have a look
 	at the developer section of the Haiku website.
-	
+
 	<b>Table of contents</b>
 	- Overview of the Messaging Classes
 	- Receiving and Handling Messages
 	- Sending messages
-	
+
 	\section app_messaging_overview Overview of the Messaging Classes
-	
+
 	\subsection app_messaging_overview_bmessage BMessage
-	
+
 	The BMessage class is the class that is in the center of all the messenger
 	operations, because it represents a message. A message is nothing more than
 	an object that contains:
@@ -49,15 +48,15 @@
 	context. The Haiku API defines several messages and their required data
 	members. Several applications provide a scripting interface with defined
 	message syntax. You can do the same for your application.
-	
+
 	\subsection app_messaging_overview_blooper BLooper
-	
+
 	Objects of the BLooper type are objects that run message loops. Every
 	object runs in its own thread. The BLooper objects continually check for
 	incoming messages. To process the messages, the looper looks for message
 	handlers that handle the messages within the thread's context. Message
 	handling within a looper is synchronous.
-	
+
 	BLooper inherits BHandler, the base class for message handling. However, it
 	is possible to chain additional handlers to the object. For example, if you
 	have an application that understands different networking protocols, and
@@ -65,23 +64,23 @@
 	can provide handlers that you can chain in your general message parser
 	thread. See AddHandler() and SetPreferredHandler() for information on
 	handlers.
-	
+
 	Messages can be posted to the looper by using the object's PostMessage()
 	method. This method puts the message in the BMessageQueue of the looper.
 	Since PostMessage() is asynchronous, the message might not be handled
 	immediately. See \ref app_messaging_overview_bmessenger "BMessenger"
 	for a synchronous implementation.
-	
+
 	Loopers can have a generic filter that discards messages based on
 	user-definable characteristics. The BMessageFilter class provides the
 	foundation for the qualifying of messages. See AddCommonFilterList() and
 	SetCommonFilterList() for more information.
-	
+
 	To get the most out of the functionality of BLooper, it is usually
 	subclassed to create a self-contained event 'machine'. Most of the time,
 	these subclasses also perform the message handling, which is possible
 	due to the fact that it is also a subclass of BHandler.
-	
+
 	In the Haiku API, there are two major classes that inherit BLooper:
 	the base application class, BApplication, and the window class, BWindow.
 	Because they inherit BLooper, each application and each window has its
@@ -90,47 +89,47 @@
 	event handling that requires more processing power, is done within its own
 	BLooper context. Networking usually qualifies as a candidate for its own
 	thread.
-	
+
 	\subsection app_messaging_overview_bhandler BHandler
-	
+
 	Objects of the BHandler type are associated to BLoopers. When they are
 	created, they should be passed to the BLooper::AddHandler() method of the
 	looper they want to handle messages for. They can then either be set as
 	preferred handlers (by chaining them with BLooper::SetPreferredHandler()),
 	or they can be added to other BHandlers with the SetNextHandler() method.
-	
+
 	The magic of the class happens in the MessageReceived() method. In your
 	subclasses you override this method, to check the incoming BMessage.
 	Usually, you check the \c what member of the message in a switch statement.
 	If your handler cannot handle the object, it will pass the message on to
 	the parent class. 
-	
+
 	\warning Don't forget to actuall call the MessageReceived() method of the
 		base class. Failing to do this will mean that the message chain will
 		not completely be followed, which can lead to unhandled messages. There
 		might be some internal system messages that the Haiku API classes
 		handle, and not actually handling these messages could lead to
 		inconsistent internal behavior.
-	
+
 	\subsection app_messaging_overview_bmessenger BMessenger
-	
+
 	BMessenger objects can send messages to both local and remote targets. For
 	local targets, a BMessenger provides an advantage over directly calling
 	the BLooper::PostMessage() method: some variants of the 
 	BMessenger::SendMessage() methods allow for synchronous replies. So, the
 	call will actually verify the handling thread processes the message, and
 	reply to the sender.
-	
+
 	The other feature of BMessenger is that it is able to be constructed with
 	the signature of another application as argument. This allows the messenger
 	to pass messages to other applications. It facilitates inter-application
 	communication.
-	
+
 	\subsection app_messaging-overview-other Other messaging classes
-	
+
 	There are several convenience classes supplied with the application kit,
 	which can make your life easier in some specific cases. 
-	
+
 	- BInvoker binds together a message and a target. By calling 
 	  BInvoker::Invoke(), the message will be sent. This class is inherited by
 	  the controls in the interface kit, such as BButton.
@@ -146,12 +145,10 @@
 	  Filter() \endlink method.
 
 	\section app-messaging-receiving Receiving Messages
-	
+
 	To do...
-	
+
 	\section app-messaging-sending Sending Messages
-	
+
 	To do...
-	
 */
-	

docs/user/book.css

@@ -1,13 +1,13 @@
 /*
- * Copyright 2008, Haiku. All rights reserved.
+ * Copyright 2008-2013 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
- *		François Revol <[email protected]>
+ *		François Revol, [email protected]
- *		Stephan Aßmus <[email protected]>
+ *		Stephan Aßmus, [email protected]
- *		Braden Ewing <[email protected]>
+ *		Braden Ewing, [email protected]
- *		Humdinger <[email protected]>
+ *		Humdinger, [email protected]
- *		John Scipione <[email protected]>
+ *		John Scipione, [email protected]
  */
 
 /* color names provided by: http://chir.ag/projects/name-that-color */
@@ -279,7 +279,23 @@ div.contents code {
 }
 
 div.contents div.dynheader {
-	margin-bottom: 16px;
+	color: #0c3762; /* madison */
+	font-size: 1.3em;
+	font-weight: normal;
+	border-bottom: dotted thin #c0c0c0; /* silver */
+	margin-top: 1em;
+	margin-bottom: 1em;
+}
+
+div.contents div.dyncontent {
+	width: 100%;
+	border: 1px solid #c7c7c7; /* silver */
+	overflow: auto;
+}
+
+div.contents div.dyncontent div.center {
+	text-align: center;
+	margin: 16px;
 }
 
 div.contents span.keycap, div.contents span.keysym {

docs/user/drivers/USB_spec.dox

@@ -1,296 +1,358 @@
 /*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * 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]
+ *
  * Corresponds to:
- * /trunk/headers/os/drivers/USB_spec.h rev 19915
+ *		headers/os/drivers/USB_spec.h rev 19915
  */
- 
+
-/*!
-  \file USB_spec.h
-  \brief General definitions as defined by the USB standard.
-*/
 
 /*!
-  \name Request Types: targets and direction
+	\file USB_spec.h
-  
+	\ingroup drivers
-  These request types can be used in the usb_module_info::send_request()
+	\ingroup libbe
-  and usb_module_info::queue_request() methods. They specifiy both the type
+	\brief General definitions as defined by the USB standard.
-  of interface and the direction of the transfer.
-  
-  These are usually combined with a category (found on this page).
 */
 
+
+/*!
+	\name Request Types: targets and direction
+
+	These request types can be used in the usb_module_info::send_request()
+	and usb_module_info::queue_request() methods. They specifiy both the type
+	of interface and the direction of the transfer.
+
+	These are usually combined with a category (found on this page).
+*/
+
+
 //! @{
 
+
 /*! 
-  \def USB_REQTYPE_DEVICE_IN
+	\def USB_REQTYPE_DEVICE_IN
-  \brief Device. In. 
+	\brief Device. In.
 */
 
+
 /*!
-  \def USB_REQTYPE_DEVICE_OUT
+	\def USB_REQTYPE_DEVICE_OUT
-  \brief Device. Out.
+	\brief Device. Out.
 */
 
+
 /*!
-  \def USB_REQTYPE_INTERFACE_IN
+	\def USB_REQTYPE_INTERFACE_IN
-  \brief Interface. In.
+	\brief Interface. In.
 */
 
+
 /*!
-  \def USB_REQTYPE_INTERFACE_OUT
+	\def USB_REQTYPE_INTERFACE_OUT
-  \brief Interface. Out.
+	\brief Interface. Out.
 */
 
-/*! 
-  \def USB_REQTYPE_ENDPOINT_IN
-  \brief Endpoint. In.
-*/
 
 /*!
-  \def USB_REQTYPE_ENDPOINT_OUT
+	\def USB_REQTYPE_ENDPOINT_IN
-  \brief Endpoint. Out.
+	\brief Endpoint. In.
 */
 
-/*!
-  \def USB_REQTYPE_OTHER_OUT 
-  \brief Other. Out.
-*/
 
 /*!
-  \def USB_REQTYPE_OTHER_IN
+	\def USB_REQTYPE_ENDPOINT_OUT
-  \brief Other. In.
+	\brief Endpoint. Out.
 */
 
+
+/*!
+	\def USB_REQTYPE_OTHER_OUT 
+	\brief Other. Out.
+*/
+
+
+/*!
+	\def USB_REQTYPE_OTHER_IN
+	\brief Other. In.
+*/
+
+
 //! @}
 
-/*! 
+
-  \name Request Types: categories
+/*!
-  
+	\name Request Types: categories
-  These request types can be used in the usb_module_info::send_request()
+
-  and usb_module_info::queue_request() methods. They specifiy the category
+	These request types can be used in the usb_module_info::send_request()
-  of the transfer.
+	and usb_module_info::queue_request() methods. They specifiy the category
-  
+	of the transfer.
-  These are usually combined with a target and direction (found on this page).
+
+	These are usually combined with a target and direction (found on this page).
 */
 
+
 //! @{
 
-/*! 
-  \def USB_REQTYPE_STANDARD
-  \brief Request that adheres to the USB specifications.
-*/
 
 /*!
-  \def USB_REQTYPE_CLASS
+	\def USB_REQTYPE_STANDARD
-  \brief Request that adheres to the specifications of the class.
+	\brief Request that adheres to the USB specifications.
 */
 
-/*!
-  \def USB_REQTYPE_VENDOR
-  \brief Request that is defined by the specifications of the vendor.
-*/
 
 /*!
-  \def USB_REQTYPE_RESERVED
+	\def USB_REQTYPE_CLASS
-  \brief Reserved for special implementations.
+	\brief Request that adheres to the specifications of the class.
 */
 
+
 /*!
-  \def USB_REQTYPE_MASK
+	\def USB_REQTYPE_VENDOR
-  \brief Constant that can be used as mask over the requesttype field.
+	\brief Request that is defined by the specifications of the vendor.
 */
 
+
+/*!
+	\def USB_REQTYPE_RESERVED
+	\brief Reserved for special implementations.
+*/
+
+
+/*!
+	\def USB_REQTYPE_MASK
+	\brief Constant that can be used as mask over the requesttype field.
+*/
+
+
 //! @}
 
+
 /*!
-  \name Standard Request Values
+	\name Standard Request Values
-  
+
-  These request values are defined by the USB standard. You can use these
+	These request values are defined by the USB standard. You can use these
-  constants in both the usb_module_info::send_request() and
+	constants in both the usb_module_info::send_request() and
-  usb_module_info::queue_request() methods.
+	usb_module_info::queue_request() methods.
-  
+
-  \warning The stack handles most of these standard requests for you. Use the
+	\warning The stack handles most of these standard requests for you. Use the
-  supplied convenience functions the the usb_module_info interface rather than
+	supplied convenience functions the the usb_module_info interface rather than
-  doing the requests yourself. Some of these request may actually interfere
+	doing the requests yourself. Some of these request may actually interfere
-  with the inner workings of the USB stack!
+	with the inner workings of the USB stack!
 */
 
+
 //! @{
 
-/*!
-  \def USB_REQUEST_GET_STATUS
-  \brief Get the status of a device.
-*/
 
 /*!
-  \def USB_REQUEST_CLEAR_FEATURE 
+	\def USB_REQUEST_GET_STATUS
-  \brief Clear a feature.
+	\brief Get the status of a device.
 */
 
-/*!
-  \def USB_REQUEST_SET_FEATURE 
-  \brief Set a feature.
-*/
 
 /*!
-  \def USB_REQUEST_SET_ADDRESS
+	\def USB_REQUEST_CLEAR_FEATURE 
-  \brief Set the device address.
+	\brief Clear a feature.
 */
 
-/*!
-  \def USB_REQUEST_GET_DESCRIPTOR 
-  \brief Get a descriptor.
-*/
 
 /*!
-  \def USB_REQUEST_SET_DESCRIPTOR 
+	\def USB_REQUEST_SET_FEATURE 
-  \brief Update a descriptor to a supplied one.
+	\brief Set a feature.
 */
 
-/*!
-  \def USB_REQUEST_GET_CONFIGURATION
-  \brief Get a configuration.
-*/
 
 /*!
-  \def USB_REQUEST_SET_CONFIGURATION 
+	\def USB_REQUEST_SET_ADDRESS
-  \brief Set the configuration.
+	\brief Set the device address.
 */
 
-/*!
-  \def USB_REQUEST_GET_INTERFACE
-  \brief Request an interface descriptor.
-*/
 
 /*!
-  \def USB_REQUEST_SET_INTERFACE
+	\def USB_REQUEST_GET_DESCRIPTOR 
-  \brief Set a specific interface.
+	\brief Get a descriptor.
 */
 
+
 /*!
-  \def USB_REQUEST_SYNCH_FRAME
+	\def USB_REQUEST_SET_DESCRIPTOR 
-  \brief Synchronize a frame.
+	\brief Update a descriptor to a supplied one.
 */
 
+
+/*!
+	\def USB_REQUEST_GET_CONFIGURATION
+	\brief Get a configuration.
+*/
+
+
+/*!
+	\def USB_REQUEST_SET_CONFIGURATION 
+	\brief Set the configuration.
+*/
+
+
+/*!
+	\def USB_REQUEST_GET_INTERFACE
+	\brief Request an interface descriptor.
+*/
+
+
+/*!
+	\def USB_REQUEST_SET_INTERFACE
+	\brief Set a specific interface.
+*/
+
+
+/*!
+	\def USB_REQUEST_SYNCH_FRAME
+	\brief Synchronize a frame.
+*/
+
+
 //! @}
 
+
 /*!
-  \name Descriptor Constants
+	\name Descriptor Constants
-  
+
-  These constants refer to a specific descriptor. They can be used when
+	These constants refer to a specific descriptor. They can be used when
-  building a standard USB request for a descriptor, or in the
+	building a standard USB request for a descriptor, or in the
-  usb_module_info::get_descriptor() method.
+	usb_module_info::get_descriptor() method.
 */
 
+
 //! @{
 
-/*!
-  \def USB_DESCRIPTOR_DEVICE
-  \brief Constant for the device descriptor.
-*/
 
 /*!
-  \def USB_DESCRIPTOR_CONFIGURATION
+	\def USB_DESCRIPTOR_DEVICE
-  \brief Constant for a configuration descriptor.
+	\brief Constant for the device descriptor.
 */
 
-/*!
-  \def USB_DESCRIPTOR_STRING
-  \brief Constant for a string descriptor.
-*/
 
 /*!
-  \def USB_DESCRIPTOR_INTERFACE
+	\def USB_DESCRIPTOR_CONFIGURATION
-  \brief Constant for an interface descriptor.
+	\brief Constant for a configuration descriptor.
 */
 
+
 /*!
-  \def USB_DESCRIPTOR_ENDPOINT
+	\def USB_DESCRIPTOR_STRING
-  \brief Constant for an endpoint descriptor.
+	\brief Constant for a string descriptor.
 */
 
+
+/*!
+	\def USB_DESCRIPTOR_INTERFACE
+	\brief Constant for an interface descriptor.
+*/
+
+
+/*!
+	\def USB_DESCRIPTOR_ENDPOINT
+	\brief Constant for an endpoint descriptor.
+*/
+
+
 //! @}
 
+
 /*!
-  \name Feature Requests
+	\name Feature Requests
-  
+
-  These constants refer to standard feature requests. You can use these using
+	These constants refer to standard feature requests. You can use these
-  the convenient usb_module_info::set_feature() and 
+	using the convenient usb_module_info::set_feature() and 
-  usb_module_info::clear_feature() methods.
+	usb_module_info::clear_feature() methods.
 */
 
+
 //! @{
 
-/*!
-  \def USB_FEATURE_DEVICE_REMOTE_WAKEUP
-  \brief Request a device to wakeup from remote calls.
-*/
 
 /*!
-  \def USB_FEATURE_ENDPOINT_HALT
+	\def USB_FEATURE_DEVICE_REMOTE_WAKEUP
-  \brief Request for a specific endpoint to halt.
+	\brief Request a device to wakeup from remote calls.
 */
 
+
+/*!
+	\def USB_FEATURE_ENDPOINT_HALT
+	\brief Request for a specific endpoint to halt.
+*/
+
+
 //! @}
 
+
 /*!
-  \name Endpoint Attributes
+	\name Endpoint Attributes
-  
+
-  These constants refer to values in the usb_endpoint_descriptor::attributes
+	These constants refer to values in the usb_endpoint_descriptor::attributes
-  field.
+	field.
 */
 
+
 //! @{
 
-/*!
-  \def USB_ENDPOINT_ATTR_CONTROL
-  \brief Endpoint facilitates control transfers.
-*/
 
 /*!
-  \def USB_ENDPOINT_ATTR_ISOCHRONOUS
+	\def USB_ENDPOINT_ATTR_CONTROL
-  \brief Endpoint facilitates isochronous transfers.
+	\brief Endpoint facilitates control transfers.
 */
 
-/*!
-  \def USB_ENDPOINT_ATTR_BULK
-  \brief Endpoint facilitates bulk transfers.
-*/
 
 /*!
-  \def USB_ENDPOINT_ATTR_INTERRUPT
+	\def USB_ENDPOINT_ATTR_ISOCHRONOUS
-  \brief Endpoint facilitates interrupt transfers.
+	\brief Endpoint facilitates isochronous transfers.
 */
 
+
 /*!
-  \def USB_ENDPOINT_ATTR_MASK
+	\def USB_ENDPOINT_ATTR_BULK
-  \brief Constant to mask out transfer types.
+	\brief Endpoint facilitates bulk transfers.
 */
 
+
+/*!
+	\def USB_ENDPOINT_ATTR_INTERRUPT
+	\brief Endpoint facilitates interrupt transfers.
+*/
+
+
+/*!
+	\def USB_ENDPOINT_ATTR_MASK
+	\brief Constant to mask out transfer types.
+*/
+
+
 //! @}
 
+
 /*!
-  \name Endpoint Address
+	\name Endpoint Address
-  
+
-  These constants refer to the direction that is embedded in the
+	These constants refer to the direction that is embedded in the
-  usb_endpoint_descriptor::address field.
+	usb_endpoint_descriptor::address field.
 */
 
+
 //! @{
 
-/*!
-  \def USB_ENDPOINT_ADDR_DIR_IN
-  \brief The endpoint provides data for the driver.
-*/
 
 /*!
-  \def USB_ENDPOINT_ADDR_DIR_OUT	
+	\def USB_ENDPOINT_ADDR_DIR_IN
-  \brief The endpoint accepts data from the host.
+	\brief The endpoint provides data for the driver.
 */
 
+
+/*!
+	\def USB_ENDPOINT_ADDR_DIR_OUT	
+	\brief The endpoint accepts data from the host.
+*/
+
+
 //! @}
-

docs/user/drivers/drivers.dox

@@ -1,9 +1,7 @@
 /*!
-\page drivers Drivers
+	\page drivers Drivers
-
-\section topics Topics
-
-- \ref fs_modules
-- \ref usb_modules
 
+	\section topics Topics
+	- \ref fs_modules
+	- \ref usb_modules
 */

docs/user/drivers/fs_interface.dox

@@ -14,6 +14,7 @@
 /*!
 	\file fs_interface.h
 	\ingroup drivers
+	\ingroup libbe
 	\brief Provides an interface for file system modules.
 
 	See the \ref fs_modules "introduction to file system modules" for a guide on

docs/user/drivers/fs_modules.dox

@@ -17,7 +17,6 @@
 	a simple mechanism for one-time module initializations. The same module is
 	used for accessing any volume of that FS type.
 
-
 	\section objects File System Objects
 
 	There are several types of objects a FS module has to deal with directly or

docs/user/drivers/usb_modules.dox

@@ -1,386 +1,387 @@
-/*
+/*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007 Haiku Inc. All rights reserved.
- * Distributed under the terms of the MIT License.
+ * Distributed under the terms of the MIT License.
- *
+ *
- * Documentation by:
+ * Authors:
- *  Niels Sascha Reedijk <[email protected]>
+ *		Niels Sascha Reedijk, [email protected]
- */
+ */
-
+
-/*!
+
-  \page usb_modules Writing drivers for USB devices
+/*!
-
+	\page usb_modules Writing drivers for USB devices
-  The introduction of USB standardized the way many devices connected to a
+
-  whole range of different computers and operating systems. It introduced a
+	The introduction of USB standardized the way many devices connected to a
-  standard that was capable of getting rid of all the legacy systems, such as
+	whole range of different computers and operating systems. It introduced a
-  the LPT, the PS/2 and serial ports. The plug and play nature of the standard
+	standard that was capable of getting rid of all the legacy systems, such as
-  were revolutional at the time of it's introduction, and it changed the way
+	the LPT, the PS/2 and serial ports. The plug and play nature of the standard
-  in which operating systems interacted with devices.
+	was revolutionary at the time of its introduction, and it changed the way
-  
+	which operating systems interacted with devices.
-  With the grand standard that USB has become, Haiku has an implementation
+
-  of it. It supports both the USB 1.1 and USB 2.0 specifications, and when
+	With the grand standard that USB has become, Haiku has an implementation
-  Haiku R1 is released, it will support the three host controller standards:
+	of it. It supports both the USB 1.1 and USB 2.0 specifications, and when
-  UHCI, OHCI and EHCI. The modularized design of Haiku's USB stack also paves
+	Haiku R1 is released, it will support the three host controller standards:
-  the way for easy implementation of any future specifications, such as
+	UHCI, OHCI and EHCI. The modularized design of Haiku's USB stack also paves
-  Wireless USB.
+	the way for easy implementation of any future specifications, such as
-  
+	Wireless USB.
-  \section usb_modules_scope The Scope of this Document
+
-  
+	\section usb_modules_scope The Scope of this Document
-  This document is written for driver developers that need to interact with
+
-  USB devices. The USB specification standardizes the communication between
+	This document is written for driver developers that need to interact with
-  the host controller and the devices, and how devices should transfer data,
+	USB devices. The USB specification standardizes the communication between
-  but it does not prescribe a standard environment that Operating Systems
+	the host controller and the devices, and how devices should transfer data,
-  should provide to the driver interfaces. As such, every operating system has
+	but it does not prescribe a standard environment that Operating Systems
-  it's own interface for drivers, and so does Haiku.
+	should provide to the driver interfaces. As such, every operating system has
-  
+	it's own interface for drivers, and so does Haiku.
-  This document will point driver developers to relevant parts of the USB
+
-  module API and give a general impression of the workings of the USB stack.
+	This document will point driver developers to relevant parts of the USB
-  This document will not give information on the basics of writing drivers, or
+	module API and give a general impression of the workings of the USB stack.
-  on how to use modules. Have a look elsewhere in this documentation for that.
+	This document will not give information on the basics of writing drivers, or
-  This document also assumes a basic knowledge of the USB specification, and on
+	on how to use modules. Have a look elsewhere in this documentation for that.
-  how you are supposed to interact with devices. See \ref usb_modules_resources
+	This document also assumes a basic knowledge of the USB specification, and on
-  for tutorials on the web if you are looking for a basic introduction on
+	how you are supposed to interact with devices. See \ref usb_modules_resources
-  communication with the USB protocol.
+	for tutorials on the web if you are looking for a basic introduction on
-  
+	communication with the USB protocol.
-  \section usb_modules_structure Structure of the Stack
+
-  
+	\section usb_modules_structure Structure of the Stack
-  This section will outline how Haiku's USB stack is structured, and how you
+
-  can interact with this stack.
+	This section will outline how Haiku's USB stack is structured, and how you
-  
+	can interact with this stack.
-  The goal of the USB stack is to provide a few basic features for drivers
+
-  interacting with USB devices. It is important that the stack maintains a
+	The goal of the USB stack is to provide a few basic features for drivers
-  continually updated device grid, so that the driver modules are always
+	interacting with USB devices. It is important that the stack maintains a
-  aware of the latest status. The stack should also facilitate communication
+	continually updated device grid, so that the driver modules are always
-  between drivers and the devices, by abstracting the actual transfering of
+	aware of the latest status. The stack should also facilitate communication
-  bits via the host controller hardware in the computer. The stack therefore
+	between drivers and the devices, by abstracting the actual transferring of
-  should implement a inituitive interface to give driver developers access to
+	bits via the host controller hardware in the computer. The stack therefore
-  all features and possibilities the USB specification offers, and at the same
+	should implement a intuitive interface to give driver developers access to
-  time it should abstract many of the small requirements and peculiarities of
+	all features and possibilities the USB specification offers, and at the same
-  that specification.
+	time it should abstract many of the small requirements and peculiarities of
-  
+	that specification.
-  The stack internally can be divided into two parts. The first part is the
+
-  core module. This module, called \c usb_busmanager, performs all the
+	The stack internally can be divided into two parts. The first part is the
-  operations required by the USB specification. For example, it performs the
+	core module. This module, called \c usb_busmanager, performs all the
-  necessary lowlevel initialization when new devices are connected, or all the
+	operations required by the USB specification. For example, it performs the
-  requirements when it comes to performing transfers. The core module also
+	necessary low-level initialization when new devices are connected, or all the
-  is the module that provides the abstractions to driver developers. The other
+	requirements when it comes to performing transfers. The core module also
-  part of the USB stack are the individual modules that control the different
+	is the module that provides the abstractions to driver developers. The other
-  host controllers. Haiku supports the three types in existence: UHCI, OHCI
+	part of the USB stack are the individual modules that control the different
-  and EHCI. These modules perform the communication between the core module
+	host controllers. Haiku supports the three types in existence: UHCI, OHCI
-  and the hardware. As driver developer, you won't have to interact with these
+	and EHCI. These modules perform the communication between the core module
-  modules: the core module provides all the abstractions you need.
+	and the hardware. As driver developer, you won't have to interact with these
-  
+	modules: the core module provides all the abstractions you need.
-  Thus, as a driver developer you are interfacing with the \c usb_busmanager
+
-  module. On Haiku, this module implements two API's. The \c v2 API, identical
+	Thus, as a driver developer you are interfacing with the \c usb_busmanager
-  to the API offered by BeOS R5, can be found in the \c USB2.h file. However,
+	module. On Haiku, this module implements two API's. The \c v2 API, identical
-  for new drivers, or for ports, the recomended API is the \c v3 API, defined
+	to the API offered by BeOS R5, can be found in the \c USB2.h file. However,
-  in the USB3.h file. This API is identical to the one provided by Zeta. The
+	for new drivers, or for ports, the recommended API is the \c v3 API, defined
-  \c v2 API should be considered to be deprecated.
+	in the USB3.h file. This API is identical to the one provided by Zeta. The
-  
+	\c v2 API should be considered to be deprecated.
-  \section usb_modules_registration Initial Steps: Driver Registration
+
-  
+	\section usb_modules_registration Initial Steps: Driver Registration
-  In order to be able to start using the USB stack to communicate with your
+
-  devices, you will need to perform some actions. This section will outline
+	In order to be able to start using the USB stack to communicate with your
-  those actions and will point you to their appropriate locations. 
+	devices, you will need to perform some actions. This section will outline
-  
+	those actions and will point you to their appropriate locations. 
-  \note The code examples are based on the \c usb_hid driver written by
+
-    Jerome Duval. Have a look at this driver for a complete working example.
+	\note The code examples are based on the \c usb_hid driver written by
-
+		Jerome Duval. Have a look at this driver for a complete working
-  The following example gives an overview of the requirements to open the 
+		example.
-  USB module, and to start your driver registration in order to receive
+
-  connect and disconnect events. 
+	The following example gives an overview of the requirements to open the 
-  
+	USB module, and to start your driver registration in order to receive
-  \code
+	connect and disconnect events. 
-// Global variables and constants
+
-usb_module_info *gUsb;
+\code
-const char *kDriverName = "usb_hid";
+// Global variables and constants
-
+usb_module_info *gUsb;
-static usb_support_descriptor sSupportedDevices[1] = {
+const char *kDriverName = "usb_hid";
-	{ USB_HID_DEVICE_CLASS, 0, 0, 0, 0 },
+
-};
+static usb_support_descriptor sSupportedDevices[1] = {
-
+    { USB_HID_DEVICE_CLASS, 0, 0, 0, 0 },
-// Prototype for the hooks that are called when devices are added or removed
+};
-static status_t hid_device_added(const usb_device *dev, void **cookie);
+
-static status_t hid_device_removed(void *cookie);
+// Prototype for the hooks that are called when devices are added or removed
-
+static status_t hid_device_added(const usb_device *dev, void **cookie);
-static usb_notify_hooks sNotifyHooks = {
+static status_t hid_device_removed(void *cookie);
-	hid_device_added,
+
-	hid_device_removed
+static usb_notify_hooks sNotifyHooks = {
-};
+	hid_device_added,
-
+	hid_device_removed
-// Driver initialization, called by the kernel when the driver is loaded
+};
-status_t 
+
-init_driver(void)
+// Driver initialization, called by the kernel when the driver is loaded
-{
+status_t 
-	if (get_module(B_USB_MODULE_NAME, (module_info **)&gUsb) != B_OK)
+init_driver(void)
-		return B_ERROR;
+{
-
+    if (get_module(B_USB_MODULE_NAME, (module_info **)&gUsb) != B_OK)
-	gUsb->register_driver(kDriverName, sSupportedDevices, 
+        return B_ERROR;
-		1, NULL);
+
-	gUsb->install_notify(kDriverName, &sNotifyHooks);
+    gUsb->register_driver(kDriverName, sSupportedDevices, 
-
+        1, NULL);
-	return B_OK;
+    gUsb->install_notify(kDriverName, &sNotifyHooks);
-}
+
-  \endcode
+    return B_OK;
-  
+}
-  Basically, this boils down to three steps. The first step is to acquire the
+\endcode
-  usb_module_info module. This struct contains a set of function pointers that
+
-  you use to communicate with the stack. You can retrieve it like you would
+	Basically, this boils down to three steps. The first step is to acquire the
-  retrieve any other module.
+	usb_module_info module. This struct contains a set of function pointers that
-  
+	you use to communicate with the stack. You can retrieve it like you would
-  As soon as you have done that you can start registering your driver in the
+	retrieve any other module.
-  stack. What you do is you pass a unique identifier to identify your driver,
+
-  zero or more \link usb_support_descriptor support descriptors \endlink
+	As soon as you have done that you can start registering your driver in the
-  to provide the stack with information on which devices you support, and the
+	stack. What you do is you pass a unique identifier to identify your driver,
-  number of support descriptors you provided. The stack is very flexible with
+	zero or more \link usb_support_descriptor support descriptors \endlink
-  what patterns it accepts, so even the most complex driver will be able to
+	to provide the stack with information on which devices you support, and the
-  pass it's credentials. Have a look at the \c usb_support_descriptor struct
+	number of support descriptors you provided. The stack is very flexible with
-  and the \c usb_module_info::register_driver() call for all the details.
+	what patterns it accepts, so even the most complex driver will be able to
-  
+	pass it's credentials. Have a look at the \c usb_support_descriptor struct
-  The last step in initialization is to provide the stack with notification
+	and the \c usb_module_info::register_driver() call for all the details.
-  hooks. These are functions in your driver that the stack should call as soon
+
-  as a device is attached or removed. Please perform this call after your
+	The last step in initialization is to provide the stack with notification
-  internal driver data structures are initialized, because as soon as you
+	hooks. These are functions in your driver that the stack should call as soon
-  perform this call, the usb stack will start searching for already attached
+	as a device is attached or removed. Please perform this call after your
-  devices that match the credentials. Have a look at
+	internal driver data structures are initialized, because as soon as you
-  \c usb_module_info::install_notify() and the structure \c usb_notify_hooks
+	perform this call, the usb stack will start searching for already attached
-  for the details on the signatures of your hooks.
+	devices that match the credentials. Have a look at
-  
+	\c usb_module_info::install_notify() and the structure \c usb_notify_hooks
-  \section usb_modules_changes Handling Device Changes
+	for the details on the signatures of your hooks.
-  
+
-  The USB stack will notify you of device connects and disconnects when they
+	\section usb_modules_changes Handling Device Changes
-  occur. You will receive notifications as soon as you have supplied the hooks
+
-  to the stack, using \c usb_module_info::install_notify() . This section will
+	The USB stack will notify you of device connects and disconnects when they
-  explain some of the details when it comes to handling device changes.
+	occur. You will receive notifications as soon as you have supplied the hooks
-  
+	to the stack, using \c usb_module_info::install_notify() . This section will
-  When a device is added, your supplied usb_notify_hooks::device_added() hook
+	explain some of the details when it comes to handling device changes.
-  will be called if its credentials matches one of your support descriptors.
+
-  Because the stack runs through all the registered drivers, it could be that
+	When a device is added, your supplied usb_notify_hooks::device_added() hook
-  two or more drivers operate on the same device. The stack does not provide
+	will be called if its credentials matches one of your support descriptors.
-  a locking mechanism to prevent two conflicting drivers to get in each others
+	Because the stack runs through all the registered drivers, it could be that
-  way. It is up to the device maker to have supplied such a mechanism.
+	two or more drivers operate on the same device. The stack does not provide
-  
+	a locking mechanism to prevent two conflicting drivers to get in each others
-  \note In reality, it is very likely that your device will match at least one
+	way. It is up to the device maker to have supplied such a mechanism.
-    other driver, because Haiku supplies the \c usb_raw driver. This driver
+
-    provides userland access to the usb devices and therefore it has a blank
+	\note In reality, it is very likely that your device will match at least one
-    support descriptor that matches everything. The \c usb_raw driver will
+	other driver, because Haiku supplies the \c usb_raw driver. This driver
-    not conflict with your device interaction though (except when there is an
+	provides userland access to the usb devices and therefore it has a blank
-    userland application that tries to meddle with your device).
+	support descriptor that matches everything. The \c usb_raw driver will
-    
+	not conflict with your device interaction though (except when there is an
-  If your driver is willing to accept the supplied device, and your 
+	userland application that tries to meddle with your device).
-  device_added() hook returns B_OK, the USB stack will ask the kernel to reload
+
-  your published devices, so that your device is visible in userspace in the
+	If your driver is willing to accept the supplied device, and your 
-  \c /dev tree.
+	device_added() hook returns B_OK, the USB stack will ask the kernel to reload
-  
+	your published devices, so that your device is visible in userspace in the
-  The other event that the stack reports, device disconnection, should be
+	\c /dev tree.
-  handled by your \c usb_notify_hooks::device_removed() hook. Because "plug and
+
-  play" also means "unplug and leave", you should make sure your driver is 
+	The other event that the stack reports, device disconnection, should be
-  capable of cleaning up in the likely event that the user removes their
+	handled by your \c usb_notify_hooks::device_removed() hook. Because "plug and
-  device, even during transfers. In your hook function, you have the ability to
+	play" also means "unplug and leave", you should make sure your driver is 
-  do clean up whatever there is to clean up, however, make sure that you cancel
+	capable of cleaning up in the likely event that the user removes their
-  all the pending transfers. Use the usb_module_info::cancel_queued_transfers()
+	device, even during transfers. In your hook function, you have the ability to
-  call for that end. Also, don't forget to free the cookie you supplied in your
+	do clean up whatever there is to clean up, however, make sure that you cancel
-  device_added() hook. 
+	all the pending transfers. Use the usb_module_info::cancel_queued_transfers()
-  
+	call for that end. Also, don't forget to free the cookie you supplied in your
-  \section usb_modules_standard Standard USB Operations
+	device_added() hook. 
-  
+
-  One of the many conveniences of the Haiku USB API is the fact that many of
+	\section usb_modules_standard Standard USB Operations
-  the standard operations can be performed by simple function calls. As such,
+
-  you won't have to build many of the standard requests the USB specification
+	One of the many conveniences of the Haiku USB API is the fact that many of
-  defines by hand. This section will outline all the different conveniences and
+	the standard operations can be performed by simple function calls. As such,
-  will point you to where to look if you do need something more advanced.
+	you won't have to build many of the standard requests the USB specification
-  
+	defines by hand. This section will outline all the different conveniences and
-  \subsection usb_modules_standard_descriptors Configurations, Interfaces and Descriptors
+	will point you to where to look if you do need something more advanced.
-  
+
-  Many standard USB operations have to do with configurations, interfaces and
+	\subsection usb_modules_standard_descriptors Configurations, Interfaces and Descriptors
-  descriptors. All these operations are accessible by convenience functions.
+
-  
+	Many standard USB operations have to do with configurations, interfaces and
-  The device descriptor is one of the first things you will be interested in if
+	descriptors. All these operations are accessible by convenience functions.
-  you want to check out a device. The device descriptor can be retrieved quite
+
-  easily using the \c usb_module_info::get_device_descriptor() call. The
+	The device descriptor is one of the first things you will be interested in if
-  retrieved descriptor complies to the one dictated by the USB standard.
+	you want to check out a device. The device descriptor can be retrieved quite
-  
+	easily using the \c usb_module_info::get_device_descriptor() call. The
-  Also important are configurations. Since every device has at least one
+	retrieved descriptor complies to the one dictated by the USB standard.
-  configuration, you should be able to retrieve and manipulate configurations.
+
-  You can use \c usb_module_info::get_nth_configuration() to get them. To set
+	Also important are configurations. Since every device has at least one
-  a configuration, you should use \c usb_module_info::set_configuration(). To
+	configuration, you should be able to retrieve and manipulate configurations.
-  get the active configuration, use \c usb_module_info::get_configuration().
+	You can use \c usb_module_info::get_nth_configuration() to get them. To set
-  
+	a configuration, you should use \c usb_module_info::set_configuration(). To
-  \attention By default, Haiku's stack will set the configuration at offset
+	get the active configuration, use \c usb_module_info::get_configuration().
-    zero, which is according to the standard, the default configuration.
+
-    Do not rely on that if you first get the device, that the currently active
+	\attention By default, Haiku's stack will set the configuration at offset
-    configuration is the default configuration though. Another driver might
+	zero, which is according to the standard, the default configuration.
-    have manipulated this device already.
+	Do not rely on that if you first get the device, that the currently active
-  
+	configuration is the default configuration though. Another driver might
-  Every configuration has associated interfaces. To make life easier, the stack
+	have manipulated this device already.
-  automatically gets the interface descriptors (and their associated
+
-  endpoints), and stores them in the \c usb_configuration_info structure. This
+	Every configuration has associated interfaces. To make life easier, the stack
-  structure has a member called \link usb_configuration_info::interface
+	automatically gets the interface descriptors (and their associated
-  \c interface \endlink which is of the type \c usb_interface_list. That object
+	endpoints), and stores them in the \c usb_configuration_info structure. This
-  containts all the interfaces, including a pointer to the interface that is
+	structure has a member called \link usb_configuration_info::interface
-  currently active. Each interface is described as a \c usb_interface_info,
+	\c interface \endlink which is of the type \c usb_interface_list. That object
-  which is a container for the interface, its associated endpoints and any
+	containts all the interfaces, including a pointer to the interface that is
-  unparsed descriptors. In order to change the active interface, you can use
+	currently active. Each interface is described as a \c usb_interface_info,
-  the stack's \c usb_module_info::set_alt_interface() call. 
+	which is a container for the interface, its associated endpoints and any
-  
+	unparsed descriptors. In order to change the active interface, you can use
-  Endpoints, the basic units with which you can communicate, are stored as
+	the stack's \c usb_module_info::set_alt_interface() call. 
-  \c usb_endpoint_info structures. Each of these structures carries the actual
+
-  endpoint descriptor, and the accompanying usb_pipe handle that you can use to
+	Endpoints, the basic units with which you can communicate, are stored as
-  actually send and receive data.
+	\c usb_endpoint_info structures. Each of these structures carries the actual
-  
+	endpoint descriptor, and the accompanying usb_pipe handle that you can use to
-  The last point of interest are descriptors. As you have seen, Haiku caches
+	actually send and receive data.
-  all the relevant descriptors itself, however, you might want to retrieve any
+
-  other type of descriptor that could be relevant for your device. The
+	The last point of interest are descriptors. As you have seen, Haiku caches
-  convenience function to use in such a case is the 
+	all the relevant descriptors itself, however, you might want to retrieve any
-  \c usb_module_info::get_descriptor() call. This function takes all the
+	other type of descriptor that could be relevant for your device. The
-  parameters needed to build the actual descriptor, and performs the request
+	convenience function to use in such a case is the 
-  over the default control pipe.
+	\c usb_module_info::get_descriptor() call. This function takes all the
-  
+	parameters needed to build the actual descriptor, and performs the request
-  \subsection usb_modules_standard_features Features
+	over the default control pipe.
-  
+
-  Another one of the building blocks of USB are features. Every device should
+	\subsection usb_modules_standard_features Features
-  provide for a number of standard features, but the USB specification also
+
-  leaves the option to using custom device specific features. Feature requests
+	Another one of the building blocks of USB are features. Every device should
-  can be performed on devices, interfaces and pipes (which are tied to
+	provide for a number of standard features, but the USB specification also
-  endpoints). 
+	leaves the option to using custom device specific features. Feature requests
-  
+	can be performed on devices, interfaces and pipes (which are tied to
-  To set a feature, you can use the \c usb_module_info::set_feature() call. To
+	endpoints). 
-  clear a feature, use the \c usb_module_info::clear_feature() call. One of the
+
-  most used feature calls is the call to clear a \c USB_FEATURE_ENDPOINT_HALT .
+	To set a feature, you can use the \c usb_module_info::set_feature() call. To
-  
+	clear a feature, use the \c usb_module_info::clear_feature() call. One of the
-  \subsection usb_modules_standard_other Other Standard Calls
+	most used feature calls is the call to clear a \c USB_FEATURE_ENDPOINT_HALT .
-  
+
-  To get the status of a device, an interface or an endpoint, you can use the
+	\subsection usb_modules_standard_other Other Standard Calls
-  \c usb_module_info::get_status() call.
+
-  
+	To get the status of a device, an interface or an endpoint, you can use the
-  If you are using isochronous transfers, you can use the
+	\c usb_module_info::get_status() call.
-  \c usb_module_info::set_pipe_policy() to set the properties of the
+
-  isochronous pipe. 
+	If you are using isochronous transfers, you can use the
-  
+	\c usb_module_info::set_pipe_policy() to set the properties of the
-  \section usb_modules_transfers Data Transfers
+	isochronous pipe. 
-  
+
-  Transfering data is one of the basic building blocks of the USB protocol.
+	\section usb_modules_transfers Data Transfers
-  This section will demonstrate how to perform transfers via the four different
+
-  protocols the USB stack offers.
+	Transfering data is one of the basic building blocks of the USB protocol.
-  
+	This section will demonstrate how to perform transfers via the four different
-  But first it is essential to show how to perform the transfers using the
+	protocols the USB stack offers.
-  \c usb_module_info interface. The interface provides five \c queue_*
+
-  functions, with the asterix being one of the following: \c bulk, \c bulk_v
+	But first it is essential to show how to perform the transfers using the
-  (bulk transfers using a vector), \c interrupt, \c isochronous or \c request
+	\c usb_module_info interface. The interface provides five \c queue_*
-  (over the standard control pipe). These five functions work asynchronously,
+	functions, with the asterix being one of the following: \c bulk, \c bulk_v
-  which means that your driver is called back from a different thread when your
+	(bulk transfers using a vector), \c interrupt, \c isochronous or \c request
-  transfer is finished. 
+	(over the standard control pipe). These five functions work asynchronously,
-  
+	which means that your driver is called back from a different thread when your
-  The five functions share some arguments. The first argument is always the
+	transfer is finished. 
-  pipe that is associated with the endpoint (except for control transfers,
+
-  these only work on the device in general). All of the functions accept a data
+	The five functions share some arguments. The first argument is always the
-  buffer, and the length of that   buffer. All of the functions require a
+	pipe that is associated with the endpoint (except for control transfers,
-  \c #usb_callback_func, a function in your driver that can be called in case a
+	these only work on the device in general). All of the functions accept a data
-  transfer is finished. The functions also require a cookie that is provided to
+	buffer, and the length of that   buffer. All of the functions require a
-  the callback function. 
+	\c #usb_callback_func, a function in your driver that can be called in case a
-  
+	transfer is finished. The functions also require a cookie that is provided to
-  The working order is as follows: first you queue a transfer, then you handle
+	the callback function. 
-  the result in the callback function when it's done. The callback function
+
-  will be called with a \a status argument, in which you can check whether or
+	The working order is as follows: first you queue a transfer, then you handle
-  not the transfer actually succeeded. See this \link #usb_callback_func 
+	the result in the callback function when it's done. The callback function
-  description \endlink for how your callback function should behave and what
+	will be called with a \a status argument, in which you can check whether or
-  kind of status there might have been.
+	not the transfer actually succeeded. See this \link #usb_callback_func 
-  
+	description \endlink for how your callback function should behave and what
-  Finally, before going into the different transfer types, a note on buffer
+	kind of status there might have been.
-  ownership. The usb stack keeps the internal buffers tidy, but the buffer you
+
-  provide to the \c queue_* functions are yours. You are responsible for
+	Finally, before going into the different transfer types, a note on buffer
-  allocating and freeing them, and you may do with them whatever you like,
+	ownership. The usb stack keeps the internal buffers tidy, but the buffer you
-  \e except between queueing your transfer and the callback. During that period
+	provide to the \c queue_* functions are yours. You are responsible for
-  you should consider the USB stack the owner of the buffer.
+	allocating and freeing them, and you may do with them whatever you like,
-  
+	\e except between queueing your transfer and the callback. During that period
-  \subsection usb_modules_transfers_control Control Requests
+	you should consider the USB stack the owner of the buffer.
-  
+
-  Control requests are done over the device wide control pipe which is provided
+	\subsection usb_modules_transfers_control Control Requests
-  by every device. Haiku's stack has two functions that you can use to perform
+
-  custom requests (opposed to many of the \ref usb_modules_standard
+	Control requests are done over the device wide control pipe which is provided
-  "standard operations"). Control transfers are the only transfers that you can
+	by every device. Haiku's stack has two functions that you can use to perform
-  perform synchronously as well as asynchronously. The functions you can use
+	custom requests (opposed to many of the \ref usb_modules_standard
-  are \c usb_module_info::send_request() for synchronous requests and
+	"standard operations"). Control transfers are the only transfers that you can
-  \c usb_module_info::queue_request() for asynchronous requests. 
+	perform synchronously as well as asynchronously. The functions you can use
-  
+	are \c usb_module_info::send_request() for synchronous requests and
-  Many of the constants that you should use when performing can be found in
+	\c usb_module_info::queue_request() for asynchronous requests. 
-  the USB_spec.h file which is automatically included if you include the main
+
-  USB header. Have a look of how to use these constants in the following
+	Many of the constants that you should use when performing can be found in
-  example:
+	the USB_spec.h file which is automatically included if you include the main
-  
+	USB header. Have a look of how to use these constants in the following
-  \code
+	example:
-  // Send a request that is defined by the standard of this class. We retrieve
+
-  // a report from the device on one of its interfaces.
+\code
-  // This request is specified by the HID specification.
+    // Send a request that is defined by the standard of this class. We retrieve
-  
+    // a report from the device on one of its interfaces.
-	status = usb->send_request(dev,
+    // This request is specified by the HID specification.
-		USB_REQTYPE_INTERFACE_IN | USB_REQTYPE_CLASS,
+
-		USB_REQUEST_HID_GET_REPORT,
+    status = usb->send_request(dev,
-		0x0100 | report_id, interfaceNumber, device->total_report_size,
+        USB_REQTYPE_INTERFACE_IN | USB_REQTYPE_CLASS,
-		device->buffer, &actual);
+        USB_REQUEST_HID_GET_REPORT, 0x0100 | report_id,
-  \endcode
+        interfaceNumber, device->total_report_size,
-  
+        device->buffer, &actual);
-  \warning Both the \link usb_module_info::send_request() \a send_request()
+\endcode
-    \endlink and \link usb_module_info::queue_request() \a queue_request()
+
-    \endlink functions can be used to perform standard usb requests. Avoid
+	\warning Both the \link usb_module_info::send_request() \a send_request()
-    low-level operations, because the stack needs to keep its internal
+	\endlink and \link usb_module_info::queue_request() \a queue_request()
-    data structures consistent. If you need to perform one of the 
+	\endlink functions can be used to perform standard usb requests. Avoid
-    \ref usb_modules_standard "standard operations", use the provided
+	low-level operations, because the stack needs to keep its internal
-    convenience functions.
+	data structures consistent. If you need to perform one of the 
-  
+	\ref usb_modules_standard "standard operations", use the provided
-  \subsection usb_modules_transfers_interrupt Interrupt
+	convenience functions.
-  
+
-  Interrupt transfers apply to endpoints that receive data, or that can be
+	\subsection usb_modules_transfers_interrupt Interrupt
-  polled in several instances of time. The intervals are determined by the
+
-  endpoint descriptor.
+	Interrupt transfers apply to endpoints that receive data, or that can be
-  
+	polled in several instances of time. The intervals are determined by the
-  To schedule a transfer, use usb_module_info::queue_interrupt(). You only have
+	endpoint descriptor.
-  to supply a buffer, the stack schedule the transfer in such a way that it
+
-  will be performed within a certain timeframe. To create a continuous
+	To schedule a transfer, use usb_module_info::queue_interrupt(). You only have
-  interrupt system, you should queue the next transfer in the callback function
+	to supply a buffer, the stack schedule the transfer in such a way that it
-  of the previous. The stack will make sure that the new transfer will be
+	will be performed within a certain timeframe. To create a continuous
-  performed exactly after the required interval. 
+	interrupt system, you should queue the next transfer in the callback function
-  
+	of the previous. The stack will make sure that the new transfer will be
-  \subsection usb_modules_transfers_bulk Bulk
+	performed exactly after the required interval. 
-  
+
-  Bulk transfers are very similar to control transfers. They will be performed
+	\subsection usb_modules_transfers_bulk Bulk
-  as soon as possible without stalling other transfers, and they transfer data.
+
-  Bulk transfers are designed to transfer up to large amounts of data as
+	Bulk transfers are very similar to control transfers. They will be performed
-  efficiently as possible. Performing bulk transfers isn't difficult, you
+	as soon as possible without stalling other transfers, and they transfer data.
-  merely supply a buffer and the endpoint that should execute the request, and
+	Bulk transfers are designed to transfer up to large amounts of data as
-  you're set. 
+	efficiently as possible. Performing bulk transfers isn't difficult, you
-  
+	merely supply a buffer and the endpoint that should execute the request, and
-  Bulk transfers come in two flavours. The first is 
+	you're set. 
-  usb_module_info::queue_bulk(), which takes a standard data buffer. The second
+
-  flavour is the usb_module_info::queue_bulk_v() function, which is designed to
+	Bulk transfers come in two flavours. The first is 
-  operate on (an array of) POSIX vectors. These functions only differ in the
+	usb_module_info::queue_bulk(), which takes a standard data buffer. The second
-  buffer they accept, they function in exactly the same way.
+	flavour is the usb_module_info::queue_bulk_v() function, which is designed to
-  
+	operate on (an array of) POSIX vectors. These functions only differ in the
-  \subsection usb_modules_transfers_isochronous Isochronous
+	buffer they accept, they function in exactly the same way.
-  
+
-  Isochronous transfers are not implemented on Haiku yet. As soon as they are,
+	\subsection usb_modules_transfers_isochronous Isochronous
-  this section should contain information on how to queue them.
+
-  
+	Isochronous transfers are not implemented on Haiku yet. As soon as they are,
-  \section usb_modules_cleanup Cleaning Up
+	this section should contain information on how to queue them.
-  
+
-  This section describes how to gracefully leave the stack after your driver is
+	\section usb_modules_cleanup Cleaning Up
-  requested to shut down.
+
-  
+	This section describes how to gracefully leave the stack after your driver is
-  There are truely only two simple actions to perform. The first is to
+	requested to shut down.
-  uninstall your notification hooks, using 
+
-  \c usb_module_info::uninstall_notify(). The second action is to 'put' the
+	There are truely only two simple actions to perform. The first is to
-  module.
+	uninstall your notification hooks, using 
-  
+	\c usb_module_info::uninstall_notify(). The second action is to 'put' the
-  \code
+	module.
-void
+
-uninit_driver(void)
+\code
-{
+void
-	usb->uninstall_notify(kDriverName);
+uninit_driver(void)
-
+{
-	put_module(B_USB_MODULE_NAME);
+    usb->uninstall_notify(kDriverName);
-}
+    put_module(B_USB_MODULE_NAME);
-  \endcode
+}
-
+\endcode
-  \section usb_modules_resources More Resources
+
-  
+	\section usb_modules_resources More Resources
-  This section should list more resources on the web.
+
-*/
+	This section should list more resources on the web.
+*/

docs/user/game/DirectWindow.dox

@@ -13,30 +13,38 @@
 
 /*!
 	\file DirectWindow.h
+	\ingroup game
+	\ingroup libbe
 	\brief Provides the DirectWindow class.
 */
 
 
 /*!
 	\enum direct_buffer_state
+
 	Direct buffer state constants
 */
 
 
 /*!
 	\enum direct_driver_state
+
 	Direct driver state constants
 */
 
 
 /*!
 	\struct direct_buffer_info
+	\ingroup game
+	\ingroup libbe
+
 	Direct butter info struct
 */
 
 
 /*!
 	\var direct_buffer_info::buffer_state
+
 	State of the direct buffer access privileges.
 	It can have one of the following values:
 	- \c B_DIRECT_MODE_MASK
@@ -52,81 +60,103 @@
 
 /*!
 	\var direct_buffer_info::driver_state
+
 	State of the graphics card on which your direct window is displayed.
 	There are two possible values:
-	- \c B_MODE_CHANGED The resolution or color depth has changed.
+		- \c B_MODE_CHANGED The resolution or color depth has changed.
-	- \c B_DRIVER_CHANGED The window was moved onto another monitor.
+		- \c B_DRIVER_CHANGED The window was moved onto another monitor.
 */
 
 
 /*!
 	\var direct_buffer_info::bits
+
 	Pointer to the frame buffer in your team's memory space.
 */
 
 
 /*!
 	\var direct_buffer_info::pci_bits
+
 	Pointer to the frame buffer in the PCI memory space. This value is
 	typically needed to control DMA.
 */
 
 /*!
 	\var direct_buffer_info::bytes_per_row
+
 	Number of bytes used to represent a single row of pixels in the frame buffer.
 */
 
 
 /*!
 	\var direct_buffer_info::bits_per_pixel
-	number of bits actually used to store a single pixel, including reserved,
+
+	Number of bits actually used to store a single pixel, including reserved,
 	unused, or alpha channel bits. This value is usually a multiple of eight.
 */
 
 
 /*!
 	\var direct_buffer_info::pixel_format
+
 	The format used to encode a pixel as defined by the \c color_space type.
 */
 
+
 /*!
 	\var direct_buffer_info::layout
+
 	Reserved for future use.
 */
 
+
 /*!
 	\var direct_buffer_info::orientation
+
 	Reserved for future use.
 */
 
+
 /*!
 	\var direct_buffer_info::_reserved[9]
+
 	Reserved for future use.
 */
 
+
 /*!
 	\var direct_buffer_info::_dd_type_
+
 	Reserved for future use.
 */
 
+
 /*!
 	\var direct_buffer_info::_dd_token_
+
 	Reserved for future use.
 */
 
+
 /*!
 	\var direct_buffer_info::clip_list_count
+
 	Number of rectangles in \c clip_list.
 */
 
+
 /*!
 	\var direct_buffer_info::window_bounds
+
 	Rectangle that defines the full content area of the window in screen
 	coordinates.
 */
 
+
 /*!
 	\var direct_buffer_info::clip_bounds
+
 	Bounding rectangle of the visible part of the content area of the window
 	in screen coordinates.
 */
@@ -134,6 +164,7 @@
 
 /*!
 	\var direct_buffer_info::clip_list
+
 	List of rectangles that together define the visible region of the content
 	area of the window in screen coordinates.
 */

docs/user/game/FileGameSound.dox

@@ -13,6 +13,8 @@
 
 /*!
 	\file FileGameSound.h
+	\ingroup game
+	\ingroup libbe
 	\brief Provides the BFileGameSound class.
 */
 

docs/user/game/GameProducer.dox

@@ -5,8 +5,10 @@
  * Authors:
  *		Christopher ML Zumwalt May, [email protected]
  *		Omri Barak
+ *
  * Proofreaders:
  *		John Scipione, [email protected]
+ *
  * Corresponds to:
  *		src/kits/game/GameProducer.h    rev 43514
  *		src/kits/game/GameProducer.cpp  rev 43514
@@ -15,6 +17,8 @@
 
 /*!
 	\file GameProducer.h
+	\ingroup game
+	\ingroup libbe
 	\brief Provides the GameProducer class.
 */
 

docs/user/interface/AbstractLayout.dox

@@ -1,3 +1,16 @@
+/*
+ * Copyright 2010 Haiku, Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		Alex Wilson, [email protected]
+ * 
+ * Corresponds to:
+ *		headers/os/interface/AbstractLayout.h	rev 39055
+ *		src/kits/inteface/AbstractLayout.cpp	rev 39055
+ */
+
+
 /*!
 	\class BAbstractLayout
 	\ingroup interface
@@ -6,7 +19,7 @@
 
 	\brief BLayout subclass providing convenience methods for derived
 	implementations.
-	
+
 	This class is designed to reduce the amount of boilerplate code required to
 	write a BLayout subclass. In most cases, you classes should derive from
 	BAbstractLayout rather than BLayout.

docs/user/interface/Alert.dox

@@ -1,9 +1,10 @@
 /*
- * Copyright 2011, Haiku inc.
+ * Copyright 2011 Haiku Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
- *		John Scipione <[email protected]>
+ *		John Scipione, [email protected]
+ *
  * Corresponds to:
  *		/trunk/headers/os/interface/Alert.h	 rev 42274
  *		/trunk/src/kits/interface/Alert.cpp	 rev 42274
@@ -12,12 +13,16 @@
 
 /*!
 	\file Alert.h
+	\ingroup interface
+	\ingroup libbe
 	\brief BAlert class definition and support enums.
 */
 
 
 /*!
 	\enum alert_type
+	\ingroup interface
+
 	Determines which icon (if any) is displayed in the alert dialog.
 	Choose one option. If the constructor doesn't include an
 	alert_type argument than \c B_EMPTY_ALERT is used.
@@ -25,35 +30,46 @@
 
 /*!
 	\var alert_type B_EMPTY_ALERT
+
 	No icon
 */
 
 /*!
 	\var alert_type B_INFO_ALERT
+
 	\image html http://api.haiku-os.org/images/alert_info_32.png
+
 	Info icon
 */
 
 /*!
 	\var alert_type B_IDEA_ALERT
+
 	\image html http://api.haiku-os.org/images/alert_idea_32.png
+
 	Idea icon
 */
 
 /*!
 	\var alert_type B_WARNING_ALERT
+
 	\image html http://api.haiku-os.org/images/alert_warning_32.png
+
 	Warning icon
 */
 
 /*!
 	\var alert_type B_STOP_ALERT
+
 	\image html http://api.haiku-os.org/images/alert_stop_32.png
+
 	Stop icon
 */
 
 /*!
 	\enum button_spacing
+	\ingroup interface
+
 	Determines how the buttons on the alert dialog are spaced relative
 	to each other. Choose one option. If the constructor doesn't include a
 	button_spacing argument than \c B_EVEN_SPACING is used.
@@ -61,12 +77,14 @@
 
 /*!
 	\var button_spacing B_EVEN_SPACING
+
 	If the alert dialog has more than one button than the buttons are
 	spaced evenly across the bottom of the alert dialog.
 */
 
 /*!
 	\var button_spacing B_OFFSET_SPACING
+
 	If the alert dialog has more than one button than the leftmost button
 	is offset to the left-hand side of the dialog while the rest of the
 	buttons are grouped on the right. This is useful to separate off a
@@ -104,13 +122,13 @@
 	The code used to create and display an alert dialog like the one shown
 	above is shown below:
 
-	\code
+\code
 BAlert* alert = new BAlert("Close and save dialog", "Save changes to...",
-	"Cancel", "Don't save", "Save", B_WIDTH_AS_USUAL, B_OFFSET_SPACING,
+    "Cancel", "Don't save", "Save", B_WIDTH_AS_USUAL, B_OFFSET_SPACING,
-	B_WARNING_ALERT);
+    B_WARNING_ALERT);
 alert->SetShortcut(0, B_ESCAPE);
 int32 button_index = alert->Go();
-	\endcode
+\endcode
 
 	The messaged displayed in the dialog window along with the button labels
 	are set by the strings in the contructor. The Cancel button is offset to

docs/user/interface/Bitmap.dox

@@ -1,17 +1,21 @@
 /*
- * Copyright 2011, Haiku inc.
+ * Copyright 2011 Haiku Inc. All rights reserved.
- * Distributed under the terms of the MIT Licence.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		Axel Dörfler, [email protected]
+ *		John Scipione, [email protected]
  *
- * Documentation by:
- *		Axel Dörfler <[email protected]>
- *		John Scipione <[email protected]>
  * Corresponds to:
  *		/trunk/headers/os/interface/Bitmap.h	 rev 42274
  *		/trunk/src/kits/interface/Bitmap.cpp	 rev 42274
  */
 
+
 /*!
 	\file Bitmap.h
+	\ingroup interface
+	\ingroup libbe
 	\brief Defines the BBitmap class and global operators and functions for
 		handling bitmaps.
 */
@@ -34,10 +38,11 @@
 
 	An example of creating a new 32x32 pixel BBitmap object and assigning the
 	icon of the current application looks like this:
-	\code
+
+\code
 BBitmap iconBitmap = new BBitmap(BRect(0, 0, 31, 31), B_RGBA32));
 appFileInfo.GetIcon(iconBitmap, B_LARGE_ICON);
-	\endcode
+\endcode
 
 	You can access the properties of a bitmap by calling the Bounds(),
 	Flags(), ColorSpace(), Area(), Bits(), BitsLength(), BytesPerRow(),

docs/user/interface/Box.dox

@@ -1,11 +1,12 @@
 /*
- * Copyright 2010, Haiku inc.
+ * Copyright 2011 Haiku Inc. All rights reserved.
- * Distributed under the terms of the MIT Licence.
+ * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
  *		Clark Gaeble
  *		Adrien Destugues <[email protected]>
  *		John Scipione <[email protected]>
+ *
  * Corresponds to:
  *		/trunk/headers/os/interface/Box.h	 rev 42274
  *		/trunk/src/kits/interface/Box.cpp	 rev 42274
@@ -13,6 +14,8 @@
 
 /*!
 	\file Box.h
+	\ingroup interface
+	\ingroup libbe
 	\brief Defines the BBox class
 */
 
@@ -20,6 +23,7 @@
 /*!
 	\class BBox
 	\ingroup interface
+	\ingroup libbe
 	\brief A rectangular view with a border and an optional label to group
 		related subviews visually.
 

docs/user/interface/Button.dox

@@ -1,9 +1,10 @@
 /*
- * Copyright 2011, Haiku inc.
+ * Copyright 2011 Haiku Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
  *		John Scipione, [email protected]
+ *
  * Corresponds to:
  *		/trunk/headers/os/interface/Button.h	 rev 42794
  *		/trunk/src/kits/interface/Button.cpp	 rev 42794
@@ -11,6 +12,8 @@
 
 /*!
 	\file Button.h
+	\ingroup interface
+	\ingroup libbe
 	\brief Describes the BButton class.
 */
 
@@ -18,6 +21,7 @@
 /*!
 	\class BButton Button.h
 	\ingroup interface
+	\ingroup libbe
 	\brief A BButton is a labeled on-screen button.
 
 	A BButton control is used to initiate an action. An action is activated
@@ -29,8 +33,8 @@
 
 	A BButton, unlike other user interface elements such as check boxes and
 	radio buttons has only a single state. During a click event the
-	BButton's value is set to \c 1, (\c B_CONTROL_ON) otherwise this value
+	BButton's value is set to 1, (\c B_CONTROL_ON) otherwise this value
-	is \c 0 (\c B_CONTROL_OFF).
+	is 0 (\c B_CONTROL_OFF).
 
 	BButton inherits from the BControl class.
 */

docs/user/interface/CheckBox.dox

@@ -1,18 +1,22 @@
 /*
- * Copyright 2011, Haiku inc.
+ * Copyright 2011 Haiku Inc. All rights reserved.
- * Distributed under the terms of the MIT Licence.
+ * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
  *		Stephan Aßmus, [email protected]
  *		Marc Flerackers, [email protected]
  *		John Scipione, [email protected]
+ *
  * Corresponds to:
  *		/trunk/headers/os/interface/CheckBox.h	 rev 42794
  *		/trunk/src/kits/interface/CheckBox.cpp	 rev 42794
  */
 
+
 /*!
 	\file CheckBox.h
+	\ingroup interface
+	\ingroup libbe
 	\brief Defines the BCheckBox class
 */
 

docs/user/interface/ColorControl.dox

@@ -1,9 +1,10 @@
 /*
- * Copyright 2011, Haiku inc.
+ * Copyright 2011 Haiku Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
  *		John Scipione, [email protected]
+ *
  * Corresponds to:
  *		/trunk/headers/os/interface/ColorControl.h	 rev 42794
  *		/trunk/src/kits/interface/ColorControl.cpp	 rev 42794
@@ -12,37 +13,47 @@
 
 /*!
 	\file ColorControl.h
+	\ingroup interface
+	\ingroup libbe
 	\brief BColorControl class definition and support enums.
 */
 
 
-/*! \enum color_control_layout
+/*!
+	\enum color_control_layout
+	\ingroup interface
+
 	Enumeration of the color control layout options.
 */
 
 /*!
 	\var color_control_layout B_CELLS_4x64
-	cells are arranged in 4 columns, 64 rows.
+
+	Cells are arranged in 4 columns, 64 rows.
 */
 
 /*!
 	\var color_control_layout B_CELLS_8x32
-	cells are arranged in 8 columns, 32 rows.
+
+	Cells are arranged in 8 columns, 32 rows.
 */
 
 /*!
 	\var color_control_layout B_CELLS_16x16
-	cells are arranged in 16 columns, 16 rows.
+
+	Cells are arranged in 16 columns, 16 rows.
 */
 
 /*!
 	\var color_control_layout B_CELLS_32x8
-	cells are arranged in 32 columns, 8 rows.
+
+	Cells are arranged in 32 columns, 8 rows.
 */
 
 /*!
 	\var color_control_layout B_CELLS_64x4
-	cells are arranged in 64 columns, 4 rows.
+
+	Cells are arranged in 64 columns, 4 rows.
 */
 
 
@@ -64,7 +75,7 @@
 	An example of creating a color control looks like this:
 \code
 colorControl = new BColorControl(BPoint(0, 0), B_CELLS_32x8, 7.0,
-	"ColorControl", new BMessage(kValueChanged));
+    "ColorControl", new BMessage(kValueChanged));
 colorControl->SetValue(0x336698);
 \endcode
 

docs/user/interface/Control.dox

@@ -1,29 +1,35 @@
 /*
- * Copyright 2011, Haiku inc.
+ * Copyright 2011 Haiku Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
  *		John Scipione, [email protected]
+ *
  * Corresponds to:
  *		/trunk/headers/os/interface/Control.h	 rev 42794
  *		/trunk/src/kits/interface/Control.cpp	 rev 42794
  */
 
+
 /*!
 	\file Control.h
+	\ingroup interface
+	\ingroup libbe
 	\brief BControl class definition and support enums.
 */
 
 
 /*!
 	\var B_CONTROL_ON
-	Control on
+
+	Control on. Value equal to 1.
 */
 
 
 /*!
 	\var B_CONTROL_OFF
-	Control off
+
+	Control off. Value equal to 0.
 */
 
 

docs/user/interface/Dragger.dox

@@ -1,8 +1,8 @@
 /*
- * Copyright 2012 Haiku inc.
+ * Copyright 2011 Haiku Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
  *		John Scipione, [email protected]
  *
  * Corresponds to:
@@ -12,6 +12,8 @@
 
 /*!
 	\file Dragger.h
+	\ingroup interface
+	\ingroup libbe
 	\brief Provides the BDragger class.
 */
 

docs/user/interface/Font.dox

@@ -1,9 +1,10 @@
 /*
- * Copyright 2013 Haiku inc.
+ * Copyright 2013 Haiku Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
- *		John Scipione <[email protected]>
+ *		John Scipione, [email protected]
+ *
  * Corresponds to:
  *		/trunk/headers/os/interface/Font.h	 hrev45178
  *		/trunk/src/kits/interface/Font.cpp	 hrev45178
@@ -12,6 +13,8 @@
 
 /*!
 	\file Font.h
+	\ingroup interface
+	\ingroup libbe
 	\brief BFont class definition, unicode_block class definition, and
 		font-related struct and enum definitions.
 */
@@ -19,12 +22,14 @@
 
 /*!
 	\var B_CHAR_SPACING
+
 	Position each character without adjustment. Best mode for printing.
 */
 
 
 /*!
 	\var B_STRING_SPACING
+
 	Optimizes the position of each character within it's space. Collisions
 	are unlikely but characters may touch each other. Best mode to use when
 	the screen needs to match what appears on the printed page.
@@ -33,6 +38,7 @@
 
 /*!
 	\var B_BITMAP_SPACING
+
 	The widths of the characters are chosen so that they never collide and
 	rarely touch. Best mode for drawing small amounts of text.
 */
@@ -40,225 +46,265 @@
 
 /*!
 	\var B_FIXED_SPACING
+
 	Positions characters at a constant width. Best mode for fixed-width fonts.
 */
 
 
 /*!
 	\enum font_direction
+	\ingroup interface
+
 	Determines the direction of the text rendered by the font,
 	left-to-right or right-to-left.
 */
 
 /*!
 	\var font_direction B_FONT_LEFT_TO_RIGHT
+
 	Left to right.
 */
 
 /*!
 	\var font_direction B_FONT_RIGHT_TO_LEFT
+
 	Right to left.
 */
 
 
 /*!
 	\var B_DISABLE_ANTIALIASING
+
 	Disable antialiasing. Used by BFont::Flags() and BFont::SetFlags().
 */
 
 
 /*!
 	\var B_FORCE_ANTIALIASING
+
 	Force antialiasing. Used by BFont::Flags() and BFont::SetFlags().
 */
 
 
 /*!
 	\var B_TRUNCATE_END
+
 	Truncate from the end of the string.
 */
 
 
 /*!
 	\var B_TRUNCATE_BEGINNING
+
 	Truncate from the beginning of the string.
 */
 
 
 /*!
 	\var B_TRUNCATE_MIDDLE
+
 	Truncate from the middle of the string.
 */
 
 
 /*!
 	\var B_TRUNCATE_SMART
+
 	Truncate while keeping each string unique.
 */
 
 
 /*!
 	\var B_UNICODE_UTF8
+
 	UTF-8 font encoding.
 */
 
 
 /*!
 	\var B_ISO_8859_1
+
 	ISO 8859-1 aka Latin 1 "Western European" font encoding.
 */
 
 
 /*!
 	\var B_ISO_8859_2
+
 	ISO 8859-2 aka Latin 2 "Eastern European" font encoding.
 */
 
 
 /*!
 	\var B_ISO_8859_3
+
 	ISO 8859-3 aka Latin 3 "South European" font encoding.
 */
 
 
 /*!
 	\var B_ISO_8859_4
+
 	ISO 8859-4 aka Latin 4 "Northern European" font encoding.
 */
 
 
 /*!
 	\var B_ISO_8859_5
+
 	ISO 8859-5 "Latin/Cyrillic" font encoding.
 */
 
 
 /*!
 	\var B_ISO_8859_6
+
 	ISO 8859-6 "Latin/Arabic" font encoding.
 */
 
 
 /*!
 	\var B_ISO_8859_7
+
 	ISO 8859-7 "Latin/Greek" font encoding.
 */
 
 
 /*!
 	\var B_ISO_8859_8
+
 	ISO 8859-8 "Latin/Hebrew" font encoding.
 */
 
 
 /*!
 	\var B_ISO_8859_9
+
 	ISO 8859-9 aka Latin 5 "Latin/Turkish" font encoding.
 */
 
 
 /*!
 	\var B_ISO_8859_10
+
 	ISO 8859-10 aka Latin 6 "Nordic" font encoding.
 */
 
 
 /*!
 	\var B_MACINTOSH_ROMAN
+
 	Macintosh Roman font encoding.
 */
 
 
 /*!
 	\var B_HAS_TUNED_FONT
-	flags for get_font_family() and get_font_style()
+
+	Flags for get_font_family() and get_font_style()
 */
 
 
 /*!
 	\var B_IS_FIXED
+
 	flags for get_font_family() and get_font_style()
 */
 
 
 /*!
 	\var B_ITALIC_FACE
+
 	Italic font face flag.
 */
 
 
 /*!
 	\var B_UNDERSCORE_FACE
+
 	Underscore font face flag.
 */
 
 
 /*!
 	\var B_NEGATIVE_FACE
+
 	Negative font face flag.
 */
 
 
 /*!
 	\var B_OUTLINED_FACE
+
 	Outline font face flag.
 */
 
 
 /*!
 	\var B_STRIKEOUT_FACE
+
 	Strikeout font face flag.
 */
 
 
 /*!
 	\var B_BOLD_FACE
+
 	Bold font face flag.
 */
 
 
 /*!
 	\var B_REGULAR_FACE
+
 	Regular font face flag.
 */
 
 
 /*!
 	\var B_CONDENSED_FACE
+
 	Condensed font face flag. Not in BeOS 5.
 */
 
 
 /*!
 	\var B_LIGHT_FACE
+
 	Light font face flag. Not in BeOS 5.
 */
 
 
 /*!
 	\var B_HEAVY_FACE
+
 	Heavy font face flag. Not in BeOS 5.
 */
 
 
 /*!
 	\enum font_metric_mode
+
 	Font metric mode, screen or printing.
 */
 
 /*!
 	\var font_metric_mode B_SCREEN_METRIC
+
 	Screen font metric mode.
 */
 
 /*!
 	\var font_metric_mode B_PRINTING_METRIC
+
 	Printing font metric mode.
 */
 
 
 /*!
 	\enum font_file_format
+	\ingroup interface
+
 	Font file format, TrueType™ or PostScript™ Type1.
 
 	\see BFont::FileFormat()
@@ -266,17 +312,21 @@
 
 /*!
 	\var font_file_format B_TRUETYPE_WINDOWS
+
 	TrueType™ font file format.
 */
 
 /*!
 	\var font_file_format B_POSTSCRIPT_TYPE1_WINDOWS
+
 	PostScript™ Type1 font file format.
 */
 
 
 /*!
 	\class unicode_block
+	\ingroup interface
+	\ingroup libbe
 	\brief Describes the blocks of Unicode characters supported by a font.
 
 	\see BFont::Blocks()
@@ -392,6 +442,8 @@
 
 /*!
 	\struct edge_info
+	\ingroup interface
+	\ingroup libbe
 	\brief The distance that a character outline is inset from its escapement
 		boundaries.
 
@@ -404,20 +456,24 @@
 
 /*!
 	\var edge_info::left
-	\brief The distance that the character outline is inset from the left
+
-		escapement boundary.
+	The distance that the character outline is inset from the left
+	escapement boundary.
 */
 
 
 /*!
 	\var edge_info::right
-	\brief The distance that the character outline is inset from the right
+
-		escapement boundary.
+	The distance that the character outline is inset from the right
+	escapement boundary.
 */
 
 
 /*!
 	\struct font_height
+	\ingroup interface
+	\ingroup libbe
 	\brief The amount of vertical space surrounding a character.
 
 	\see BFont::GetHeight()
@@ -426,24 +482,29 @@
 
 /*!
 	\var font_height::ascent
-	\brief The distance characters can ascend above the baseline.
+
+	The distance characters can ascend above the baseline.
 */
 
 
 /*!
 	\var font_height::descent
-	\brief The distance characters can descend below the baseline.
+
+	The distance characters can descend below the baseline.
 */
 
 
 /*!
 	\var font_height::leading
-	\brief The distance between lines, descent above to ascent below.
+
+	The distance between lines, descent above to ascent below.
 */
 
 
 /*!
 	\struct escapement_delta
+	\ingroup interface
+	\ingroup libbe
 	\brief The amount of horizontal space surrounding a character.
 
 	Escapements need to be multiplied by the font size to get the correct
@@ -455,60 +516,72 @@
 
 /*!
 	\var escapement_delta::nonspace
-	\brief The amount of space surrounding a character with a visible glyph.
+
+	The amount of space surrounding a character with a visible glyph.
 */
 
 
 /*!
 	\var escapement_delta::space
-	\brief The amount of space surrounding a whitespace character, for example
+
-		\c B_TAB and \c B_SPACE.
+	The amount of space surrounding a whitespace character, for example
+	\c B_TAB and \c B_SPACE.
 */
 
 
 /*!
 	\struct font_cache_info
+	\ingroup interface
+	\ingroup libbe
 	\brief Font cache parameters.
 */
 
 
 /*!
 	\var font_cache_info::sheared_font_penalty
-	\brief Sheared font penalty.
+
+	Sheared font penalty.
 */
 
 
 /*!
 	\var font_cache_info::rotated_font_penalty
-	\brief Rotated font penalty.
+
+	Rotated font penalty.
 */
 
 
 /*!
 	\var font_cache_info::oversize_threshold
-	\brief Oversize threshold.
+
+	Oversize threshold.
 */
 
 
 /*!
 	\var font_cache_info::oversize_penalty
-	\brief Oversize penalty.
+
+	Oversize penalty.
 */
 
 /*!
 	\var font_cache_info::cache_size
-	\brief Cache size.
+
+	Cache size.
 */
 
 
 /*!
 	\var font_cache_info::spacing_size_threshold
-	\brief Spacing size threshold.
+
+	Spacing size threshold.
 */
 
 
 /*!
 	\struct tuned_font_info
+	\ingroup interface
+	\ingroup libbe
 	\brief Tuning information of fonts used to make it look better when
 		displayed on-screen.
 
@@ -519,30 +592,35 @@
 
 /*!
 	\var tuned_font_info::size
-	\brief Font size.
+
+	Font size.
 */
 
 
 /*!
 	\var tuned_font_info::shear
-	\brief Font shear.
+
+	Font shear.
 */
 
 
 /*!
 	\var tuned_font_info::rotation
-	\brief Font rotation.
+
+	Font rotation.
 */
 
 
 /*!
 	\var tuned_font_info::flags
-	\brief Font flags.
+
+	Font flags.
 */
 
 /*!
 	\var tuned_font_info::face
-	\brief Font face.
+
+	Font face.
 */
 
 

docs/user/interface/GridLayout.dox

@@ -1,17 +1,21 @@
 /*
- * Copyright 2010, Haiku, Inc. All Rights Reserved.
+ * Copyright 2010 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
- *   Alex Wilson <[email protected]>
+ *		Alex Wilson, [email protected]
+ *
  * Corresponds to:
- *   /trunk/headers/os/interface/GridLayout.h  rev 38207
+ *		headers/os/interface/GridLayout.h	rev 38207
- *   /trunk/src/kits/interface/GridLayout.cpp  rev 38207
+ *		src/kits/interface/GridLayout.cpp	rev 38207
  */
 
 
 /*!
 	\file GridLayout.h
+	\ingroup interface
+	\ingroup layout
+	\ingroup libbe
 	\brief Provides the BGridLayout class.
 */
 
@@ -21,9 +25,8 @@
 	\ingroup interface
 	\ingroup layout
 	\ingroup libbe
-
 	\brief The BGridLayout class a BLayout subclass that arranges the items it
-	holds in a grid.
+		holds in a grid.
 
 	Each item in a BGridLayout receives a rectangular area which can span more
 	than a single row or column. The indexing of columns and rows is zero based,

docs/user/interface/GroupLayout.dox

@@ -1,17 +1,21 @@
 /*
- * Copyright 2010, Haiku, Inc. All Rights Reserved.
+ * Copyright 2010 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
- *   Alex Wilson <[email protected]>
+ *		Alex Wilson, [email protected]
+ *
  * Corresponds to:
- *   /trunk/headers/os/interface/GroupLayout.h  rev 38207
+ *		headers/os/interface/GroupLayout.h  rev 38207
- *   /trunk/src/kits/interface/GroupLayout.cpp  rev 38207
+ *		src/kits/interface/GroupLayout.cpp  rev 38207
  */
 
 
 /*!
 	\file GroupLayout.h
+	\ingroup interface
+	\ingroup layout
+	\ingroup libbe
 	\brief Describes the BGroupLayout class.
 */
 
@@ -21,7 +25,7 @@
 	\ingroup layout
 	\ingroup libbe
 	\brief The BGroupLayout class is a simple BLayout subclass that
-	arranges the items it holds within a vertical or horizontal box.
+		arranges the items it holds within a vertical or horizontal box.
 
 	In a horizontal BGroupLayout, each BLayoutItem is given the same vertical
 	area, but different horizontal areas. In a vertical BGroupLayout, each
@@ -47,7 +51,8 @@
 */
 
 
-/*!	\fn BGroupLayout::BGroupLayout(enum orientation orientation, float spacing)
+/*!
+	\fn BGroupLayout::BGroupLayout(enum orientation orientation, float spacing)
 	\brief Creates a new BGroupLayout.
 
 	\param orientation The #orientation of this BGroupLayout.
@@ -55,52 +60,61 @@
 */
 
 
-/*! \fn BGroupLayout::~BGroupLayout()
+/*!
+	\fn BGroupLayout::~BGroupLayout()
 	\brief Destructor method.
 
 	Standard Destructor.
 */
 
 
-/*!	\fn BGroupLayout::BGroupLayout(BMessage* from)
+/*!
+	\fn BGroupLayout::BGroupLayout(BMessage* from)
 	\brief Archive constructor.
 
 	\param from The message to construct the BGroupLayout from.
 */
 
 
-/*!	\fn float BGroupLayout::Spacing() const
+/*!
+	\fn float BGroupLayout::Spacing() const
 	\brief Get the amount of spacing (in pixels) between each item.
 */
 
 
-/*!	\fn void BGroupLayout::SetSpacing(float spacing)
+/*!
+	\fn void BGroupLayout::SetSpacing(float spacing)
 	\brief Set the amount of spacing (in pixels) between each item.
 */
 
 
-/*!	\fn orientation BGroupLayout::Orientation() const
+/*!
+	\fn orientation BGroupLayout::Orientation() const
 	\brief Get the #orientation of this BGroupLayout.
 */
 
 
-/*!	\fn void BGroupLayout::SetOrientation(enum orientation orientation)
+/*!
+	\fn void BGroupLayout::SetOrientation(enum orientation orientation)
 	\brief Set the #orientation of this BGroupLayout.
 	\param orientation The new #orientation of this BGroupLayout.
 */
 
 
-/*!	\fn float BGroupLayout::ItemWeight(int32 index) const
+/*!
+	\fn float BGroupLayout::ItemWeight(int32 index) const
 	\brief Get the weight of the item at \a index.
 */
 
 
-/*!	\fn void BGroupLayout::SetItemWeight(int32 index, float weight)
+/*!
+	\fn void BGroupLayout::SetItemWeight(int32 index, float weight)
 	\brief Set the weight of the item at \a index.
 */
 
 
-/*!	\fn BLayoutItem* BGroupLayout::AddView(BView* child)
+/*!
+	\fn BLayoutItem* BGroupLayout::AddView(BView* child)
 	\brief Adds \a child to this layout as the last item. In a vertical
 		BGroupLayout, \a child will be on the right, in a horizontal
 		BGroupLayout, \a child will be at the bottom.
@@ -109,27 +123,31 @@
 */
 
 
-/*!	\fn BLayoutItem* BGroupLayout::AddView(int32 index, BView* child)
+/*!
+	\fn BLayoutItem* BGroupLayout::AddView(int32 index, BView* child)
 	\brief Adds \a child to this layout at \a index.
 
 	\a child will have a weight of \c 1.0f.
 */
 
 
-/*!	\fn BLayoutItem* BGroupLayout::AddView(BView* child, float weight)
+/*!
+	\fn BLayoutItem* BGroupLayout::AddView(BView* child, float weight)
 	\brief Adds \a child to the end of this layout with a weight of
 		\a weight.
 */ 
 
 
-/*!	\fn BLayoutItem* BGroupLayout::AddView(int32 index, BView* child, 
+/*!
+	\fn BLayoutItem* BGroupLayout::AddView(int32 index, BView* child, 
 		float weight)
 	\brief Adds \a child this layout at \a index with a weight of
 		\a weight.
 */
 
 
-/*!	\fn bool BGroupLayout::AddItem(BLayoutItem* item)
+/*!
+	\fn bool BGroupLayout::AddItem(BLayoutItem* item)
 	\brief Adds \a item to this layout as the last item. In a vertical
 		BGroupLayout, \a item will be on the right, in a horizontal
 		BGroupLayout, \a item will be at the bottom.
@@ -138,20 +156,23 @@
 */
 
 
-/*!	\fn bool BGroupLayout::AddItem(int32 index, BLayoutItem* item)
+/*!
+	\fn bool BGroupLayout::AddItem(int32 index, BLayoutItem* item)
 	\brief Adds \a item to this layout at \a index.
 
 	\a item will have a weight of \c 1.0f.
 */
 
 
-/*!	\fn bool BGroupLayout::AddItem(BLayoutItem* item, float weight)
+/*!
+	\fn bool BGroupLayout::AddItem(BLayoutItem* item, float weight)
 	\brief Adds \a item to the end of this layout with a weight of
 		\a weight.
 */
 
 
-/*!	\fn bool BGroupLayout::AddItem(int32 index, BLayoutItem* item, float weight)
+/*!
+	\fn bool BGroupLayout::AddItem(int32 index, BLayoutItem* item, float weight)
 	\brief Adds \a item this layout at \a index with a weight of
 		\a weight.
 */

docs/user/interface/IconUtils.dox

@@ -1,17 +1,20 @@
 /*
- * Copyright 2011, Haiku, Inc. All Rights Reserved.
+ * Copyright 2011 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
- *		Adrien Destugues <[email protected]>
+ *		Adrien Destugues, [email protected]
+ *
  * Corresponds to:
- *		/trunk/headers/os/interface/IconUtils.h  rev 42600
+ *		headers/os/interface/IconUtils.h	rev 42600
- *		/trunk/src/kits/interface/IconUtils.cpp  rev 42600
+ *		src/kits/interface/IconUtils.cpp	rev 42600
  */
 
 
 /*!
 	\file IconUtils.h
+	\ingroup interface
+	\ingroup libbe
 	\brief Vector icon handling utility class
 */
 

docs/user/interface/InterfaceDefs.dox

@@ -1,20 +1,34 @@
 /*
- * Copyright 2001-2011, Haiku, Inc. All rights reserved.
+ * Copyright 2011 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		John Scipione, [email protected]
+ *
+ * Corresponds to:
+ *		headers/os/interface/InterfaceDefs.h	rev 43230
+ *		src/kits/interface/InterfaceDefs.cpp	rev 43230
  */
 
+
 /*!
 	\file InterfaceDefs.h
+	\ingroup interface
+	\ingroup libbe
 	\brief Defines standard interface definitions for controls.
 */
 
 
 /*!
 	\enum border_style
+	\ingroup interface
+
 	Collection of flags that determine the border style drawn around a BBox.
 */
 
-/*! \var border_style B_PLAIN_BORDER
+
+/*!
+	\var border_style B_PLAIN_BORDER
 
 	\image html B_PLAIN_BORDER.png
 
@@ -23,7 +37,9 @@
 	is raised slightly above the surrounding surface.
 */
 
-/*! \var border_style B_FANCY_BORDER
+
+/*!
+	\var border_style B_FANCY_BORDER
 
 	\image html B_FANCY_BORDER.png
 
@@ -31,45 +47,61 @@
 	in appearance on all four sides. This is the default appearance.
 */
 
-/*! \var border_style B_NO_BORDER
+
+/*!
+	\var border_style B_NO_BORDER
+
 	No border.
 */
 
 
 /*!
 	\enum orientation
-Orientation flag sets the layout to either horizontal or vertical
+
+	Orientation flag sets the layout to either horizontal or vertical
 	alignment.
 */
 
+
 /*!
 	\var orientation B_HORIZONTAL
+
 	Horizontal alignment
 */
 
-/*! \var orientation B_VERTICAL
+
+/*!
+	\var orientation B_VERTICAL
+
 	Vertical alignment
 */
 
 
 /*!
 	\enum button_width
+
 	Collection of flags that determine how wide to draw the buttons in a
 	BAlert dialog.
 */
 
+
 /*!
 	\var button_width B_WIDTH_AS_USUAL
+
 	Set the width of each button based on the standard width.
 */
 
+
 /*!
 	\var button_width B_WIDTH_FROM_WIDEST
+
 	Set the width of each button based on the width of the widest button.
 */
 
+
 /*!
 	\var button_width B_WIDTH_FROM_LABEL
+
 	Set the width of each button to accomidate the width of the button's
 	label.
 */

docs/user/interface/Layout.dox

@@ -1,17 +1,21 @@
 /*
- * Copyright 2010, Haiku, Inc. All Rights Reserved.
+ * Copyright 2010 Haiku Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
- *   Alex Wilson <[email protected]>
+ *		Alex Wilson, [email protected]
+ *
  * Corresponds to:
- *   /trunk/headers/os/interface/Layout.h  rev 38207
+ *		headers/os/interface/Layout.h	rev 38207
- *   /trunk/src/kits/interface/Layout.cpp  rev 38207
+ *		src/kits/interface/Layout.cpp	rev 38207
  */
 
 
 /*!
 	\file Layout.h
+	\ingroup interface
+	\ingroup layout
+	\ingroup libbe
 	\brief Defines the BLayout class.
 */
 
@@ -72,7 +76,7 @@ topLayout->AddItem(nestedLayoutWithView);
 
 	After this constructor has finished, this BLayout holds no
 	BLayoutItem&apos;s and does not have a target BView.
-	
+
 	\warning Because a new BLayout does not have a target BView, calls to the
 		AddItem() and AddView() will fail methods will fail.
 */
@@ -147,7 +151,7 @@ topLayout->AddItem(nestedLayoutWithView);
 		this layout.
 		
 	\a child is added to this BLayout&apos;s target view.
-	
+
 	\returns The BLayoutItem created to represent \a child is, or \c NULL if
 		there was an error.
 
@@ -208,7 +212,7 @@ topLayout->AddItem(nestedLayoutWithView);
 		it represents from this BLayout&apos;s target view.
 
 	\param item The BLayoutItem to be removed
-	
+
 	\warning \a item is not deleted, you must delete it manually, or add it	to
 		another BLayout.
 	\warning \a item->View(), even when it is removed from the target view,
@@ -255,7 +259,7 @@ topLayout->AddItem(nestedLayoutWithView);
 /*!
 	\fn int32 BLayout::IndexOfView(BView* child) const
 	\brief Get the index of \a child in this layout.
-	
+
 	\note This finds the index of views added through BLayout::AddView(), not
 		the index of an item which represents \a child that was added through
 		BLayout::AddItem().
@@ -339,7 +343,7 @@ topLayout->AddItem(nestedLayoutWithView);
 	\brief If there is no layout currently ongoing, and \a force is \c false,
 		creates a new BLayoutContext and calls the DoLayout() method
 		of this BLayout and any BLayout s nested in this BLayout.
-	
+
 	This method also guarantees that the owner view of this layout (as returned
 	by BLayout::Owner()) performs a layout as well (if it is suitable to do so).
 

docs/user/interface/LayoutBuilder.Group.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2011, Haiku, Inc. All Rights Reserved.
+ * Copyright 2011 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -14,6 +14,9 @@
 
 /*!
 	\file GroupLayoutBuilder.h
+	\ingroup interface
+	\ingroup layout
+	\ingroup libbe
 	\brief Provides the BLayoutBuilder::Group<> class.
 */
 
@@ -22,6 +25,7 @@
 	\class BLayoutBuilder::Group<>
 	\ingroup interface
 	\ingroup layout
+	\ingroup libbe
 	\brief BLayoutBuilder::Base subclass for building BGroupLayouts.
 */
 
@@ -347,7 +351,7 @@
 
 
 /*!
-	\fn	BView* BLayoutBuilder::Group<ParentBuilder>::View() const
+	\fn BView* BLayoutBuilder::Group<ParentBuilder>::View() const
 	\brief Get the BView this builder's BGroupLayout is attached to.
 */
 
@@ -361,7 +365,7 @@
 
 
 /*!
-	\fn	ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::GetView(
+	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::GetView(
 	BView** _view)
 	\brief Get the BView this builder's BGroupLayout is attached to.
 	\param[out] _view The BView this builder's BGroupLayout is attached to.

docs/user/interface/LayoutBuilder.dox

@@ -1,13 +1,27 @@
 /*
- * Copyright 2010, Haiku, Inc. All Rights Reserved.
+ * Copyright 2010 Haiku Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
- *   Alex Wilson <[email protected]>
+ *		Alex Wilson, [email protected]
+ *
+ * Corresponds to:
+ *		headers/os/interface/LayoutBuilder.h	rev 38207
+ *		src/kits/interface/LayoutBuilder.cpp	rev 38207
  */
 
 
-/*!	\class BLayoutBuilder::Base<>
+/*!
+	\file LayoutBuilder.h
+	\ingroup interface
+	\ingroup layout
+	\ingroup libbe
+	\brief Defines the BLayoutBuilder templates.
+*/
+
+
+/*!
+	\class BLayoutBuilder::Base<>
 	\ingroup interface
 	\ingroup layout
 	\brief Base for all other layout builders in the BLayoutBuilder namespace.

docs/user/interface/LayoutItem.dox

@@ -1,18 +1,22 @@
 /*
- * Copyright 2010, Haiku, Inc. All Rights Reserved.
+ * Copyright 2010 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
- *   Alex Wilson <[email protected]>
+ *		Alex Wilson, [email protected]
+ *
  * Corresponds to:
- *   /trunk/headers/os/interface/LayoutItem.h  rev 38207
+ *		headers/os/interface/LayoutItem.h  rev 38207
- *   /trunk/src/kits/interface/LayoutItem.cpp  rev 38207
+ *		src/kits/interface/LayoutItem.cpp  rev 38207
  */
 
 
 /*!
 	\file LayoutItem.h
-	\brief Describes the BLayoutItem class
+	\ingroup interface
+	\ingroup layout
+	\ingroup libbe
+	\brief Describes the BLayoutItem class.
 */
 
 
@@ -21,7 +25,6 @@
 	\ingroup interface
 	\ingroup layout
 	\ingroup libbe
-
 	\brief Abstract class representing things that are positionable and
 		resizable by objects of the BLayout class.
 
@@ -98,7 +101,7 @@
 	\fn bool BLayoutItem::HasHeightForWidth()
 	\brief Returns whether or not this BLayoutItem&apos;s height constraints are
 		dependent on its width.
-	
+
 	\note By default, this method returns \c false.
 */
 

docs/user/interface/Screen.dox

@@ -1,19 +1,22 @@
 /*
- * Copyright 2011, Haiku inc.
+ * Copyright 2011 Haiku, Inc. All rights reserved.
- * Distributed under the terms of the MIT Licence.
+ * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
  *		Stefano Ceccherini, [email protected]
  *		Axel Dörfler, [email protected]
  *		John Scipione, [email protected]
+ *
  * Corresponds to:
- *		/trunk/headers/os/interface/Screen.h	 rev 42759
+ *		/trunk/headers/os/interface/Screen.h	rev 42759
- *		/trunk/src/kits/interface/Screen.cpp	 rev 42759
+ *		/trunk/src/kits/interface/Screen.cpp	rev 42759
  */
 
 
 /*!
 	\file Screen.h
+	\ingroup interface
+	\ingroup libbe
 	\brief Defines the BScreen class and support structures.
 */
 
@@ -21,6 +24,7 @@
 /*!
 	\class BScreen
 	\ingroup interface
+	\ingroup libbe
 	\brief The BScreen class provides methods to retrieve and change display
 		settings.
 
@@ -126,7 +130,8 @@
 */
 
 
-/*!	\fn color_space BScreen::ColorSpace()
+/*!
+	\fn color_space BScreen::ColorSpace()
 	\brief Gets the color_space of the display.
 
 	\return \c B_CMAP8, \c B_RGB15, \c B_RGB32, or \c B_NO_COLOR_SPACE

docs/user/interface/TwoDimensionalLayout.dox

@@ -1,17 +1,21 @@
 /*
- * Copyright 2010, Haiku, Inc. All Rights Reserved.
+ * Copyright 2010 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
- *   Alex Wilson <[email protected]>
+ *		Alex Wilson, [email protected]
+ *
  * Corresponds to:
- *   /trunk/headers/os/interface/TwoDimensionalLayout.h  rev 38207
+ *		headers/os/interface/TwoDimensionalLayout.h	rev 38207
- *   /trunk/src/kits/interface/TwoDimensionalLayout.cpp  rev 38207
+ *		src/kits/interface/TwoDimensionalLayout.cpp	rev 38207
  */
 
 
 /*!
 	\file TwoDimensionalLayout.h
+	\ingroup interface
+	\ingroup layout
+	\ingroup libbe
 	\brief Defines the BTwoDimensionalLayout class.
 */
 
@@ -21,7 +25,6 @@
 	\ingroup interface
 	\ingroup layout
 	\ingroup libbe
-
 	\brief Abstract BLayout subclass arranging items within rows and columns.
 
 	This class manages all the tricky work of actually positioning/resizing

docs/user/interface/View.dox

@@ -1,18 +1,21 @@
 /*
- * Copyright 2011, Haiku inc.
+ * Copyright 2011 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
  *		John Scipione, [email protected]
+ *
  * Corresponds to:
- *		/trunk/headers/os/interface/View.h	 rev 42794
+ *		headers/os/interface/View.h	 rev 42794
- *		/trunk/src/kits/interface/View.cpp	 rev 42794
+ *		src/kits/interface/View.cpp	 rev 42794
  */
 
 
 /*!
 	\file View.h
-	\brief BView class definition and support enums.
+	\ingroup interface
+	\ingroup libbe
+	\brief BView class definition and support data structures.
 */
 
 
@@ -20,7 +23,6 @@
 	\class BView
 	\ingroup interface
 	\ingroup libbe
-
 	\brief View base class.
 */
 

docs/user/interface/_interface_intro.dox

@@ -1,26 +1,26 @@
 /*
- * Copyright 2010, Haiku, Inc. All Rights Reserved.
+ * Copyright 2010 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
- *		Alex Wilson <[email protected]>
+ *		Alex Wilson, [email protected]
  */
 
 
 /*!
 	\page interface_intro Introduction to the Interface Kit.
-  
+
 	The Interface Kit holds all the classes you'll need to develop a GUI.
 	Building on the messaging facilities provided by the Application Kit,
-	the Inteface Kit can be used to create a responsive and attractive graphical
+	the Interface Kit can be used to create a responsive and attractive
-	user interface.
+	graphical user interface.
 
- 	The most important class in the Interface Kit is the BView class, which
+	The most important class in the Interface Kit is the BView class, which
 	handles drawing and user interaction. Pointer and keyboard events are
 	processed in this class. 
 
 	Another important class is the BWindow class, which holds BViews and makes
-	them visibile to the user. The BWindow class also handles BView focusing
+	them visible to the user. The BWindow class also handles BView focusing
 	and BMessage dispatching, among other things.
 
 	A new addition Haiku has added over the BeOS API is the Layout API, which

docs/user/interface/_layout_intro.dox

@@ -1,9 +1,9 @@
 /*
- * Copyright 2010, Haiku, Inc. All Rights Reserved.
+ * Copyright 2010 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
- *		Alex Wilson <[email protected]>
+ *		Alex Wilson, [email protected]
  */
 
 
@@ -13,7 +13,8 @@
 	Haiku's Layout API is centered around the BLayoutItem and BLayout classes.
 	The BLayoutItem class represents thing that can be managed by a BLayout,
 	which is itself a BLayoutItem. Before we go any further, it is a good idea
-	to familiarize yourself with the different BLayouts available in Haiku:
+	to familiarize yourself with the different BLayout classes available in
+	Haiku:
 		\li BGroupLayout
 		\li BGridLayout
 		\li BCardLayout
@@ -21,14 +22,14 @@
 
 	You'll notice that BSplitView is not actually a BLayout, but a BView. The
 	BSplitView class uses a custom BLayout behind the scenes, but because it
-	must also be able to draw, a BView is required. Other BLayouts have
+	must also be able to draw, a BView is required. Other BLayout objects have
-	BViews that can be used for convenience.
+	BView objects that can be used for convenience.
 		\li BGroupLayout : BGroupView
 		\li BGridLayout : BGridView
 		\li BCardLayout : BTabView (also provides on-screen tabs)
 
 	Although it is not necessary to use these classes to make use of the
-	coresponding layouts, it does make things easier.
+	corresponding layouts, it does make things easier.
 
 	Once you have an understanding of what each BLayout does, you can start
 	designing an interface with them. Let's consider a very simple window,
@@ -39,8 +40,7 @@
 	So, let's review the BGroupLayout constructor:
 
 \code
-BGroupLayout(enum orientation orientation, float spacing
+BGroupLayout(enum orientation orientation, float spacing = B_USE_DEFAULT_SPACING)
-		= B_USE_DEFAULT_SPACING)
 \endcode
 
 	Because we only have one item in this layout, \c orientation and \c spacing
@@ -67,17 +67,17 @@ group->AddView(MakeStringView("Haiku rocks!"));
 
 	That does it! Now we've got a BWindow with a horizontal BGroupLayout holding
 	a single BView. However, if we want to ensure that our BStringView is always
-	centered in the window, we should give it an explict BAlignment. So that
+	centered in the window, we should give it an explicit BAlignment. So the
 	last line becomes:
 
 \code
 BLayoutItem* stringView = group->AddView(MakeStringView("Haiku rocks!"));
 stringView->SetExplicitAlignment(BAlignment(B_ALIGN_HORIZONTAL_CENTER,
-		B_ALIGN_VERTICAL_CENTER);
+	B_ALIGN_VERTICAL_CENTER);
 \endcode
 
 	Now our BStringView will always be right in the middle of the space
-	alloted to it, which at the moment is the whole of \c window.
+	allotted to it, which at the moment is the whole of \c window.
 
 	Now let's take things one step further, and add a BMenuBar into the mix.
 
@@ -118,8 +118,8 @@ group->AddItem(grid);
 \endcode
 
 	You'll notice that we've added \c grid directly to \c group. This means that
-	any BViews we add to \c grid will become children of \c window, but will be
+	any BView objects we add to \c grid will become children of \c window, but
-	positioned by \c grid.
+	will be positioned by \c grid.
 
 \code
 grid->AddView(MakeSmallButton(), 0, 0);
@@ -128,7 +128,7 @@ grid->AddView(MakeBigButton(), 0, 1, 2, 1);
 grid->AddView(MakeSmallButton(), 1, 2);
 \endcode
 
-	Now we've got a nice grid of BButtons, let's go over it quickly:
+	Now we've got a nice grid of BButton objects, let's go over it quickly:
 		\li \c grid has two columns and three rows.
 		\li The cells (0, 0), (1, 0), and (1, 2) hold small buttons
 		\li The cells (0, 1) and (1, 1) hold a single button that spans both
@@ -156,6 +156,4 @@ BLayoutBuilder::Group<>(window, B_VERTICAL)
 	This is only one way that you could build this layout, but it is probably
 	the most succinct. Functionally, this is equivalent to all the previous
 	code in this introduction.
-
 */
-

docs/user/interface/layout_tips.dox

@@ -26,7 +26,6 @@
 		consider using one of the layout-related convenience classes (eg.
 		BGroupView for BGroupLayout).
 
-
 	\section layout_layout_tips BLayout Tips
 
 	\li It is generally better to add BViews and BLayoutItems directly to the

docs/user/locale/Catalog.dox

@@ -1,20 +1,22 @@
 /*
- * Copyright 2011-2012 Haiku, Inc. All Rights Reserved.
+ * Copyright 2011-2012 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		Axel Dörfler, [email protected]
  *		John Scipione, [email protected]
  *		Oliver Tappe, [email protected]
- * 
+ *
  * Corresponds to:
- *		/trunk/headers/os/locale/Catalog.h	 hrev45083
+ *		headers/os/locale/Catalog.h	 hrev45083
- *		/trunk/src/kits/locale/Catalog.cpp	 hrev45083
+ *		src/kits/locale/Catalog.cpp	 hrev45083
  */
 
 
 /*!
 	\file Catalog.h
+	\ingroup locale
+	\ingroup libbe
 	\brief Provides the BCatalog class.
 */
 

docs/user/locale/Collator.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2011, Haiku, Inc. All Rights Reserved.
+ * Copyright 2011 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -8,13 +8,15 @@
  *		John Scipione, [email protected]
  *
  * Corresponds to:
- *		/trunk/headers/os/locale/Collator.h	 rev 42274
+ *		headers/os/locale/Collator.h	 rev 42274
- *		/trunk/src/kits/locale/Collator.cpp	 rev 42274
+ *		src/kits/locale/Collator.cpp	 rev 42274
  */
 
 
 /*!
 	\file Collator.h
+	\ingroup locale
+	\ingroup libbe
 	\brief Provides the BCollator class.
 */
 
@@ -22,6 +24,7 @@
 /*!
 	\class BCollator
 	\ingroup locale
+	\ingroup libbe
 	\brief Class for handling locale-aware collation (sorting) of strings.
 
 	BCollator is designed to handle collation (sorting) of strings. Unlike

docs/user/locale/Country.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2011, Haiku, Inc. All Rights Reserved.
+ * Copyright 2011 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -8,26 +8,31 @@
  *		John Scipione, [email protected]
  * 
  * Corresponds to:
- *		/trunk/headers/os/locale/Country.h	 rev 42274
+ *		headers/os/locale/Country.h	 rev 42274
- *		/trunk/src/kits/locale/Country.cpp	 rev 42274
+ *		src/kits/locale/Country.cpp	 rev 42274
  */
 
 
-/*!	\file Country.h
+/*!
+	\file Country.h
+	\ingroup locale
+	\ingroup libbe
 	\brief BCountry class definition.
 */
 
 
-/*!	\class BCountry
+/*!
+	\class BCountry
 	\ingroup locale
-	\brief Class representing a country
+	\ingroup libbe
+	\brief Class representing a country.
 
-	BCountry provides all the information about a particular country.
+	BCountry provides information about a particular country including the
-	This includes the country flag (as an HVIF icon), the localized name
+	countries flag (as an HVIF icon), the localized name of the country,
-	of the country, and the ISO country code.
+	and the ISO country code.
 
-	Date, time, and numer formatting also depends to some extent on the
+	Date, time, and number formatting also depends to some extent on the
-	language used, so they are found in the BLocale class instead.
+	language used so they are found in the BLocale class instead.
 */
 
 
@@ -85,7 +90,7 @@
 	The flag is stored in HVIF format so it can be rendered at any size and
 	color depth.
 
-	\param result The BBitmap to drag the flag into.
+	\param result The BBitmap object to draw the flag into.
 
 	\returns \c B_OK if the drawing was successful.
 */

docs/user/locale/DurationFormat.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2011, Haiku. All rights reserved.
+ * Copyright 2011 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -7,11 +7,19 @@
  *		John Scipione, [email protected]
  *
  * Corresponds to:
- *		/trunk/headers/os/locale/DurationFormat.h	 hrev45084
+ *		headers/os/locale/DurationFormat.h	 hrev45084
- *		/trunk/src/kits/locale/DurationFormat.cpp	 hrev45084
+ *		src/kits/locale/DurationFormat.cpp	 hrev45084
  */
 
 
+/*!
+	\file DurationFormat.h
+	\ingroup locale
+	\ingroup libbe
+	\brief Contains BDurationFormat class, a time interval formatter.
+*/
+
+
 /*!
 	\class BDurationFormat
 	\ingroup locale

docs/user/locale/Locale.dox

@@ -1,12 +1,12 @@
 /*
- * Copyright 2011, Haiku, Inc. All Rights Reserved.
+ * Copyright 2011 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		Axel Dörfler, [email protected].
  *		John Scipione, [email protected]
  *		Oliver Tappe, [email protected].
- * 
+ *
  * Corresponds to:
  *		/trunk/headers/os/locale/Locale.h	 rev 43095
  *		/trunk/src/kits/locale/Locale.cpp	 rev 43095
@@ -15,12 +15,16 @@
 
 /*!
 	\file Locale.h
-	\brief Provides the BLocale class.
+	\ingroup locale
+	\ingroup libbe
+	\brief Provides the BLocale class, the base class of the Locale Kit.
 */
 
 
-/*!	\class BLocale
+/*!
+	\class BLocale
 	\ingroup locale
+	\ingroup libbe
 	\brief Class for representing a locale and its settings.
 
 	A locale is defined by the combination of a country and a language.

docs/user/locale/LocaleRoster.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2003-2010, Haiku. All rights reserved.
+ * Copyright 2003-2010 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -8,15 +8,24 @@
  *		Oliver Tappe, [email protected]
  *
  * Corresponds to:
- *		/trunk/headers/os/locale/LocaleRoster.h	 rev 42274
+ *		headers/os/locale/LocaleRoster.h	 rev 42274
- *		/trunk/src/kits/locale/LocaleRoster.cpp	 rev 42274
+ *		src/kits/locale/LocaleRoster.cpp	 rev 42274
  */
 
 
+/*!
+	\file LocaleRoster.h
+	\ingroup locale
+	\ingroup libbe
+	\brief Provides the BLocaleRoster class to access locale data.
+*/
+
+
 /*!
 	\class BLocaleRoster
 	\ingroup locale
-	\brief Main class for accessing the locale kit data
+	\ingroup libbe
+	\brief Main class for accessing the Locale Kit data.
 
 	The Locale Roster is the central part of the locale kit. It is a global
 	object (\c be_locale_roster) storing all the useful locale data. Other

docs/user/locale/TimeZone.dox

@@ -1,26 +1,30 @@
 /*
- * Copyright 2011, Haiku inc.
+ * Copyright 2011 Haiku, Inc. All rights reserved.
- * Distributed under the terms of the MIT Licence.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		Adrien Destugues, [email protected]
+ *		John Scipione, [email protected]
+ *		Oliver Tappe, [email protected]
  *
- * Documentation by:
- *		Adrien Destugues <[email protected]>
- *		John Scipione <[email protected]>
- *		Oliver Tappe <[email protected]>
  * Corresponds to:
- *		/trunk/headers/os/locale/TimeZone.h	 rev 42274
+ *		headers/os/locale/TimeZone.h	 rev 42274
- *		/trunk/src/kits/locale/TimeZone.cpp	 rev 42274
+ *		src/kits/locale/TimeZone.cpp	 rev 42274
  */
 
 
 /*!
 	\file TimeZone.h
-	\brief Provides for the BTimeZone class.
+	\ingroup locale
+	\ingroup libbe
+	\brief Provides the BTimeZone class.
 */
 
 
 /*!
 	\class BTimeZone
 	\ingroup locale
+	\ingroup libbe
 	\brief Provides information about time zones.
 */
 

docs/user/locale/UnicodeChar.dox

@@ -1,20 +1,29 @@
 /*
- * Copyright 2011, Haiku, Inc. All Rights Reserved.
+ * Copyright 2011 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the OpenBeOS License.
  *
  * Authors:
- *		Axel Dörfler <[email protected]>
+ *		Axel Dörfler, [email protected]
- *		John Scipione <[email protected]>
+ *		John Scipione, [email protected]
- * 
+ *
  * Corresponds to:
- *		/trunk/headers/os/locale/UnicodeChar.h	 rev 42274
+ *		headers/os/locale/UnicodeChar.h	 rev 42274
- *		/trunk/src/kits/locale/UnicodeChar.cpp	 rev 42274
+ *		src/kits/locale/UnicodeChar.cpp	 rev 42274
  */
 
+
+/*!
+	\file UnicodeChar.h
+	\ingroup locale
+	\ingroup libbe
+	\brief Provides the BUnicodeChar class.
+*/
+
+
 /*!
 	\class BUnicodeChar
 	\ingroup locale
-
+	\ingroup libbe
 	\brief Management of all information about characters.
 
 	This class provide a set of tools for managing the whole set of characters
@@ -27,11 +36,12 @@
 	instantiate it. You can call one of the methods passing in the character
 	that you want to be examined.
 
-	Note all the function work with chars encoded in utf-32. This is not the
+	Note all the function work with chars encoded in UTF-32. This is not the
 	most usual way to handle characters, but it is the fastest. To convert an
-	utf-8 string to an utf-32 character use the FromUTF8() method.
+	UTF-8 string to an UTF-32 character use the FromUTF8() method.
 */
 
+
 /*!
 	\fn static bool BUnicodeChar::IsAlpha(uint32 c)
 	\brief Determine if \a c is alphabetic.
@@ -40,6 +50,7 @@
 		alphabetic character.
 */
 
+
 /*!
 	\fn static bool BUnicodeChar::IsAlNum(uint32 c)
 	\brief Determine if \a c is alphanumeric.
@@ -48,6 +59,7 @@
 		alphabetic or numeric character.
 */
 
+
 /*!
 	\fn static bool BUnicodeChar::IsDigit(uint32 c)
 	\brief Determine if \a c is numeric.
@@ -56,6 +68,7 @@
 		number character.
 */
 
+
 /*!
 	\fn static bool BUnicodeChar::IsHexDigit(uint32 c)
 	\brief Determine if \a c is a hexadecimal digit.
@@ -64,6 +77,7 @@
 		hexadecimal number character.
 */
 
+
 /*!
 	\fn static bool BUnicodeChar::IsUpper(uint32 c)
 	\brief Determine if \a c is uppercase.
@@ -72,6 +86,7 @@
 		uppercase character.
 */
 
+
 /*!
 	\fn static bool BUnicodeChar::IsLower(uint32 c)
 	\brief Determine if \a c is lowercase.
@@ -80,6 +95,7 @@
 		lowercase character.
 */
 
+
 /*!
 	\fn static bool BUnicodeChar::IsSpace(uint32 c)
 	\brief Determine if \a c is a space.
@@ -94,6 +110,7 @@
 	\sa IsWhitespace()
 */
 
+
 /*!
 	\fn static bool BUnicodeChar::IsWhitespace(uint32 c)
 	\brief Determine if \a c is whitespace.
@@ -107,6 +124,7 @@
 	\sa IsSpace()
 */
 
+
 /*!
 	\fn static bool BUnicodeChar::IsControl(uint32 c)
 	\brief Determine if \a c is a control character.
@@ -120,6 +138,7 @@
 	\sa IsPrintable()
 */
 
+
 /*!
 	\fn static bool BUnicodeChar::IsPunctuation(uint32 c)
 	\brief Determine if \a c is punctuation character.
@@ -128,6 +147,7 @@
 		punctuation character.
 */
 
+
 /*!
 	\fn static bool BUnicodeChar::IsPrintable(uint32 c)
 	\brief Determine if \a c is printable.
@@ -140,6 +160,7 @@
 	\sa IsControl()
 */
 
+
 /*!
 	\fn static bool BUnicodeChar::IsTitle(uint32 c)
 	\brief Determine if \a c is title case.
@@ -150,6 +171,7 @@
 		character.
 */
 
+
 /*!
 	\fn static bool BUnicodeChar::IsDefined(uint32 c)
 	\brief Determine if \a c is defined.
@@ -160,6 +182,7 @@
 	\returns \c true if the specified unicode character is defined.
 */
 
+
 /*!
 	\fn static bool BUnicodeChar::IsBase(uint32 c)
 	\brief Determine if \a c can be used with a diacritic.
@@ -170,6 +193,7 @@
 		form character that can be used with a diacritic.
 */
 
+
 /*!
 	\fn static int8 BUnicodeChar::Type(uint32 c)
 	\brief Gets the type of a character.
@@ -177,6 +201,7 @@
 	\returns A member of the \c unicode_char_category enum.
 */
 
+
 /*!
 	\fn uint32  BUnicodeChar::ToLower(uint32 c)
 	\brief Transforms \a c to lowercase.
@@ -184,6 +209,7 @@
 	\returns The lowercase version of the specified unicode character.
 */
 
+
 /*!
 	\fn uint32 BUnicodeChar::ToUpper(uint32 c)
 	\brief Transforms \a c to uppercase.
@@ -191,6 +217,7 @@
 	\returns The uppercase version of the specified unicode character.
 */
 
+
 /*!
 	\fn uint32 BUnicodeChar::ToTitle(uint32 c)
 	\brief Transforms \a c to title case.
@@ -198,6 +225,7 @@
 	\returns The title case version of the specified unicode character.
 */
 
+
 /*!
 	\fn int32 BUnicodeChar::DigitValue(uint32 c)
 	\brief Gets the numeric value \a c.
@@ -205,33 +233,37 @@
 	\returns The numeric version of the specified unicode character.
 */
 
+
 /*!
 	\fn void BUnicodeChar::ToUTF8(uint32 c, char **out)
-	\brief Transform a character to utf-8 encoding.
+	\brief Transform a character to UTF-8 encoding.
 
-	\returns The utf-8 encoding of the specified unicode character.
+	\returns The UTF-8 encoding of the specified unicode character.
 */
 
+
 /*!
 	\fn uint32 BUnicodeChar::FromUTF8(const char **in)
-	\brief Transform a utf-8 string to an utf-32 character.
+	\brief Transform a UTF-8 string to an UTF-32 character.
 
 	If the string contains multiple characters, only the fist one is used.
 	This function updates the in pointer so that it points on the next
 	character for the following call.
 
-	\returns The utf-32 encoded version of \a in.
+	\returns The UTF-32 encoded version of \a in.
 */
 
+
 /*!
 	\fn size_t BUnicodeChar::UTF8StringLength(const char *str)
 	\brief Counts the characters in the given \c NUL terminated string.
 
-	\returns the number of utf-8 characters in the \c NUL terminated string.
+	\returns the number of UTF-8 characters in the \c NUL terminated string.
 
 	\sa BString::CountChars()
 */
 
+
 /*!
 	\fn size_t BUnicodeChar::UTF8StringLength(const char *str, size_t maxLength)
 	\brief Counts the characters in the given string up to \a maxLength
@@ -240,6 +272,6 @@
 	The string does not need to be \c NUL terminated if you specify a
 	\a maxLength that is shorter than the maximum length of the string.
 
-	\returns the number of utf-8 characters in the \c NUL terminated string
+	\returns the number of UTF-8 characters in the \c NUL terminated string
 		up to \a maxLength characters.
 */

docs/user/media/Buffer.dox

@@ -1,67 +1,80 @@
 /*
- * Copyright 2011, Haiku, Inc. All Rights Reserved.
+ * Copyright 2011 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		John Scipione, [email protected]
- * 
+ *
  * Corresponds to:
- *		/trunk/headers/os/media/Buffer.h	 rev 42274
+ *		headers/os/media/Buffer.h	 rev 42274
- *		/trunk/src/kits/media/Buffer.cpp	 rev 42274
+ *		src/kits/media/Buffer.cpp	 rev 42274
  */
 
 
 /*!
 	\file Buffer.h
+	\ingroup media
+	\ingroup libbe
 	\brief Defines the buffer_clone_info struct and BBuffer class.
 */
 
 
 /*!
 	\struct buffer_clone_info
+	\ingroup media
+	\ingroup libbe
 	\brief A struct that stores where in memory a BBuffer object is in memory
-		as well as the buffer flags.
+		   as well as the buffer flags.
 */
 
 
 /*!
 	\class BBuffer
 	\ingroup media
+	\ingroup libbe
 	\brief A reference to a chunk of memory useful for sharing media data
-		between applications and nodes.
+		   between applications and nodes.
 */
 
 
 /*!
 	\fn void* BBuffer::Data()
-	\brief Returns a pointer to the data of the buffer.
+	\brief Gets a pointer to the data of the buffer.
+
+	\returns A void* pointer to the data.
 */
 
 
 /*!
 	\fn size_t BBuffer::SizeAvailable()
-	\brief Returns the size of the buffer in bytes. Alias for Size().
+	\brief Gets the size of the buffer in bytes. Alias for Size().
+
+	\returns The buffer size in bytes
 */
 
 
 /*!
 	\fn size_t BBuffer::SizeUsed()
-	\brief Returns the size of the portion of the buffer that is currently in
+	\brief Gets the size of the portion of the buffer that is currently in
 		use in bytes.
+
+	\returns The currently used portion of the buffer size in bytes.
 */
 
 
 /*!
 	\fn void BBuffer::SetSizeUsed(size_t size_used)
 	\brief Sets the size of the buffer that is used in bytes.
-	
+
 	This method should be called after writing data to the buffer.
 */
 
 
 /*!
 	\fn uint32 BBuffer::Flags()
-	\brief Returns the flags of the buffer.
+	\brief Gets the flags of the buffer.
+
+	\returns The buffer flags.
 */
 
 
@@ -73,41 +86,57 @@
 
 /*!
 	\fn buffer_clone_info BBuffer::CloneInfo() const
-	\brief Returns the buffer_clone_info struct that describes the buffer.
+	\brief Gets the \c buffer_clone_info struct that describes the buffer.
+
+	\returns The a clone of the \c buffer_clone_info struct.
 */
 
 
 /*!
 	\fn media_buffer_id BBuffer::ID()
-	\brief Returns the app_server ID of the buffer.
+	\brief Gets the ID of the buffer according to the App Server.
+
+	\returns The App Server's ID of the buffer.
 */
 
 
 /*!
 	\fn media_type BBuffer::Type()
-	\brief Returns the media type of the data in the buffer.
+	\brief Gets the media type of the data in the buffer.
+
+	\returns The media type of the data in the buffer.
 */
 
 
 /*!
 	\fn media_header* BBuffer::Header()
-	\brief Returns a pointer to the header of the buffer.
+	\brief Gets a pointer to the header of the buffer.
+
+	\returns A pointer to the header of the buffer.
 */
 
 
 /*!
 	\fn media_audio_header* BBuffer::AudioHeader()
-	\brief Returns a pointer to a header of the audio buffer.
+	\brief Gets a pointer to the header of the audio buffer.
+
+	\returns A pointer to the header of the audio buffer.
 */
 
 
 /*!
 	\fn media_video_header* BBuffer::VideoHeader()
-	\brief Returns a pointer to a header of the video buffer.
+	\brief Gets a pointer to a header of the video buffer.
+
+	\returns A pointer to a header of the video buffer.
 */
 
 
 /*!
 	\fn size_t BBuffer::Size()
-	\brief Returns the size of the buffer in bytes. Alias for SizeAvailable().
+	\brief Gets the size of the buffer in bytes.
+
+	Alias for SizeAvailable().
+
+	\returns The size of the buffer in bytes.
 */

docs/user/media/FileInterface.dox

@@ -1,18 +1,20 @@
 /*
- * Copyright 2012 Haiku, Inc. All Rights Reserved.
+ * Copyright 2012 Haiku Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		John Scipione, [email protected]
  * 
  * Corresponds to:
- *		/trunk/headers/os/media/FileInterface.h	hrev45081
+ *		headers/os/media/FileInterface.h	hrev45081
- *		/trunk/src/kits/media/FileInterface.cpp	hrev45081
+ *		src/kits/media/FileInterface.cpp	hrev45081
  */
 
 
 /*!
 	\file FileInterface.h
+	\ingroup media
+	\ingroup libbe
 	\brief Provides BFileInterface abstract class.
 */
 

docs/user/midi2/Midi2Defs.dox

@@ -1,280 +1,344 @@
 /*!
-\file Midi2Defs.h
+	\file Midi2Defs.h
-\brief Some definitions to define raw MIDI events.
+	\ingroup midi2
-\ingroup midi2
+	\ingroup libbe
+	\brief Some definitions to define raw MIDI events.
 */
 
+
 /*!
-\name Channel Message Masks
+	\name Channel Message Masks
-\brief Some definitions to define the raw MIDI events.
+	\brief Some definitions to define the raw MIDI events.
 
-The default implementation of BMidiLocalConsumer::Data() uses these constants
+	The default implementation of BMidiLocalConsumer::Data() uses these
-to determine which event has been passed on. If you override that method, you
+	constants to determine which event has been passed on. If you override
-may use the constants yourself.
+	that method, you may use the constants yourself.
 */
 
-//! @{
-
-/*!
-\var B_NOTE_OFF
-*/
-
-/*!
-\var B_NOTE_ON
-*/
-
-/*!
-\var B_KEY_PRESSURE
-*/
-
-/*!
-\var B_CONTROL_CHANGE
-*/
-
-/*!
-\var B_PROGRAM_CHANGE
-*/
-
-/*!
-\var B_CHANNEL_PRESSURE
-*/
-
-/*!
-\var B_PITCH_BEND
-*/
-
-//! @}
-
-
-/*! 
-\name System Messages
-\brief Some definitions to define the raw MIDI system messages.
-
-The default implementation of BMidiLocalConsumer::Data() uses these constants
-to determine which event system message has been passed on. See 
-BMidiLocalProducer::SpraySystemCommon() and BMidiLocalProducer::SpraySystemRealTime()
-for more details on how and when to use these messages.
-*/
-
-//! @{
-
-/*!
-\var B_SYS_EX_START
-*/
-
-/*!
-\var B_MIDI_TIME_CODE
-*/
-
-/*!
-\var B_SONG_POSITION
-*/
-
-/*!
-\var B_SONG_SELECT
-*/
-
-/*!
-\var B_CABLE_MESSAGE
-*/
-
-/*!
-\var B_TUNE_REQUEST
-*/
-
-/*!
-\var B_SYS_EX_END
-*/
-
-/*!
-\var B_TIMING_CLOCK
-*/
-
-/*!
-\var B_START
-*/
-
-/*!
-\var B_CONTINUE
-*/
-
-/*!
-\var B_STOP
-*/
-
-/*!
-\var B_ACTIVE_SENSING
-*/
-
-/*!
-\var B_SYSTEM_RESET
-*/
-
-//! @}
-
-/*! 
-\name Controller Numbers
-\brief Constants that represent specific controller messages.
-
-These constants can be used in BMidiLocalProducer::SprayControlChange()
-and BMidiLocalConsumer::ControlChange(). These constants represent the
-MIDI specification.
-*/
 
 //! @{
 
 
+/*!
+	\var B_NOTE_OFF
 */
 
+
 /*!
-\var B_MODULATION
+	\var B_NOTE_ON
 */
 
+
 /*!
-\var B_BREATH_CONTROLLER
+	\var B_KEY_PRESSURE
 */
 
+
 /*!
-\var B_FOOT_CONTROLLER
+	\var B_CONTROL_CHANGE
 */
 
+
 /*!
-\var B_PORTAMENTO_TIME
+	\var B_PROGRAM_CHANGE
 */
 
+
 /*!
-\var B_DATA_ENTRY
+	\var B_CHANNEL_PRESSURE
 */
 
+
 /*!
-\var B_MAIN_VOLUME
+	\var B_PITCH_BEND
-*/
-
-/*!
-\var B_MIDI_BALANCE
-*/
-
-/*!
-\var B_PAN
-*/
-
-/*!
-\var B_EXPRESSION_CTRL
-*/
-
-/*!
-\var B_GENERAL_CTRL_1
-*/
-
-/*!
-\var B_GENERAL_CTRL_2
-*/
-
-/*!
-\var B_GENERAL_CTRL_3
-*/
-
-/*!
-\var B_GENERAL_CTRL_4
-*/
-
-/*!
-\var B_SUSTAIN_PEDAL
-*/
-
-/*!
-\var B_PORTAMENTO
-*/
-
-/*! 
-\var B_SOSTENUTO
-*/
-
-/*!
-\var B_SOFT_PEDAL 
-*/
-
-/*!
-\var B_HOLD_2
-*/
-
-/*!
-\var B_GENERAL_CTRL_5
-*/
-
-/*!
-\var B_GENERAL_CTRL_6
-*/
-
-/*!
-\var B_TEMPO_CHANGE
-*/
-
-/*!
-\var B_GENERAL_CTRL_7
-*/
-
-/*!
-\var B_GENERAL_CTRL_8
-*/
-
-/*!
-\var B_EFFECTS_DEPTH
-*/
-
-/*!
-\var B_TREMOLO_DEPTH 
-*/
-
-/*!
-\var B_CHORUS_DEPTH
-*/
-
-/*!
-\var B_CELESTE_DEPTH
-*/
-
-/*!
-\var B_PHASER_DEPTH
-*/
-
-/*!
-\var B_DATA_INCREMENT
-*/
-
-/*!
-\var B_DATA_DECREMENT
-*/
-
-/*!
-\var B_RESET_ALL_CONTROLLERS
-*/
-
-/*!
-\var B_LOCAL_CONTROL 
-*/
-
-/*!
-\var B_ALL_NOTES_OFF
-*/
-
-/*!
-\var B_OMNI_MODE_OFF
-*/
-
-/*!
-\var B_OMNI_MODE_ON 
-*/
-
-/*!
-\var B_MONO_MODE_ON
-*/
-
-/*!
-\var B_POLY_MODE_ON
 */
 
 
 //! @}
 
 
+/*! 
+	\name System Messages
+	\brief Some definitions to define the raw MIDI system messages.
+
+	The default implementation of BMidiLocalConsumer::Data() uses these
+	constants to determine which event system message has been passed on.
+	See  BMidiLocalProducer::SpraySystemCommon() and
+	BMidiLocalProducer::SpraySystemRealTime() for more details on how and
+	when to use these messages.
+*/
+
+
+//! @{
+
+
+/*!
+	\var B_SYS_EX_START
+*/
+
+
+/*!
+	\var B_MIDI_TIME_CODE
+*/
+
+
+/*!
+	\var B_SONG_POSITION
+*/
+
+
+/*!
+	\var B_SONG_SELECT
+*/
+
+
+/*!
+	\var B_CABLE_MESSAGE
+*/
+
+
+/*!
+	\var B_TUNE_REQUEST
+*/
+
+
+/*!
+	\var B_SYS_EX_END
+*/
+
+
+/*!
+	\var B_TIMING_CLOCK
+*/
+
+
+/*!
+	\var B_START
+*/
+
+
+/*!
+	\var B_CONTINUE
+*/
+
+
+/*!
+	\var B_STOP
+*/
+
+
+/*!
+	\var B_ACTIVE_SENSING
+*/
+
+
+/*!
+	\var B_SYSTEM_RESET
+*/
+
+
+//! @}
+
+
+/*! 
+	\name Controller Numbers
+	\brief Constants that represent specific controller messages.
+
+	These constants can be used in BMidiLocalProducer::SprayControlChange()
+	and BMidiLocalConsumer::ControlChange(). These constants represent the
+	MIDI specification.
+*/
+
+
+//! @{
+
+
+*/
+
+
+/*!
+	\var B_MODULATION
+*/
+
+
+/*!
+	\var B_BREATH_CONTROLLER
+*/
+
+
+/*!
+	\var B_FOOT_CONTROLLER
+*/
+
+
+/*!
+	\var B_PORTAMENTO_TIME
+*/
+
+
+/*!
+	\var B_DATA_ENTRY
+*/
+
+
+/*!
+	\var B_MAIN_VOLUME
+*/
+
+
+/*!
+	\var B_MIDI_BALANCE
+*/
+
+
+/*!
+	\var B_PAN
+*/
+
+
+/*!
+	\var B_EXPRESSION_CTRL
+*/
+
+
+/*!
+	\var B_GENERAL_CTRL_1
+*/
+
+
+/*!
+	\var B_GENERAL_CTRL_2
+*/
+
+
+/*!
+	\var B_GENERAL_CTRL_3
+*/
+
+
+/*!
+	\var B_GENERAL_CTRL_4
+*/
+
+
+/*!
+	\var B_SUSTAIN_PEDAL
+*/
+
+
+/*!
+	\var B_PORTAMENTO
+*/
+
+
+/*! 
+	\var B_SOSTENUTO
+*/
+
+
+/*!
+	\var B_SOFT_PEDAL 
+*/
+
+
+/*!
+	\var B_HOLD_2
+*/
+
+
+/*!
+	\var B_GENERAL_CTRL_5
+*/
+
+
+/*!
+	\var B_GENERAL_CTRL_6
+*/
+
+
+/*!
+	\var B_TEMPO_CHANGE
+*/
+
+
+/*!
+	\var B_GENERAL_CTRL_7
+*/
+
+
+/*!
+	\var B_GENERAL_CTRL_8
+*/
+
+
+/*!
+	\var B_EFFECTS_DEPTH
+*/
+
+
+/*!
+	\var B_TREMOLO_DEPTH 
+*/
+
+
+/*!
+	\var B_CHORUS_DEPTH
+*/
+
+
+/*!
+	\var B_CELESTE_DEPTH
+*/
+
+
+/*!
+	\var B_PHASER_DEPTH
+*/
+
+
+/*!
+	\var B_DATA_INCREMENT
+*/
+
+
+/*!
+	\var B_DATA_DECREMENT
+*/
+
+
+/*!
+	\var B_RESET_ALL_CONTROLLERS
+*/
+
+
+/*!
+	\var B_LOCAL_CONTROL 
+*/
+
+
+/*!
+	\var B_ALL_NOTES_OFF
+*/
+
+
+/*!
+	\var B_OMNI_MODE_OFF
+*/
+
+
+/*!
+	\var B_OMNI_MODE_ON 
+*/
+
+
+/*!
+	\var B_MONO_MODE_ON
+*/
+
+
+/*!
+	\var B_POLY_MODE_ON
+*/
+
+
+//! @}

docs/user/midi2/MidiConsumer.dox

@@ -0,0 +1,323 @@
+/*!
+	\file MidiConsumer.h
+	\ingroup midi2
+	\ingroup libbe
+	\brief Defines consumer classes for the MIDI Kit.
+*/
+
+
+/*!
+	\class BMidiConsumer MidiConsumer.h
+	\ingroup midi2
+	\ingroup libmidi2
+	\ingroup libbe
+	\brief Receives MIDI events from a producer
+
+	A consumer is an object that knows how to deal with incoming MIDI events. A 
+	consumer can be connected to multiple producers at the same time. There is no 
+	way to find out which producers are connected to this consumer just by looking 
+	at the BMidiConsumer object; you will have to consult BMidiRoster for that.
+
+	A BMidiConsumer either represents a local consumer, i.e. a class extending from 
+	BMidiLocalConsumer, or is a proxy for a remote object published by another app. 
+*/
+
+
+/*!
+	\fn bigtime_t BMidiConsumer::Latency() const
+	\brief Returns the latency of this consumer
+
+	The latency is measured in microseconds. Producers should attempt to get MIDI 
+	events to this consumer by <I>(when - latency)</I>. You do this by subtracting 
+	the latency from the performance time when you spray the events (provided that 
+	you spray these events ahead of time, of course).
+
+	You cannot <I>set</I> the latency on a BMidiConsumer, only on a 
+	BMidiLocalConsumer.
+
+	The latency issue gets slightly more complicated when multiple endpoints are 
+	chained together, as in the following picture:
+
+\verbatim
++-------+     +-------------+     +-------+
+|       |     |             |     |       |
+| prodA |---->| consB prodB |---->| consC |
+|       |     |             |     |       |
++-------+     +-------------+     +-------+
+  appA          appB (filter)       appC
+\endverbatim
+
+	Suppose consC has 200ms latency, and consB has 100ms latency. If consB simply 
+	reports 100ms, then prodA will schedule its events for (t - 100), which is 
+	really 200ms too late. (Of course, producers send out their events as soon as 
+	possible, so depending on the load of the system, everything may work out just 
+	fine.)
+
+	ConsB should report the latency of the consumer that is hooked up to its 
+	output, consC, in addition to its own latency. In other words, the full 
+	downstream latency. So, the reported latency in this case would be 300ms. This 
+	also means that appB should change the latency of consB when prodB makes or 
+	breaks a connection, and when consC reports a latency change. (If multiple 
+	consumers are connected to prodB, you should take the slowest one.) 
+	Unfortunately, the Midi Kit provides no easy mechanism for doing any of this, 
+	so you are on your own here.
+*/
+
+/*!
+	\class BMidiLocalConsumer MidiConsumer.h
+	\ingroup midi2
+	\ingroup libmidi2
+	\ingroup libbe
+	\brief A consumer endpoint that is created by your own application.
+
+	If you want to create a consumer that reacts to MIDI events, you should 
+	subclass BMidiLocalConsumer.
+
+	Each local consumer has its own thread that receives and dispatches the MIDI 
+	events. Whenever MIDI data arrives, the Data() hook passes the MIDI event on to 
+	a more specific hook function: NoteOn(), NoteOff(), SystemExclusive(), and so 
+	on. Calls to these hook functions are serialized -- they will never have to be 
+	re-entrant. They also should not be called from outside the thread that is 
+	invoking them.
+
+	Your subclass can override any of the MIDI event hooks. BMidiLocalConsumer 
+	doesn't provide default implementations for them, so you don't have to call a 
+	hook's default implementation if you override it. For complete control, you can 
+	also override Data().
+
+	Most hook functions take a channel argument. Even though MIDI channels are 
+	really numbered 1 through 16, the hook functions work with channels 0 through 
+	15. The performance time for the event is specified in microseconds relative to 
+	the system time base. A performance time that is 0 (or really any time in the 
+	past) means "play as soon as possible". See the \ref midi2time "introduction" 
+	for more information about timing and consumers.
+
+	The thread driving the consumer's events is a very high priority real time 
+	thread. Events should be handled as quickly as possible (not counting 
+	snoozing). If non-time-critical computation is needed it may be wise to queue 
+	events up for a lower priority thread to handle them external to the main event 
+	thread.
+*/
+
+
+/*!
+	\fn BMidiLocalConsumer::BMidiLocalConsumer(const char *name = NULL)
+	\brief Creates a new local consumer endpoint
+
+	The new endpoint is not visible to other applications until you Register() it.
+
+	You can tell the constructor what the name of the new consumer will be. If you 
+	pass NULL (or use the default argument), then the consumer's name will be an 
+	empty string. It won't be NULL, since endpoint names cannot be NULL.
+
+	There is no guarantee that the endpoint will be successfully created. For 
+	example, the Midi Server may not be running. Therefore, you should always call 
+	IsValid() after creating a new endpoint to make sure that everything went okay. 
+	If not, Release() the object to reclaim memory and abort gracefully.
+
+\code
+MyConsumer* cons = new MyConsumer(...);
+if (!cons->IsValid())
+{
+    cons->Release();
+    ...exit gracefully...
+}
+\endcode
+
+*/
+
+
+/*!
+	\fn void BMidiLocalConsumer::SetLatency(bigtime_t latency)
+	\brief Changes the published latency of the consumer.
+
+	\sa Latency()
+*/
+
+
+/*!
+	\fn int32 BMidiLocalConsumer::GetProducerID()
+	\brief Returns the ID of the producer that most recently sent a MIDI event to 
+		   this consumer.
+
+	You can call this from one of the hooks to determine which producer the event 
+	came from.
+*/
+
+
+/*!
+	\fn void BMidiLocalConsumer::SetTimeout(bigtime_t when, void* data)
+	\brief Requests that the Timeout() hook will be called at some point.
+
+	This method asks the consumer thread to call the Timeout() hook as soon as 
+	possible after the timeout expires. For every call to SetTimeout(), the 
+	Timeout() hook is only called once. Note: the term "timeout" may be a little 
+	misleading; the hook will <I>always</I> be called, even if events are received 
+	in the mean time. Apparently, this facility is handy for dealing with early 
+	events.
+
+	Note that the event thread blocks on the consumer's port as long as no events 
+	arrive. By default no timeout is set, and as a result the thread blocks 
+	forever. Your call to SetTimeout() doesn't change this. The new timeout value 
+	will go into effect the next time the thread tries to read from the port, i.e. 
+	after the first event has been received. If no event ever comes in, the 
+	Timeout() hook will never be called. This also means that you cannot cancel a 
+	timeout once you have set it. To repeat, calling SetTimeout() only takes effect 
+	after at least one new event has been received.
+
+	\param when An absolute time that's measured against the system clock.
+
+	\param data A pointer to a "cookie" that you can pass along to Timeout(). The 
+	data is not copied, so you must ensure that the pointer remains valid until 
+	Timeout() is called. You typically delete the data inside Timeout().
+*/
+
+
+/*!
+	\fn void BMidiLocalConsumer::Timeout(void* data)
+	\brief Hook function that is called per your own request.
+
+	\sa SetTimeout()
+*/
+
+/*!
+	\fn void BMidiLocalConsumer::Data(uchar* data, size_t length, bool atomic,
+		bigtime_t time)
+	\brief Invoked when raw MIDI is received.
+
+	What the default implementation of Data() does depends on the value of atomic. 
+	If atomic is true, the data received comprises a single MIDI event; i.e. one 
+	status byte followed by the appropriate number of data bytes and nothing else. 
+	In this case, Data() calls the event-specific hook function that corresponds to 
+	that status byte. This optimization is used by the Midi Kit to allow faster 
+	dispatch of events generated by the specific Spray functions from 
+	BMidiLocalProducer.
+
+	If atomic is false, Data() ignores the MIDI event. If you want a consumer to 
+	handle non-atomic events, you have to override Data() and program this 
+	yourself. In that case, you probably also want to call the default 
+	implementation to handle the "normal" MIDI events.
+
+	Data() is rarely overridden, but you can override it if you want to. If you do, 
+	remember that the data buffer is owned by the Midi Kit. Do not attempt to 
+	modify or free it, lest you wish to be laughed at by other developers.
+
+	\param data the MIDI event data
+	\param length byte size of the data buffer
+	\param atomic whether the data buffer contains a single complete MIDI event
+	\param time the requested performance time of the event
+
+	\sa BMidiLocalProducer::SprayData()
+*/
+
+
+/*!
+	\fn void BMidiLocalConsumer::NoteOff(uchar channel, uchar note,
+		uchar velocity, bigtime_t time)
+	\brief Invoked when a Note Off event is received.
+
+	\sa BMidiLocalProducer::SprayNoteOff()
+*/
+
+
+/*!
+	\fn void BMidiLocalConsumer::NoteOn(uchar channel, uchar note,
+		uchar velocity, bigtime_t time)
+	\brief Invoked when a Note On event is received.
+
+	\sa BMidiLocalProducer::SprayNoteOn()
+*/
+
+
+/*!
+	\fn void BMidiLocalConsumer::KeyPressure(uchar channel, uchar note,
+		uchar pressure, bigtime_t time)
+	\brief Invoked when a Polyphonic Pressure (Aftertouch) event is received.
+
+	\sa BMidiLocalProducer::SprayKeyPressure()
+*/
+
+
+/*!
+	\fn void BMidiLocalConsumer::ControlChange(uchar channel,
+		uchar controlNumber, uchar controlValue, bigtime_t time)
+	\brief Invoked when a Controller Change event is received.
+
+	\sa BMidiLocalProducer::SprayControlChange()
+*/
+
+
+/*!
+	\fn void BMidiLocalConsumer::ProgramChange(uchar channel,
+		uchar programNumber, bigtime_t time)
+	\brief Invoked when a Program Change event is received.
+
+	\sa BMidiLocalProducer::SprayProgramChange()
+*/
+
+
+/*!
+	\fn void BMidiLocalConsumer::ChannelPressure(uchar channel,
+		uchar pressure, bigtime_t time)
+	\brief Invoked when a Channel Pressure event is received.
+
+	\sa BMidiLocalProducer::SprayChannelPressure()
+*/
+
+
+/*!
+	\fn void BMidiLocalConsumer::PitchBend(uchar channel, uchar lsb,
+		uchar msb, bigtime_t time)
+	\brief Invoked when a Pitch Bend event is received.
+
+	\sa BMidiLocalProducer::SprayPitchBend()
+*/
+
+
+/*!
+	\fn void BMidiLocalConsumer::SystemExclusive(void* data, size_t length,
+		bigtime_t time)
+	\brief Invoked when a System Exclusive event is received.
+
+	The data does not include the sysex start and end control bytes
+	(0xF0 and 0xF7), only the payload of the sysex message.
+
+	The data belongs to the Midi Kit and is only valid for the duration of
+	this event. You may not modify or free it.
+
+	\sa BMidiLocalProducer::SpraySystemExclusive()
+*/
+
+
+/*!
+	\fn void BMidiLocalConsumer::SystemCommon(uchar status, uchar data1,
+		uchar data2, bigtime_t time)
+	\brief Invoked when a System Common event is received.
+
+	Not all data bytes are used for all common events. Unused bytes are
+	set to 0.
+
+	\sa BMidiLocalProducer::SpraySystemCommon()
+*/
+
+
+/*!
+	\fn void BMidiLocalConsumer::SystemRealTime(uchar status, bigtime_t time)
+	\brief Invoked when a Real Time event is received.
+
+	\sa BMidiLocalProducer::SpraySystemRealTime()
+*/
+
+
+/*!
+	\fn void BMidiLocalConsumer::TempoChange(int32 beatsPerMinute, bigtime_t time)
+
+	\brief Invoked when a Tempo Change event is received
+	\sa BMidiLocalProducer::SprayTempoChange()
+*/
+
+
+/*!
+	\fn void BMidiLocalConsumer::AllNotesOff(bool justChannel, bigtime_t time)
+	\brief Not used.
+*/

docs/user/midi2/MidiEndpoint.dox

@@ -0,0 +1,322 @@
+/*!
+	\file MidiEndpoint.h
+	\ingroup midi2
+	\ingroup libbe
+	\brief Defines the Baseclass of all MIDI consumers and producers.
+*/
+
+
+/*!
+	\class BMidiEndpoint
+	\ingroup midi2
+	\ingroup libmidi2
+	\ingroup libbe
+	\brief Base class for all MIDI endpoints.
+
+	BMidiEndpoint is the abstract base class that represents either a
+	producer or consumer endpoint. It may be used to obtain the state, name,
+	properties, or system-wide ID of the object. BMidiEndpoint also provides
+	the ability to change the name and properties of endpoints that were
+	created locally.
+
+	Remember, you cannot call the destructor of BMidiEndpoint and its
+	subclasses directly. Endpoint objects are destructed automatically when
+	their reference count drops to zero. If necessary, the destructor of a
+	local endpoint first breaks off any connections and Unregister()'s the
+	endpoint before it is deleted. However, for good style and bonus points
+	you should really \link BMidiProducer::Disconnect() Disconnect() \endlink
+	and Unregister() the object yourself and not rely on the destructor to
+	do this.
+*/
+
+/*!
+	\fn const char* BMidiEndpoint::Name() const
+	\brief Returns the name of the endpoint.
+
+	The function never returns NULL. If you created a local endpoint by
+	passing a \c NULL name into its constructor (or passing no name,
+	which is the same thing), then Name() will return an empty string,
+	not \c NULL.
+
+	\sa SetName()
+*/
+
+/*!
+	\fn void BMidiEndpoint::SetName(const char* name)
+	\brief Changes the name of the endpoint.
+
+	Names don't have to be unique, but it is recommended that you give any
+	endpoints you publish meaningful and unique names, so users can easily
+	recognize what each endpoint does. There is no limit to the size of
+	endpoint names.
+
+	Even though you can call this function on both remote and local objects,
+	you are only allowed to change the names of local endpoints; SetName()
+	calls on remote endpoints are ignored.
+
+	\param name The new name. If you pass \c NULL the name won't be changed.
+
+	\sa Name()
+*/
+
+/*!
+	\fn int32 BMidiEndpoint::ID() const
+	\brief Returns the ID of the endpoint
+
+	An ID uniquely identifies an endpoint in the system. The ID is a signed
+	32-bit number that is assigned by the Midi Server when the endpoint is
+	created. (So even if a local endpoint is not published, it still has a
+	unique ID.) Valid IDs range from 1 to 0x7FFFFFFF, the largest value an
+	int32 can have. 0 and negative values are <b>not</b> valid IDs.
+*/
+
+
+/*!
+	\fn bool BMidiEndpoint::IsProducer() const
+	\brief Determines whether this endpoint is a BMidiProducer
+
+	If it is, you can use a dynamic_cast to convert this object into a
+	producer:
+
+\code
+if (endp->IsProducer())
+{
+    BMidiProducer* prod = dynamic_cast<BMidiProducer*>(endp);
+
+    ....
+
+}
+\endcode
+
+*/
+
+
+/*!
+	\fn bool BMidiEndpoint::IsConsumer() const
+	\brief Determines whether this endpoint is a BMidiConsumer
+
+	If it is, you can use a dynamic_cast to convert this object into a consumer:
+
+\code
+if (endp->IsConsumer())
+{
+    BMidiConsumer* cons = dynamic_cast<BMidiConsumer*>(endp);
+
+    ....
+
+}
+\endcode
+
+*/
+
+
+/*!
+	\fn bool BMidiEndpoint::IsRemote() const
+	\brief Determines whether this endpoint is a proxy for a remote object.
+
+	An endpoint is "remote" when it is created by another application.
+	Obviously, the remote object is Register()'ed as well, otherwise you would
+	not be able to see it.
+*/
+
+
+/*!
+	\fn bool BMidiEndpoint::IsLocal() const
+	\brief Determines whether this endpoint represents a local object
+
+	An endpoint is "local" when it is created by this application; in other
+	words, a BMidiLocalConsumer or BMidiLocalProducer.
+*/
+
+
+/*!
+	\fn bool BMidiEndpoint::IsPersistent() const
+	\brief Not used.
+
+	The purpose of this function is unclear, and as a result it doesn't do
+	anything in the Haiku Midi Kit implementation.
+
+	\return \c false always.
+*/
+
+
+/*!
+	\fn bool BMidiEndpoint::IsValid() const
+	\brief Determines whether the endpoint still exists.
+
+	Suppose you obtained a proxy object for a remote endpoint by querying the
+	BMidiRoster. What if the application that published this endpoint quits,
+	or less drastically, Unregister()'s that endpoint? Even though you still
+	have a BMidiEndpoint proxy object, the real endpoint no longer exists.
+	You can use IsValid() to check for this.
+
+	Don't worry, operations on invalid objects, such as GetProperties(), will
+	return an error code (typically B_ERROR), but not cause a crash. Local
+	objects are always are considered to be valid, even if you did not
+	Register() them. (The only time a local endpoint is not valid is when there
+	was a problem constructing it.)
+
+	If the application that created the remote endpoint crashes, then there is
+	no guarantee that the Midi Server immediately recognizes this. In that
+	case, IsValid() may still return true. Eventually, the stale endpoint will
+	be removed from the roster, though. From then on, IsValid() correctly
+	returns \c false.
+*/
+
+
+/*!
+	\fn status_t BMidiEndpoint::Acquire()
+	\brief Increments the endpoint's reference count
+
+	Each BMidiEndpoint has a reference count associated with it, so that
+	BMidiRoster can do proper bookkeeping. Acquire() increments this reference
+	count, and Release() decrements it. Once the count reaches zero, the
+	endpoint is deleted.
+
+	When you are done with the endpoint, whether local or remote, you should
+	always Release() it!
+
+	Upon construction, local endpoints start with a reference count of 1. Any
+	objects you obtain from BMidiRoster using the NextXXX() or FindXXX()
+	functions have their reference counts incremented in the process. If you
+	forget to call  Release(), the objects won't be properly cleaned up and
+	you'll make a fool out of yourself.
+
+	After you Release() an object, you are advised not to use it any further.
+	If you do, your app will probably crash. That also happens if you Release()
+	an object too many times.
+
+	Typically, you don't need to call Acquire(), unless you have two disparate
+	parts of your application working with the same endpoint, and you don't
+	want to have to keep track of who needs to Release() the endpoint. Now you
+	simply have both of them release it.
+
+	\return Always returns B_OK
+
+	\sa Release()
+*/
+
+/*!
+	\fn status_t BMidiEndpoint::Release()
+	\brief Decrements the endpoint's reference count.
+
+	\return Always returns B_OK
+
+	\sa Acquire()
+*/
+
+/*!
+	\fn status_t BMidiEndpoint::Register()
+	\brief Publishes the endpoint on the roster
+
+	MIDI objects created by an application are invisible to other applications
+	until they are published. To publish an object use the Register() method.
+	The corresponding Unregister() method will cause an object to once again
+	become invisible to remote applications.
+
+	BMidiRoster also has Register() and Unregister() methods. You may also use
+	those methods  to publish or hide your endpoints; both do the same thing.
+
+	Although it is considered bad style, calling Register() on local endpoints
+	that are already registered won't mess things up. The Midi Server will
+	simply ignore your request. Likewise for Unregister()'ing more than once.
+	Attempts to Register() or Unregister() remote endpoints will fail, of
+	course.
+
+	If you are \link BMidiRoster::StartWatching() watching \endlink, you will
+	<b>not</b> receive notifications for any local endpoints you register or
+	unregister. Of course, other applications <I>will</I> be notified about
+	your endpoints.
+
+	Existing connections will not be broken when an object is unregistered,
+	but future remote connections will be denied. When objects are destroyed,
+	they automatically become unregistered.
+
+	\returns B_OK on success, or an error code (typically \c B_ERROR) if
+			 something went wrong.
+
+	\sa Unregister()
+*/
+
+/*!
+	\fn status_t BMidiEndpoint::Unregister()
+	\brief Hides the endpoint from the roster/
+
+	\sa Register()
+*/
+
+/*!
+	\fn status_t BMidiEndpoint::SetProperties(const BMessage* props)
+	\brief Changes the properties of the endpoint
+
+	Endpoints can have properties, which is any kind of information that
+	might be useful to associate with a MIDI object. The properties are
+	stored in a BMessage.
+
+	Usage example:
+
+\code
+BMessage props;
+if (endpoint->GetProperties(&props) == B_OK)
+{
+    ...add data to the message...
+    endpoint->SetProperties(&props);
+} 
+\endcode
+
+	You are only allowed to call SetProperties() on a local object.
+
+	Properties should follow a protocol, so different applications will know
+	how to read each other's properties. The current protocol is very limited
+	-- it only allows you to associate icons with your endpoints. Be planned
+	to publish a more complete protocol that included additional information,
+	such as vendor/model names, copyright/version info, category, etc., but
+	they never got around to it.
+
+	<TABLE BORDER="1">
+	<TR><TD>property</TD><TD>Vector icon (raw data)</TD></TR>
+	<TR><TD>field name</TD><TD>"icon"</TD></TR>
+	<TR><TD>field type</TD><TD>'VICN'</TD></TR>
+	</TABLE>
+
+	This vector icon is available under Haiku only, and comes as raw data,
+	not a BBitmap. Before being able to display it, you first must render
+	the vector icon in the size of your choice.
+
+	<TABLE BORDER="1">
+	<TR><TD>property</TD><TD>Large (32x32) icon</TD></TR>
+	<TR><TD>field name</TD><TD>"be:large_icon"</TD></TR>
+	<TR><TD>field type</TD><TD>'ICON'</TD></TR>
+	</TABLE>
+
+	<TABLE BORDER="1">
+	<TR><TD>property</TD><TD>Small (16x16) icon</TD></TR>
+	<TR><TD>field name</TD><TD>"be:mini_icon"</TD></TR>
+	<TR><TD>field type</TD><TD>'MICN'</TD></TR>
+	</TABLE>
+
+	The MidiUtil package (downloadable from the OpenBeOS website) contains a
+	number of convenient functions to associate icons with endpoints, so you
+	don't have to write that code all over again.
+
+	\sa GetProperties()
+*/
+
+/*!
+	\fn status_t BMidiEndpoint::GetProperties(BMessage* props) const
+	\brief Reads the properties of the endpoint
+
+	Usage example:
+
+\code
+BMessage props;
+if (endpoint->GetProperties(&props) == B_OK) 
+{
+    ...examine the contents of the message...
+}
+\endcode
+
+	Note that GetProperties() overwrites the contents of your BMessage.
+
+	\sa SetProperties()
+*/

docs/user/midi2/MidiProducer.dox

@@ -0,0 +1,359 @@
+/*!
+	\file MidiProducer.h
+	\ingroup midi2
+	\ingroup libbe
+	\brief Defines producer classes for the MIDI Kit.
+*/
+
+
+/*!
+	\class BMidiProducer MidiProducer.h
+	\ingroup midi2
+	\ingroup libmidi2
+	\ingroup libbe
+	\brief Streams MIDI events to connected consumers.
+
+	A producer is an object that generate a stream of MIDI events. Each
+	producer has a list of BMidiConsumer objects to which it is connected,
+	and may be asked to connect to or disconnect from a BMidiConsumer. A
+	producer can spray its  events to multiple consumers at the same time.
+	A BMidiProducer either represents a local producer, i.e. a class extending
+	from BMidiLocalProducer, or is a proxy for a remote object published by
+	another app.
+*/
+
+
+/*!
+	\fn status_t BMidiProducer::Connect(BMidiConsumer* cons)
+	\brief Connects a consumer to this producer.
+
+	Establishes a connection between this producer and the specified consumer
+	endpoint. From now on, any events that this producer sprays will be sent 
+	to that consumer. You may connect multiple consumers to a producer.
+
+	\return B_OK on success, or an error code when the connection could not be
+		established. If the consumer is a proxy for a remote object and that
+		object no longer exists, Connect() returns B_ERROR. It also returns
+		\c B_ERROR if you try to connect the same producer and consumer more
+		than once.
+
+	\sa Disconnect()
+*/
+
+
+/*!
+	\fn status_t BMidiProducer::Disconnect(BMidiConsumer* cons)
+	\brief Disconnects a consumer from this producer.
+
+	Terminates the connection between this producer and the specified consumer
+	endpoint. From now on, any events that this producer sprays no longer go
+	to that consumer.
+
+	\return B_OK on success, or an error code if there was no connection to break
+	\sa Connect()
+*/
+
+
+/*!
+	\fn bool BMidiProducer::IsConnected(BMidiConsumer* cons) const
+	\brief Determines whether a consumer is connected to this producer.
+
+	\sa Connect()
+	\sa Disconnect()
+*/
+
+
+/*!
+	\fn BList* BMidiProducer::Connections() const
+	\brief Returns a list with all connected consumers.
+
+	Returns a BList with pointers to BMidiEndpoint objects for all consumers
+	that are connected to this producer. You can examine the contents of the
+	list as follows:
+\code
+BList* list = prod->Connections();
+for (int32 t = 0; t < list->CountItems(); ++t)
+{
+    BMidiEndpoint* endp = (BMidiEndpoint*) list->ItemAt(t);
+    ...do stuff...
+    endp->Release();  // yes, here too!
+}
+delete list;
+\endcode
+	Every time you call this function, a new BList is allocated. The caller
+	(that is you) is responsible for freeing this list. The BMidiEndpoint
+	objects in the list have their reference counts bumped, so you need to
+	Release() them before you delete the list or they will go all leaky on
+	you.
+*/
+
+
+/*!
+	\class BMidiLocalProducer MidiProducer.h
+	\ingroup midi2
+	\ingroup libmidi2
+	\ingroup libbe
+	\brief A producer endpoint that is created by your own application.
+
+	You create a BMidiLocalProducer if you want your application to send MIDI
+	events. You use the various spray functions to send events to all connected
+	consumers. If no consumers are connected to the producer, any calls to the
+	spray functions are ignored.
+
+	Most spray functions accept a channel argument. Even though MIDI channels are
+	really numbered 1 through 16, the spray functions work with channels 0 through
+	15. You can also specify the performance time for the event using the time
+	argument. Specify 0 (or any time in the past) to perform the event "now", i.e.
+	as soon as possible. You can also schedule events to be performed in the
+	future, by passing a time such as system_time() + 5000000, which means 5
+	seconds from now.
+
+	Unlike BMidiLocalConsumer, which should be subclassed almost always, you hardly
+	ever need to derive a class from BMidiLocalProducer. The only reason for
+	subclassing is when you need to know when the producer gets connected or
+	disconnected.
+
+	Also unlike consumers, local producers have no thread of control directly
+	associated with them. If you want to send out the MIDI events from a different
+	thread, you will have to create one yourself.
+*/
+
+
+/*!
+	\fn BMidiLocalProducer::BMidiLocalProducer(const char *name = NULL)
+	\brief Creates a new local producer endpoint.
+
+	The new endpoint is not visible to other applications until you Register() it.
+	You can tell the constructor what the name of the new producer will be. If you
+	pass NULL (or use the default argument), then the producer's name will be an
+	empty string. It won't be NULL, since endpoint names cannot be NULL.
+	There is no guarantee that the endpoint will be successfully created. For
+	example, the Midi Server may not be running. Therefore, you should always call
+	IsValid() after creating a new endpoint to make sure that everything went okay.
+	If not, Release() the object to reclaim memory and abort gracefully.
+\code
+BMidiLocalProducer* prod = new BMidiLocalProducer(...);
+if (!prod->IsValid())
+{
+    prod->Release();
+    ...exit gracefully...
+}
+\endcode
+*/
+
+
+/*!
+	\fn void BMidiLocalProducer::Connected(BMidiConsumer* cons)
+	\brief Invoked when a new consumer is connected to this producer
+
+	Although typical notifications (i.e. from BMidiRoster's "watching" facility)
+	are only sent if it is some other app that is performing the operation,
+	Connected() is also called if you are making the connection yourself.
+	If you override this hook, you don't have to call the default implementation,
+	because that does nothing.
+
+	\param cons The newly connected consumer. The reference count of the
+		consumer object is not increased, so you should not Release() it.
+		However, if you want to keep track of the consumer beyond this
+		function, you should first Acquire() it, and Release() it when you
+		are done.
+
+	\sa Disconnected()
+*/
+
+
+/*!
+	\fn void BMidiLocalProducer::Disconnected(BMidiConsumer* cons)
+	\brief Invoked when a consumer is disconnected from this producer.
+
+	\sa Connected()
+*/
+
+
+/*!
+	\fn void BMidiLocalProducer::SprayData(void* data, size_t length,
+		bool atomic = false, bigtime_t time = 0) const
+	\brief Sends raw MIDI data downstream to all connected consumers.
+
+	Typically you won't have to call SprayData(); the other spray functions
+	will do just fine. If you do call it, remember that you retain ownership
+	of the data and that you are responsible for freeing it at some point.
+	(Even though data is not declared const, the function does not change it.)
+	With atomic set to false, you can send a MIDI message in segments (perhaps
+	for a large sysex dump). However, when you do this, you are on your own.
+	The Midi Kit only tags the data as being non-atomic, but offers no]
+	additional support.
+
+	The default implementation of BMidiLocalConsumer completely ignores such
+	events. To handle non-atomic MIDI data, you should override the
+	BMidiLocalConsumer::Data() hook and process the MIDI event yourself. All of
+	BMidiLocalProducer's other spray functions always send atomic data.
+
+	\param data the MIDI event data.
+	\param length byte size of the data buffer.
+	\param atomic whether the data buffer contains a single complete
+		   MIDI event.
+	\param time the required performance time of the event.
+
+	\sa BMidiLocalConsumer::Data()
+*/
+
+
+/*!
+	\fn void BMidiLocalProducer::SprayNoteOff(uchar channel, uchar note,
+		uchar velocity, bigtime_t time = 0) const
+	\brief Sends a Note Off event to all connected consumers.
+
+	\sa BMidiLocalConsumer::NoteOff()
+*/
+
+
+/*!
+	\fn void BMidiLocalProducer::SprayNoteOn(uchar channel, uchar note,
+		uchar velocity, bigtime_t time = 0) const
+	\brief Sends a Note On event to all connected consumers.
+
+	\sa BMidiLocalConsumer::NoteOn()
+*/
+
+
+/*!
+	\fn void BMidiLocalProducer::SprayKeyPressure(uchar channel, uchar note,
+		uchar pressure, bigtime_t time = 0) const
+	\brief Sends a Polyphonic Pressure (Aftertouch) event to all connected
+		   consumers.
+
+	\sa BMidiLocalConsumer::KeyPressure()
+*/
+
+
+/*!
+	\fn void BMidiLocalProducer::SprayControlChange(uchar channel,
+		uchar controlNumber, uchar controlValue, bigtime_t time = 0) const
+	\brief Sends a Controller Change event to all connected consumers.
+
+	\sa Midi2Defs.h
+	\sa BMidiLocalConsumer::ControlChange()
+*/
+
+
+/*!
+	\fn void BMidiLocalProducer::SprayProgramChange(uchar channel,
+		uchar programNumber, bigtime_t time = 0) const
+	\brief Sends a Program Change event to all connected consumers.
+
+	\sa BMidiLocalConsumer::ProgramChange()
+*/
+
+
+/*!
+	\fn void BMidiLocalProducer::SprayChannelPressure(uchar channel,
+		uchar pressure, bigtime_t time = 0) const
+	\brief Sends a Channel Pressure event to all connected consumers.
+
+	\sa BMidiLocalConsumer::ChannelPressure()
+*/
+
+
+/*!
+	\fn void BMidiLocalProducer::SprayPitchBend(uchar channel, uchar lsb,
+		uchar msb, bigtime_t time = 0) const
+	\brief Sends a Pitch Bend event to all connected consumers.
+
+	\sa BMidiLocalConsumer::PitchBend()
+*/
+
+
+/*!
+	\fn void BMidiLocalProducer::SpraySystemExclusive(void* data,
+		size_t length, bigtime_t time = 0) const
+	\brief Sends a System Exclusive event to all connected consumers.
+
+	You retain ownership of the data and are responsible for freeing it. Even
+	though data is not declared const, the function does not change it. Even
+	though the amount of data may be quite large, this function always sends
+	sysex messages as an atomic block of data.
+
+	\sa BMidiLocalConsumer::SystemExclusive()
+*/
+
+
+/*!
+	\fn void BMidiLocalProducer::SpraySystemCommon(uchar status,\
+		uchar data1, uchar data2, bigtime_t time = 0) const
+	\brief Sends a System Common event to the connected consumers.
+
+	The status byte must be one of the following:
+	<table border="1">
+		<tr>
+			<td>0xF1</td>
+			<td>\c B_MIDI_TIME_CODE</td>
+			<td>data1 only</td>
+		</tr>
+		<tr>
+			<td>0xF2</td>
+			<td>\c B_SONG_POSITION</td>
+			<td>data1 and data2</td>
+		</tr>
+		<tr>
+			<td>0xF3</td>
+			<td>\c B_SONG_SELECT</td>
+			<td>data1 only</td>
+		</tr>
+		<tr>
+			<td>0xF5</td>
+			<td>\c B_CABLE_MESSAGE</td>
+			<td>data1 only</td>
+		</tr>
+		<tr>
+			<td>0xF6</td>
+			<td>\c B_TUNE_REQUEST</td>
+			<td>no data</td>
+		</tr>
+		<tr>
+			<td>0xF7</td>
+			<td>\c B_SYS_EX_END</td>
+			<td>no data</td>
+		</tr>
+	</table>
+
+	\sa BMidiLocalConsumer::SystemCommon()
+*/
+
+
+/*!
+	\fn void BMidiLocalProducer::SpraySystemRealTime(uchar status,
+		bigtime_t time = 0) const
+	\brief Sends a Real Time event to the connected consumers.
+
+	The status byte must be one of the following:
+	<table border="1">
+		<tr><td>0xf8</td><td>\c B_TIMING_CLOCK</td></tr>
+		<tr><td>0xfa</td><td>\c B_START</td></tr>
+		<tr><td>0xfb</td><td>\c B_CONTINUE</td></tr>
+		<tr><td>0xfc</td><td>\c B_STOP</td></tr>
+		<tr><td>0xfe</td><td>\c B_ACTIVE_SENSING</td></tr>
+		<tr><td>0xff</td><td>\c B_SYSTEM_RESET</td></tr>
+	</table>
+
+	Because of their high priority, the MIDI specification allows real time
+	messages to "interleave" with other MIDI messages. A large sysex dump, for
+	example, may be interrupted by a real time event. The Midi Kit, however,
+	doesn't care. If you (or another producer) have just sent a big system
+	exclusive to a consumer, any following real time message will simply have
+	to wait until the consumer has dealt with the sysex.
+
+	\sa BMidiLocalConsumer::SystemRealTime()
+*/
+
+
+/*!
+	\fn void BMidiLocalProducer::SprayTempoChange(int32 bpm,
+		bigtime_t time = 0) const
+	\brief Sends a Tempo Change event to the connected consumers.
+
+	This kind of Tempo Change event is not really part of the MIDI spec,
+	rather it is an extension from the SMF (Standard MIDI File) format.
+
+	\sa BMidiLocalConsumer::TempoChange()
+*/

docs/user/midi2/MidiRoster.dox

@@ -0,0 +1,417 @@
+/*!
+	\file MidiRoster.h
+	\ingroup midi2
+	\ingroup libbe
+	\brief Defines the heart of the MIDI Kit: the MIDI Roster.
+*/
+
+
+/*!
+	\enum BMidiOp
+	\ingroup midi2
+	\brief Defines the status codes for MIDI Server notification messages.
+
+	These codes are used when you request notification as in
+	BMidiRoster::StartWatching(). Check against these codes to determine what
+	is happening. See the StartWatching() method for a more complete
+	description of the codes and their meaning.
+*/
+
+
+/*!
+	\var B_MIDI_EVENT
+	\brief BMessage identifier of MIDI messages.
+*/
+
+
+/*!
+	\class BMidiRoster MidiRoster.h
+	\ingroup midi2
+	\ingroup libmidi2
+	\ingroup libbe
+	\brief Interface to the system-wide Midi Roster.
+
+	BMidiRoster allows you to find available MIDI consumer and producer
+	objects. You can locate these objects using the iterative NextEndpoint(),
+	NextProducer(), and NextConsumer() methods or by requesting notification
+	messages to be sent with StartWatching(). Notification messages may
+	contain object IDs which can be resolved using the FindEndpoint(),
+	FindProducer(), and FindConsumer() methods.
+
+	The constructor and destructor of BMidiRoster are private, which means
+	that you cannot create or delete your own BMidiRoster objects. Every
+	application can have only one instance of BMidiRoster, which is
+	automatically created the very first time you use a Midi Kit function.
+	You can call BMidiRoster's functions like this:
+\code
+producer = BMidiRoster::FindProducer(someID);
+\endcode
+Or using the slightly more annoying:
+\code
+BMidiRoster* roster = BMidiRoster::MidiRoster();
+if (roster != NULL)
+{
+    producer = roster->FindProducer(someID);
+}
+\endcode
+*/
+
+
+/*!
+	\fn BMidiEndpoint* BMidiRoster::NextEndpoint(int32* id)
+	\brief Returns the next endpoint from the roster
+
+	The "next endpoint" means: the endpoint with the ID that follows \a id.
+	So if you set id to 3, the first possible endpoint it returns is
+	endpoint 4. No endpoint can have ID 0, so passing 0 gives you the first
+	endpoint. If you pass \c NULL instead of an ID, NextEndpoint() always
+	returns \c NULL. When the function returns, it sets \a id to the ID of the
+	endpoint that was found. If no more endpoints exist, NextEndpoint()
+	returns \c NULL and id is not changed. NextEndpoint() does <b>not</b>
+	return locally created endpoints, even if they are Register()'ed.
+
+	Usage example:
+\code
+int32 id = 0;
+BMidiEndpoint* endp;
+while ((endp = BMidiRoster::NextEndpoint(&id)) != NULL)
+{
+    ... do something with endpoint ...
+    endp->Release();  // don't forget!
+}
+\endcode
+	Remember that NextEndpoint() bumps the endpoint's reference count, so you
+	should always \link BMidiEndpoint::Release() Release() \endlink it when
+	you are done.
+*/
+
+
+/*!
+	\fn BMidiProducer* BMidiRoster::NextProducer(int32* id)
+	\brief Returns the next producer from the roster.
+
+	Like NextEndpoint(), but only returns producer endpoints.
+
+	\sa NextConsumer
+	\sa NextEndpoint
+*/
+
+
+/*!
+	\fn BMidiConsumer* BMidiRoster::NextConsumer(int32* id)
+	\brief Returns the next consumer from the roster.
+
+	Like NextEndpoint(), but only returns consumer endpoints.
+
+	\sa NextProducer
+	\sa NextEndpoint
+*/
+
+
+/*!
+	\fn BMidiEndpoint* BMidiRoster::FindEndpoint(int32 id,
+		bool localOnly = false)
+	\brief Returns the endpoint with the specified \a id.
+
+	FindEndpoint() will always find <b>any</b> local endpoints created by this
+	application; they do not have to be published with Register() first. If
+	localOnly is false, FindEndpoint() also looks at remote endpoints,
+	otherwise only local endpoints will be resolved. Returns NULL if no such
+	endpoint could be found.
+
+	You should use a dynamic_cast to convert the BMidiEndpoint into a producer
+	or consumer:
+\code
+BMidiEndpoint* endp = ...;
+BMidiProducer* prod = NULL;
+BMidiConsumer* cons = NULL;
+if (endp->IsProducer())
+{
+    prod = dynamic_cast<BMidiProducer*>(endp);
+}
+else if (endp->IsConsumer())
+{
+    cons = dynamic_cast<BMidiConsumer*>(endp);
+}
+\endcode
+
+	Remember that FindEndpoint() increments the endpoint's reference count,
+	so you should always \link BMidiEndpoint::Release() Release() \endlink
+	an endpoint when you are done with it:
+\code
+BMidiEndpoint* endp = BMidiRoster::FindEndpoint(someID);
+if (endp != NULL)
+{
+    ...do stuff with the endpoint...
+    endp->Release();
+}
+\endcode
+*/
+
+
+/*!
+	\fn BMidiProducer* BMidiRoster::FindProducer(int32 id,
+		bool localOnly = false)
+	\brief Finds the producer with the specified \a id.
+
+	Like FindEndpoint(), but only looks for producer endpoints. Returns
+	\c NULL if no endpoint with that ID exists, or if that endpoint is not
+	a producer.
+
+	\sa FindConsumer
+	\sa FindEndpoint
+*/
+
+
+/*!
+	\fn BMidiConsumer* BMidiRoster::FindConsumer(int32 id,
+		bool localOnly = false)
+	\brief Finds the consumer with the specified \a id.
+
+	Like FindEndpoint(), but only looks for consumer endpoints. Returns
+	\c NULL if no endpoint with that ID exists, or if that endpoint is not
+	a consumer.
+
+	\sa FindProducer
+	\sa FindEndpoint
+*/
+
+
+/*!
+	\fn void BMidiRoster::StartWatching(const BMessenger* msngr)
+	\brief Start receiving notifications from the Midi Roster
+
+	When you start watching, BMidiRoster sends you notifications for all
+	currently \b published \c remote endpoints, and all the current
+	connections between them. (At this point, BMidiRoster does not let you
+	know about connections between unpublished endpoints, nor does it tell
+	you anything about your local endpoints, even though they may be
+	published.)
+
+	Thereafter, you'll receive notifications any time something important
+	happens to an object. The application that performs these operations is
+	itself not notified. The assumption here is that you already know about
+	these changes, because you are the one that is performing them.
+
+	The notifications are BMessages with code B_MIDI_EVENT. You specify the
+	BMessenger that will be used to send these messages. Each message contains
+	a field called be:op that describes the type of notification.
+
+	The "registered" and "unregistered" notifications are sent when a remote
+	endpoint Register()'s or Unregister()'s, respectively. You don't receive
+	these notifications when you register or unregister your local endpoints,
+	but the other apps will.
+
+	<table border="1">
+		<tr>
+			<td>be:op</td>
+			<td>int32</td>
+			<td>\c B_MIDI_REGISTERED</td>
+		</tr>
+		<tr>
+			<td>be:id</td>
+			<td>int32</td>
+			<td>id of the endpoint</td>
+		</tr>
+		<tr>
+			<td>be:type</td>
+			<td>string</td>
+			<td>"producer" or "consumer"</td>
+		</tr>
+	</table>
+	<table border="1">
+		<tr>
+			<td>be:op</td>
+			<td>int32</td>
+			<td>\c B_MIDI_UNREGISTERED</td>
+		</tr>
+		<tr>
+			<td>be:id</td>
+			<td>int32</td>
+			<td>id of the endpoint</td>
+		</tr>
+		<tr>
+			<td>be:type</td>
+			<td>string</td>
+			<td>"producer" or "consumer"</td>
+		</tr>
+	</table>
+
+	The "connected" and "disconnected" notifications are sent when a consumer
+	\link BMidiProducer::Connect() Connect()\endlink's to a producer, or when
+	they \link BMidiProducer::Disconnect() Disconnect() \endlink. You will
+	receive these notifications when \b any two endpoints connect or
+	disconnect, even if they are not published. (The purpose of which is
+	debatable.) You won't receive the notifications if you are the one making
+	the connection, even if both endpoints are remote. You \b will be notified
+	when another app connects one of your published endpoints.
+	<table border="1">
+		<tr>
+			<td>be:op</td>
+			<td>\c int32</td>
+			<td>\c B_MIDI_CONNECTED</td>
+		</tr>
+		<tr>
+			<td>be:producer</td>
+			<td>\c int32</td>
+			<td>id of the connector</td>
+		</tr>
+		<tr>
+			<td>be:consumer</td>
+			<td>\c int32</td>
+			<td>id of the connectee</td>
+		</tr>
+	</table>
+
+	<table border="1">
+		<tr>
+			<td>be:op</td>
+			<td>\c int32</td>
+			<td>\c B_MIDI_DISCONNECTED</td>
+		</tr>
+		<tr>
+			<td>be:producer</td>
+			<td>\c int32</td>
+			<td>id of the connector</td>
+		</tr>
+		<tr>
+			<td>be:consumer</td>
+			<td>int32</td>
+			<td>id of the connectee</td>
+		</tr>
+	</table>
+
+	the following notifications are sent when an endpoint's attributes are
+	changed. you receive these notifications only if another application is
+	changing one of its published endpoints.
+
+	<table border="1">
+		<tr>
+			<td>be:op</td>
+			<td>\c int32</td>
+			<td>\c B_MIDI_CHANGED_NAME</td>
+		</tr>
+		<tr>
+			<td>be:id</td>
+			<td>\c int32</td>
+			<td>id of the endpoint</td>
+		</tr>
+		<tr>
+			<td>be:type</td>
+			<td>string</td>
+			<td>"producer" or "consumer"</td>
+		</tr>
+		<tr>
+			<td>be:name</td>
+			<td>string</td>
+			<td>the endpoint's new name</td>
+		</tr>
+	</table>
+
+	<table border="1">
+		<tr>
+			<td>be:op</td>
+			<td>\c int32</td>
+			<td>\c B_MIDI_CHANGED_LATENCY</td>
+		</tr>
+		<tr>
+			<td>be:id</td>
+			<td>\c int32</td>
+			<td>id of the endpoint</td>
+		</tr>
+		<tr>
+			<td>be:type</td>
+			<td>string</td>
+			<td>"producer" or "consumer"</td>
+		</tr>
+		<tr>
+			<td>be:latency</td>
+			<td>int64</td>
+			<td>the new latency (microseconds)</td>
+		</tr>
+	</table>
+
+	<table border="1">
+		<tr>
+			<td>be:op</td>
+			<td>int32</td>
+			<td>\c B_MIDI_CHANGED_PROPERTIES</td>
+		</tr>
+		<tr>
+			<td>be:id</td>
+			<td>\c int32</td>
+			<td>id of the endpoint</td>
+		</tr>
+		<tr>
+			<td>be:type</td>
+			<td>string</td>
+			<td>"producer" or "consumer"</td>
+		</tr>
+		<tr>
+			<td>be:properties</td>
+			<td>bmessage</td>
+			<td>the new properties</td>
+		</tr>
+	</table>
+
+	Typical usage example:
+
+\code
+void MyView::AttachedToWindow()
+{
+    BMessenger msgr(this);
+    BMidiRoster::StartWatching(&msgr);
+}
+void MyView::MessageReceived(BMessage* msg)
+{
+    switch (msg->what)
+    {
+        case B_MIDI_EVENT:
+            HandleMidiEvent(msg);
+            break;
+        default:
+            super::MessageReceived(msg);
+            break;
+    }
+}
+\endcode
+
+	For the possible midi options, see #BMidiOp
+*/
+
+
+/*!
+	\fn void BMidiRoster::StopWatching()
+	\brief Stop receiving notifications from the Midi Roster.
+
+	\sa StartWatching()
+*/
+
+
+/*!
+	\fn status_t BMidiRoster::Register(BMidiEndpoint* object)
+	\brief Publishes an endpoint to other applications.
+
+	Calls BMidiEndpoint's \link BMidiEndpoint::Register() Register() \endlink
+	method to publish an endpoint, which makes it visible to other
+	applications.
+*/
+
+
+/*!
+	\fn status_t BMidiRoster::Unregister(BMidiEndpoint* object)
+	\brief Hides an endpoint from other applications.
+
+	Calls BMidiEndpoint's
+	\link BMidiEndpoint::Unregister() Unregister() \endlink method to hide
+	a previously published endpoint from other applications.
+*/
+
+
+/*!
+	\fn BMidiRoster* BMidiRoster::MidiRoster()
+	\brief Returns a pointer to the only instance of BMidiRoster.
+
+	There is no real reason use this function, since all BMidiRoster's public
+	function are static.
+*/

docs/user/midi2/midiconsumer.dox

@@ -1,291 +0,0 @@
-/*!
-\class BMidiConsumer MidiConsumer.h
-\ingroup midi2
-\ingroup libmidi2
-\brief Receives MIDI events from a producer
-
-A consumer is an object that knows how to deal with incoming MIDI events. A 
-consumer can be connected to multiple producers at the same time. There is no 
-way to find out which producers are connected to this consumer just by looking 
-at the BMidiConsumer object; you will have to consult BMidiRoster for that.
-
-A BMidiConsumer either represents a local consumer, i.e. a class extending from 
-BMidiLocalConsumer, or is a proxy for a remote object published by another app. 
-
-*/
-
-/*!
-\fn bigtime_t BMidiConsumer::Latency() const
-\brief Returns the latency of this consumer
-
-The latency is measured in microseconds. Producers should attempt to get MIDI 
-events to this consumer by <I>(when - latency)</I>. You do this by subtracting 
-the latency from the performance time when you spray the events (provided that 
-you spray these events ahead of time, of course).
-
-You cannot <I>set</I> the latency on a BMidiConsumer, only on a 
-BMidiLocalConsumer.
-
-The latency issue gets slightly more complicated when multiple endpoints are 
-chained together, as in the following picture:
-
-\verbatim
-+-------+     +-------------+     +-------+
-|       |     |             |     |       |
-| prodA |---->| consB prodB |---->| consC |
-|       |     |             |     |       |
-+-------+     +-------------+     +-------+
-  appA          appB (filter)       appC
-\endverbatim
-
-Suppose consC has 200ms latency, and consB has 100ms latency. If consB simply 
-reports 100ms, then prodA will schedule its events for (t - 100), which is 
-really 200ms too late. (Of course, producers send out their events as soon as 
-possible, so depending on the load of the system, everything may work out just 
-fine.)
-
-ConsB should report the latency of the consumer that is hooked up to its 
-output, consC, in addition to its own latency. In other words, the full 
-downstream latency. So, the reported latency in this case would be 300ms. This 
-also means that appB should change the latency of consB when prodB makes or 
-breaks a connection, and when consC reports a latency change. (If multiple 
-consumers are connected to prodB, you should take the slowest one.) 
-Unfortunately, the Midi Kit provides no easy mechanism for doing any of this, 
-so you are on your own here.
-
-*/
-
-/*!
-\class BMidiLocalConsumer MidiConsumer.h
-\ingroup midi2
-\ingroup libmidi2
-\brief A consumer endpoint that is created by your own application
-
-If you want to create a consumer that reacts to MIDI events, you should 
-subclass BMidiLocalConsumer.
-
-Each local consumer has its own thread that receives and dispatches the MIDI 
-events. Whenever MIDI data arrives, the Data() hook passes the MIDI event on to 
-a more specific hook function: NoteOn(), NoteOff(), SystemExclusive(), and so 
-on. Calls to these hook functions are serialized -- they will never have to be 
-re-entrant. They also should not be called from outside the thread that is 
-invoking them.
-
-Your subclass can override any of the MIDI event hooks. BMidiLocalConsumer 
-doesn't provide default implementations for them, so you don't have to call a 
-hook's default implementation if you override it. For complete control, you can 
-also override Data().
-
-Most hook functions take a channel argument. Even though MIDI channels are 
-really numbered 1 through 16, the hook functions work with channels 0 through 
-15. The performance time for the event is specified in microseconds relative to 
-the system time base. A performance time that is 0 (or really any time in the 
-past) means "play as soon as possible". See the \ref midi2time "introduction" 
-for more information about timing and consumers.
-
-The thread driving the consumer's events is a very high priority real time 
-thread. Events should be handled as quickly as possible (not counting 
-snoozing). If non-time-critical computation is needed it may be wise to queue 
-events up for a lower priority thread to handle them external to the main event 
-thread.
-
-*/
-
-/*!
-\fn BMidiLocalConsumer::BMidiLocalConsumer(const char *name = NULL)
-\brief Creates a new local consumer endpoint
-
-The new endpoint is not visible to other applications until you Register() it.
-
-You can tell the constructor what the name of the new consumer will be. If you 
-pass NULL (or use the default argument), then the consumer's name will be an 
-empty string. It won't be NULL, since endpoint names cannot be NULL.
-
-There is no guarantee that the endpoint will be successfully created. For 
-example, the Midi Server may not be running. Therefore, you should always call 
-IsValid() after creating a new endpoint to make sure that everything went okay. 
-If not, Release() the object to reclaim memory and abort gracefully.
-
-\code
-MyConsumer* cons = new MyConsumer(...);
-if (!cons->IsValid())
-{
-    cons->Release();
-    ...exit gracefully...
-}
-\endcode
-
-*/
-
-/*!
-\fn void BMidiLocalConsumer::SetLatency(bigtime_t latency)
-\brief Changes the published latency of the consumer
-\sa Latency()
-*/
-
-/*!
-\fn int32 BMidiLocalConsumer::GetProducerID()
-\brief Returns the ID of the producer that most recently sent a MIDI event to 
-this consumer
-
-You can call this from one of the hooks to determine which producer the event 
-came from.
-
-*/
-
-/*!
-\fn void BMidiLocalConsumer::SetTimeout(bigtime_t when, void* data)
-\brief Requests that the Timeout() hook will be called at some point
-
-This method asks the consumer thread to call the Timeout() hook as soon as 
-possible after the timeout expires. For every call to SetTimeout(), the 
-Timeout() hook is only called once. Note: the term "timeout" may be a little 
-misleading; the hook will <I>always</I> be called, even if events are received 
-in the mean time. Apparently, this facility is handy for dealing with early 
-events.
-
-Note that the event thread blocks on the consumer's port as long as no events 
-arrive. By default no timeout is set, and as a result the thread blocks 
-forever. Your call to SetTimeout() doesn't change this. The new timeout value 
-will go into effect the next time the thread tries to read from the port, i.e. 
-after the first event has been received. If no event ever comes in, the 
-Timeout() hook will never be called. This also means that you cannot cancel a 
-timeout once you have set it. To repeat, calling SetTimeout() only takes effect 
-after at least one new event has been received.
-
-\param when An absolute time that's measured against the system clock.
-
-\param data A pointer to a "cookie" that you can pass along to Timeout(). The 
-data is not copied, so you must ensure that the pointer remains valid until 
-Timeout() is called. You typically delete the data inside Timeout().
-
-*/
-
-/*!
-\fn void BMidiLocalConsumer::Timeout(void* data)
-\brief Hook function that is called per your own request
-\sa SetTimeout()
-*/
-
-/*!
-\fn void BMidiLocalConsumer::Data(
-	uchar* data, size_t length, bool atomic, bigtime_t time)
-\brief Invoked when raw MIDI is received
-
-What the default implementation of Data() does depends on the value of atomic. 
-If atomic is true, the data received comprises a single MIDI event; i.e. one 
-status byte followed by the appropriate number of data bytes and nothing else. 
-In this case, Data() calls the event-specific hook function that corresponds to 
-that status byte. This optimization is used by the Midi Kit to allow faster 
-dispatch of events generated by the specific Spray functions from 
-BMidiLocalProducer.
-
-If atomic is false, Data() ignores the MIDI event. If you want a consumer to 
-handle non-atomic events, you have to override Data() and program this 
-yourself. In that case, you probably also want to call the default 
-implementation to handle the "normal" MIDI events.
-
-Data() is rarely overridden, but you can override it if you want to. If you do, 
-remember that the data buffer is owned by the Midi Kit. Do not attempt to 
-modify or free it, lest you wish to be laughed at by other developers.
-
-\param data the MIDI event data
-\param length byte size of the data buffer
-\param atomic whether the data buffer contains a single complete MIDI event
-\param time the requested performance time of the event
-
-\sa BMidiLocalProducer::SprayData()
-*/
-
-/*!
-\fn void BMidiLocalConsumer::NoteOff(
-    uchar channel, uchar note, uchar velocity, bigtime_t time)
-\brief Invoked when a Note Off event is received
-\sa BMidiLocalProducer::SprayNoteOff()
-*/
-
-/*!
-\fn void BMidiLocalConsumer::NoteOn(
-    uchar channel, uchar note, uchar velocity, bigtime_t time)
-\brief Invoked when a Note On event is received
-\sa BMidiLocalProducer::SprayNoteOn()
-*/
-
-/*!
-\fn void BMidiLocalConsumer::KeyPressure(
-    uchar channel, uchar note, uchar pressure, bigtime_t time)
-\brief Invoked when a Polyphonic Pressure (Aftertouch) event is received
-\sa BMidiLocalProducer::SprayKeyPressure()
-*/
-
-/*!
-\fn void BMidiLocalConsumer::ControlChange(
-    uchar channel, uchar controlNumber, uchar controlValue, bigtime_t time)
-\brief Invoked when a Controller Change event is received
-\sa BMidiLocalProducer::SprayControlChange()
-*/
-
-/*!
-\fn void BMidiLocalConsumer::ProgramChange(
-    uchar channel, uchar programNumber, bigtime_t time)
-\brief Invoked when a Program Change event is received
-\sa BMidiLocalProducer::SprayProgramChange()
-*/
-
-/*!
-\fn void BMidiLocalConsumer::ChannelPressure(
-    uchar channel, uchar pressure, bigtime_t time)
-\brief Invoked when a Channel Pressure event is received
-\sa BMidiLocalProducer::SprayChannelPressure()
-*/
-
-/*!
-\fn void BMidiLocalConsumer::PitchBend(
-    uchar channel, uchar lsb, uchar msb, bigtime_t time)
-\brief Invoked when a Pitch Bend event is received
-\sa BMidiLocalProducer::SprayPitchBend()
-*/
-
-/*!
-\fn void BMidiLocalConsumer::SystemExclusive(
-    void* data, size_t length, bigtime_t time)
-\brief Invoked when a System Exclusive event is received
-
-The data does not include the sysex start and end control bytes (0xF0 and 0xF7), 
-only the payload of the sysex message.
-
-The data belongs to the Midi Kit and is only valid for the duration of this 
-event. You may not modify or free it.
-
-\sa BMidiLocalProducer::SpraySystemExclusive()
-*/
-
-/*!
-\fn void BMidiLocalConsumer::SystemCommon(
-    uchar status, uchar data1, uchar data2, bigtime_t time)
-\brief Invoked when a System Common event is received
-
-Not all data bytes are used for all common events. Unused bytes are set to 0.
-
-\sa BMidiLocalProducer::SpraySystemCommon()
-*/
-
-/*!
-\fn void BMidiLocalConsumer::SystemRealTime(
-	uchar status, bigtime_t time)
-\brief Invoked when a Real Time event is received
-\sa BMidiLocalProducer::SpraySystemRealTime()
-*/
-
-/*!
-\fn void BMidiLocalConsumer::TempoChange(int32 beatsPerMinute, bigtime_t time)
-\brief Invoked when a Tempo Change event is received
-\sa BMidiLocalProducer::SprayTempoChange()
-*/
-
-/*!
-\fn void BMidiLocalConsumer::AllNotesOff(bool justChannel, bigtime_t time)
-\brief Not used
-*/
-
-

docs/user/midi2/midiendpoint.dox

@@ -1,296 +0,0 @@
-/*!
-\class BMidiEndpoint
-\ingroup midi2
-\ingroup libmidi2
-\brief Base class for all MIDI endpoints
-
-BMidiEndpoint is the abstract base class that represents either a producer or 
-consumer endpoint. It may be used to obtain the state, name, properties, or 
-system-wide ID of the object. BMidiEndpoint also provides the ability to change 
-the name and properties of endpoints that were created locally.
-
-Remember, you cannot call the destructor of BMidiEndpoint and its subclasses 
-directly. Endpoint objects are destructed automatically when their reference 
-count drops to zero. If necessary, the destructor of a local endpoint first 
-breaks off any connections and Unregister()'s the endpoint before it is 
-deleted. However, for good style and bonus points you should really \link 
-BMidiProducer::Disconnect() Disconnect() \endlink and Unregister() the object 
-yourself and not rely on the destructor to do this.
-
-*/
-
-/*!
-\fn const char* BMidiEndpoint::Name() const
-\brief Returns the name of the endpoint
-
-The function never returns NULL. If you created a local endpoint by passing a 
-NULL name into its constructor (or passing no name, which is the same thing), 
-then Name() will return an empty string, not NULL.
-
-\sa SetName()
-
-*/
-
-/*!
-\fn void BMidiEndpoint::SetName(const char* name)
-\brief Changes the name of the endpoint.
-
-Names don't have to be unique, but it is recommended that you give any 
-endpoints you publish meaningful and unique names, so users can easily 
-recognize what each endpoint does. There is no limit to the size of endpoint 
-names.
-
-Even though you can call this function on both remote and local objects, you 
-are only allowed to change the names of local endpoints; SetName() calls on 
-remote endpoints are ignored.
-
-\param name The new name. If you pass NULL, the name simply won't be changed.
-
-\sa Name()
-
-*/
-
-/*!
-\fn int32 BMidiEndpoint::ID() const
-\brief Returns the ID of the endpoint
-
-An ID uniquely identifies an endpoint in the system. The ID is a signed 32-bit 
-number that is assigned by the Midi Server when the endpoint is created. (So 
-even if a local endpoint is not published, it still has a unique ID.) Valid IDs 
-range from 1 to 0x7FFFFFFF, the largest value an int32 can have. 0 and negative 
-values are <I>not</I> valid IDs.
-
-*/
-
-/*!
-\fn bool BMidiEndpoint::IsProducer() const
-\brief Determines whether this endpoint is a BMidiProducer
-
-If it is, you can use a dynamic_cast to convert this object into a producer:
-
-\code
-if (endp->IsProducer())
-{
-    BMidiProducer* prod = dynamic_cast<BMidiProducer*>(endp);
-    ....
-}
-\endcode
-*/
-
-/*!
-\fn bool BMidiEndpoint::IsConsumer() const
-\brief Determines whether this endpoint is a BMidiConsumer
-
-If it is, you can use a dynamic_cast to convert this object into a consumer:
-
-\code
-if (endp->IsConsumer())
-{
-    BMidiConsumer* cons = dynamic_cast<BMidiConsumer*>(endp);
-    ....
-}
-\endcode
-*/
-
-/*!
-\fn bool BMidiEndpoint::IsRemote() const
-\brief Determines whether this endpoint is a proxy for a remote object
-
-An endpoint is "remote" when it is created by another application. Obviously, 
-the remote object is Register()'ed as well, otherwise you would not be able to 
-see it.
-
-*/
-
-/*!
-\fn bool BMidiEndpoint::IsLocal() const
-\brief Determines whether this endpoint represents a local object
-
-An endpoint is "local" when it is created by this application; in other words, 
-a BMidiLocalConsumer or BMidiLocalProducer.
-
-*/
-
-/*!
-\fn bool BMidiEndpoint::IsPersistent() const
-\brief Not used
-
-The purpose of this function is unclear, and as a result it doesn't do anything
-in the OpenBeOS implementation of the Midi Kit.
-
-\return Always returns false.
-*/
-
-/*!
-\fn bool BMidiEndpoint::IsValid() const
-\brief Determines whether the endpoint still exists
-
-Suppose you obtained a proxy object for a remote endpoint by querying the 
-BMidiRoster. What if the application that published this endpoint quits, or 
-less drastically, Unregister()'s that endpoint? Even though you still have a 
-BMidiEndpoint proxy object, the real endpoint no longer exists. You can use 
-IsValid() to check for this.
-
-Don't worry, operations on invalid objects, such as GetProperties(), will 
-return an error code (typically B_ERROR), but not cause a crash. Local objects 
-are always are considered to be valid, even if you did not Register() them. 
-(The only time a local endpoint is not valid is when there was a problem 
-constructing it.)
-
-If the application that created the remote endpoint crashes, then there is no 
-guarantee that the Midi Server immediately recognizes this. In that case, 
-IsValid() may still return true. Eventually, the stale endpoint will be removed 
-from the roster, though. From then on, IsValid() correctly returns false.
-
-*/
-
-/*!
-\fn status_t BMidiEndpoint::Acquire()
-\brief Increments the endpoint's reference count
-
-Each BMidiEndpoint has a reference count associated with it, so that 
-BMidiRoster can do proper bookkeeping. Acquire() increments this reference 
-count, and Release() decrements it. Once the count reaches zero, the endpoint 
-is deleted.
-
-When you are done with the endpoint, whether local or remote, you should 
-<I>always</I> Release() it!
-
-Upon construction, local endpoints start with a reference count of 1. Any 
-objects you obtain from BMidiRoster using the NextXXX() or FindXXX() functions 
-have their reference counts incremented in the process. If you forget to call 
-Release(), the objects won't be properly cleaned up and you'll make a fool out 
-of yourself.
-
-After you Release() an object, you are advised not to use it any further. If 
-you do, your app will probably crash. That also happens if you Release() an 
-object too many times.
-
-Typically, you don't need to call Acquire(), unless you have two disparate 
-parts of your application working with the same endpoint, and you don't want to 
-have to keep track of who needs to Release() the endpoint. Now you simply have 
-both of them release it.
-
-\return Always returns B_OK
-\sa Release()
-*/
-
-/*!
-\fn status_t BMidiEndpoint::Release()
-\brief Decrements the endpoint's reference count
-\return Always returns B_OK
-\sa Acquire()
-*/
-
-/*!
-\fn status_t BMidiEndpoint::Register()
-\brief Publishes the endpoint on the roster
-
-MIDI objects created by an application are invisible to other applications 
-until they are published. To publish an object use the Register() method. The 
-corresponding Unregister() method will cause an object to once again become 
-invisible to remote applications.
-
-BMidiRoster also has Register() and Unregister() methods. You may also use 
-those methods  to publish or hide your endpoints; both do the same thing.
-
-Although it is considered bad style, calling Register() on local endpoints that 
-are already registered won't mess things up. The Midi Server will simply ignore 
-your request. Likewise for Unregister()'ing more than once. Attempts to 
-Register() or Unregister() remote endpoints will fail, of course.
-
-If you are \link BMidiRoster::StartWatching() watching \endlink, you will 
-<I>not</I> receive notifications for any local endpoints you register or 
-unregister. Of course, other applications <I>will</I> be notified about your 
-endpoints.
-
-Existing connections will not be broken when an object is unregistered, but 
-future remote connections will be denied. When objects are destroyed, they 
-automatically become unregistered.
-
-\return B_OK on success, or a negative error code (typically B_ERROR) if 
-something went wrong.
-
-\sa Unregister()
-*/
-
-/*!
-\fn status_t BMidiEndpoint::Unregister()
-\brief Hides the endpoint from the roster
-\sa Register()
-*/
-
-/*!
-\fn status_t BMidiEndpoint::SetProperties(const BMessage* props)
-\brief Changes the properties of the endpoint
-
-Endpoints can have properties, which is any kind of information that might be 
-useful to associate with a MIDI object. The properties are stored in a 
-BMessage.
-
-Usage example:
-
-\code
-BMessage props;
-if (endpoint->GetProperties(&props) == B_OK)
-{
-    ...add data to the message...
-    endpoint->SetProperties(&props);
-} 
-\endcode
-
-You are only allowed to call SetProperties() on a local object.
-
-Properties should follow a protocol, so different applications will know how to 
-read each other's properties. The current protocol is very limited -- it only 
-allows you to associate icons with your endpoints. Be planned to publish a more 
-complete protocol that included additional information, such as vendor/model 
-names, copyright/version info, category, etc., but they never got around to it.
-
-<TABLE BORDER="1">
-<TR><TD>property</TD><TD>Vector icon (raw data)</TD></TR>
-<TR><TD>field name</TD><TD>"icon"</TD></TR>
-<TR><TD>field type</TD><TD>'VICN'</TD></TR>
-</TABLE>
-
-This vector icon is available under Haiku only, and comes as raw data, not a BBitmap. 
-Before being able to display it, you first must render the vector icon in the size of 
-your choice.
-
-<TABLE BORDER="1">
-<TR><TD>property</TD><TD>Large (32x32) icon</TD></TR>
-<TR><TD>field name</TD><TD>"be:large_icon"</TD></TR>
-<TR><TD>field type</TD><TD>'ICON'</TD></TR>
-</TABLE>
-
-<TABLE BORDER="1">
-<TR><TD>property</TD><TD>Small (16x16) icon</TD></TR>
-<TR><TD>field name</TD><TD>"be:mini_icon"</TD></TR>
-<TR><TD>field type</TD><TD>'MICN'</TD></TR>
-</TABLE>
-
-The MidiUtil package (downloadable from the OpenBeOS website) contains a number 
-of convenient functions to associate icons with endpoints, so you don't have to 
-write that code all over again.
-
-\sa GetProperties()
-*/
-
-/*!
-\fn status_t BMidiEndpoint::GetProperties(BMessage* props) const
-\brief Reads the properties of the endpoint
-
-Usage example:
-
-\code
-BMessage props;
-if (endpoint->GetProperties(&props) == B_OK) 
-{
-    ...examine the contents of the message...
-}
-\endcode
-
-Note that GetProperties() overwrites the contents of your BMessage.
-
-\sa SetProperties()
-*/

docs/user/midi2/midifiles.dox

@@ -1,31 +0,0 @@
-*!
-  \file Midi2Defs.h
-  \ingroup midi2
-  \brief General Defines for the MIDI2 kit
-
-  Please see \ref midi2defs for more information.
-*/
-
-/*!
-  \file MidiConsumer.h
-  \ingroup midi2
-  \brief Defines consumer classes for the MIDI Kit
-*/
-
-/*!
-  \file MidiProducer.h
-  \ingroup midi2
-  \brief Defines producer classes for the MIDI Kit
-*/
-
-/*!
-  \file MidiEndpoint.h
-  \ingroup midi2
-  \brief Defines the Baseclass of all MIDI consumers and producers
-*/
-
-/*!
-  \file MidiRoster.h
-  \ingroup midi2
-  \brief Defines the heart of the MIDI Kit: the MIDI Roster
-*/

docs/user/midi2/midiproducer.dox

@@ -1,308 +0,0 @@
-/*!
-\class BMidiProducer MidiProducer.h
-\ingroup midi2
-\ingroup libmidi2
-\brief Streams MIDI events to connected consumers
-
-A producer is an object that generate a stream of MIDI events. Each producer 
-has a list of BMidiConsumer objects to which it is connected, and may be asked 
-to connect to or disconnect from a BMidiConsumer. A producer can spray its 
-events to multiple consumers at the same time. 
-
-A BMidiProducer either represents a local producer, i.e. a class extending from 
-BMidiLocalProducer, or is a proxy for a remote object published by another app. 
-
-*/
-
-/*!
-\fn status_t BMidiProducer::Connect(BMidiConsumer* cons)
-\brief Connects a consumer to this producer
-
-Establishes a connection between this producer and the specified consumer 
-endpoint. From now on, any events that this producer sprays will be sent to 
-that consumer. You may connect multiple consumers to a producer.
-
-\return B_OK on success, or an error code when the connection could not be 
-established. If the consumer is a proxy for a remote object and that object no 
-longer exists, Connect() returns B_ERROR. It also returns B_ERROR if you try to 
-connect the same producer and consumer more than once.
-
-\sa Disconnect()
-*/
-
-/*!
-\fn status_t BMidiProducer::Disconnect(BMidiConsumer* cons)
-\brief Disconnects a consumer from this producer
-
-Terminates the connection between this producer and the specified consumer 
-endpoint. From now on, any events that this producer sprays no longer go to 
-that consumer.
-
-\return B_OK on success, or an error code if there was no connection to break
-
-\sa Connect()
-*/
-
-/*!
-\fn bool BMidiProducer::IsConnected(BMidiConsumer* cons) const
-\brief Determines whether a consumer is connected to this producer
-\sa Connect()
-\sa Disconnect()
-*/
-
-/*!
-\fn BList* BMidiProducer::Connections() const
-\brief Returns a list with all connected consumers
-
-Returns a BList with pointers to BMidiEndpoint objects for all consumers that 
-are connected to this producer. You can examine the contents of the list as 
-follows:
-
-\code
-BList* list = prod->Connections();
-for (int32 t = 0; t < list->CountItems(); ++t)
-{
-    BMidiEndpoint* endp = (BMidiEndpoint*) list->ItemAt(t);
-    ...do stuff...
-    endp->Release();  // yes, here too!
-}
-delete list;
-\endcode
-
-Every time you call this function, a new BList is allocated. The caller (that 
-is you) is responsible for freeing this list. The BMidiEndpoint objects in the 
-list have their reference counts bumped, so you need to Release() them before 
-you delete the list or they will go all leaky on you.
-
-*/
-
-/*!
-\class BMidiLocalProducer MidiProducer.h
-\ingroup midi2
-\ingroup libmidi2
-\brief A producer endpoint that is created by your own application
-
-You create a BMidiLocalProducer if you want your application to send MIDI 
-events. You use the various spray functions to send events to all connected 
-consumers. If no consumers are connected to the producer, any calls to the 
-spray functions are ignored.
-
-Most spray functions accept a channel argument. Even though MIDI channels are 
-really numbered 1 through 16, the spray functions work with channels 0 through 
-15. You can also specify the performance time for the event using the time 
-argument. Specify 0 (or any time in the past) to perform the event "now", i.e. 
-as soon as possible. You can also schedule events to be performed in the 
-future, by passing a time such as system_time() + 5000000, which means 5 
-seconds from now.
-
-Unlike BMidiLocalConsumer, which should be subclassed almost always, you hardly 
-ever need to derive a class from BMidiLocalProducer. The only reason for 
-subclassing is when you need to know when the producer gets connected or 
-disconnected.
-
-Also unlike consumers, local producers have no thread of control directly 
-associated with them. If you want to send out the MIDI events from a different 
-thread, you will have to create one yourself.
-
-*/
-
-/*!
-\fn BMidiLocalProducer::BMidiLocalProducer(const char *name = NULL)
-\brief Creates a new local producer endpoint
-
-The new endpoint is not visible to other applications until you Register() it.
-
-You can tell the constructor what the name of the new producer will be. If you 
-pass NULL (or use the default argument), then the producer's name will be an 
-empty string. It won't be NULL, since endpoint names cannot be NULL.
-
-There is no guarantee that the endpoint will be successfully created. For 
-example, the Midi Server may not be running. Therefore, you should always call 
-IsValid() after creating a new endpoint to make sure that everything went okay. 
-If not, Release() the object to reclaim memory and abort gracefully.
-
-\code
-BMidiLocalProducer* prod = new BMidiLocalProducer(...);
-if (!prod->IsValid())
-{
-    prod->Release();
-    ...exit gracefully...
-}
-\endcode
-
-*/
-
-/*!
-\fn void BMidiLocalProducer::Connected(BMidiConsumer* cons)
-\brief Invoked when a new consumer is connected to this producer
-
-Although typical notifications (i.e. from BMidiRoster's "watching" facility) 
-are only sent if it is some other app that is performing the operation, 
-Connected() is also called if you are making the connection yourself.
-
-If you override this hook, you don't have to call the default implementation, 
-because that does nothing.
-
-\param cons The newly connected consumer. The reference count of the consumer 
-object is not increased, so you should not Release() it. However, if you want 
-to keep track of the consumer beyond this function, you should first Acquire() 
-it, and Release() it when you are done.
-
-\sa Disconnected()
-*/
-
-/*!
-\fn void BMidiLocalProducer::Disconnected(BMidiConsumer* cons)
-\brief Invoked when a consumer is disconnected from this producer
-\sa Connected()
-*/
-
-/*!
-\fn void BMidiLocalProducer::SprayData(
-    void* data, size_t length, bool atomic = false, bigtime_t time = 0) const
-\brief Sends raw MIDI data downstream to all connected consumers
-
-Typically you won't have to call SprayData(); the other spray functions will do 
-just fine. If you do call it, remember that you retain ownership of the data 
-and that you are responsible for freeing it at some point. (Even though data is 
-not declared const, the function does not change it.)
-
-With atomic set to false, you can send a MIDI message in segments (perhaps for 
-a large sysex dump). However, when you do this, you are on your own. The Midi 
-Kit only tags the data as being non-atomic, but offers no additional support. 
-The default implementation of BMidiLocalConsumer completely ignores such 
-events. To handle non-atomic MIDI data, you should override the 
-BMidiLocalConsumer::Data() hook and process the MIDI event yourself. All of
-BMidiLocalProducer's other spray functions always send atomic data.
-
-\param data the MIDI event data
-\param length byte size of the data buffer
-\param atomic whether the data buffer contains a single complete MIDI event
-\param time the required performance time of the event
-
-\sa BMidiLocalConsumer::Data()
-*/
-
-/*!
-\fn void BMidiLocalProducer::SprayNoteOff(
-    uchar channel, uchar note, uchar velocity, bigtime_t time = 0) const
-\brief Sends a Note Off event to all connected consumers
-\sa BMidiLocalConsumer::NoteOff()
-*/
-
-/*!
-\fn void BMidiLocalProducer::SprayNoteOn(
-    uchar channel, uchar note, uchar velocity, bigtime_t time = 0) const
-\brief Sends a Note On event to all connected consumers
-\sa BMidiLocalConsumer::NoteOn()
-*/
-
-/*!
-\fn void BMidiLocalProducer::SprayKeyPressure(
-    uchar channel, uchar note, uchar pressure, bigtime_t time = 0) const
-\brief Sends a Polyphonic Pressure (Aftertouch) event to all connected 
-consumers
-\sa BMidiLocalConsumer::KeyPressure()
-*/
-
-/*!
-\fn void BMidiLocalProducer::SprayControlChange(
-    uchar channel, uchar controlNumber, uchar controlValue,
-    bigtime_t time = 0) const
-\brief Sends a Controller Change event to all connected consumers
-
-\sa Midi2Defs.h
-\sa BMidiLocalConsumer::ControlChange()
-*/
-
-/*!
-\fn void BMidiLocalProducer::SprayProgramChange(
-    uchar channel, uchar programNumber, bigtime_t time = 0) const
-\brief Sends a Program Change event to all connected consumers
-\sa BMidiLocalConsumer::ProgramChange()
-*/
-
-/*!
-\fn void BMidiLocalProducer::SprayChannelPressure(
-    uchar channel, uchar pressure, bigtime_t time = 0) const
-\brief Sends a Channel Pressure event to all connected consumers
-\sa BMidiLocalConsumer::ChannelPressure()
-*/
-
-/*!
-\fn void BMidiLocalProducer::SprayPitchBend(
-    uchar channel, uchar lsb, uchar msb, bigtime_t time = 0) const
-\brief Sends a Pitch Bend event to all connected consumers
-\sa BMidiLocalConsumer::PitchBend()
-*/
-
-/*!
-\fn void BMidiLocalProducer::SpraySystemExclusive(
-    void* data, size_t length, bigtime_t time = 0) const
-\brief Sends a System Exclusive event to all connected consumers
-
-You retain ownership of the data and are responsible for freeing it. Even 
-though data is not declared const, the function does not change it. Even though 
-the amount of data may be quite large, this function always sends sysex 
-messages as an atomic block of data.
-
-\sa BMidiLocalConsumer::SystemExclusive()
-*/
-
-/*!
-\fn void BMidiLocalProducer::SpraySystemCommon(
-    uchar status, uchar data1, uchar data2, bigtime_t time = 0) const
-\brief Sends a System Common event to the connected consumers
-
-The status byte must be one of the following:
-
-<TABLE BORDER="1">
-<TR><TD>0xF1</TD><TD>B_MIDI_TIME_CODE</TD><TD>data1 only</TD></TR>
-<TR><TD>0xF2</TD><TD>B_SONG_POSITION</TD><TD>data1 and data2</TD></TR>
-<TR><TD>0xF3</TD><TD>B_SONG_SELECT</TD><TD>data1 only</TD></TR>
-<TR><TD>0xF5</TD><TD>B_CABLE_MESSAGE</TD><TD>data1 only</TD></TR>
-<TR><TD>0xF6</TD><TD>B_TUNE_REQUEST</TD><TD>no data</TD></TR>
-<TR><TD>0xF7</TD><TD>B_SYS_EX_END</TD><TD>no data</TD></TR>
-</TABLE>
-
-\sa BMidiLocalConsumer::SystemCommon()
-*/
-
-/*!
-\fn void BMidiLocalProducer::SpraySystemRealTime(
-    uchar status, bigtime_t time = 0) const
-\brief Sends a Real Time event to the connected consumers
-
-The status byte must be one of the following:
-
-<TABLE BORDER="1">
-<TR><TD>0xF8</TD><TD>B_TIMING_CLOCK</TD></TR>
-<TR><TD>0xFA</TD><TD>B_START</TD></TR>
-<TR><TD>0xFB</TD><TD>B_CONTINUE</TD></TR>
-<TR><TD>0xFC</TD><TD>B_STOP</TD></TR>
-<TR><TD>0xFE</TD><TD>B_ACTIVE_SENSING</TD></TR>
-<TR><TD>0xFF</TD><TD>B_SYSTEM_RESET</TD></TR>
-</TABLE>
-
-Because of their high priority, the MIDI specification allows real time 
-messages to "interleave" with other MIDI messages. A large sysex dump, for 
-example, may be interrupted by a real time event. The Midi Kit, however, 
-doesn't care. If you (or another producer) have just sent a big system 
-exclusive to a consumer, any following real time message will simply have to 
-wait until the consumer has dealt with the sysex.
-
-\sa BMidiLocalConsumer::SystemRealTime()
-*/
-
-/*!
-\fn void BMidiLocalProducer::SprayTempoChange(
-    int32 bpm, bigtime_t time = 0) const
-\brief Sends a Tempo Change event to the connected consumers.
-
-This kind of Tempo Change event is not really part of the MIDI spec, rather
-it is an extension from the SMF (Standard MIDI File) format.
-
-\sa BMidiLocalConsumer::TempoChange()
-*/
-
-

docs/user/midi2/midiroster.dox

@@ -1,309 +0,0 @@
-/*!
-\var B_MIDI_EVENT
-\ingroup midi2
-\brief BMessage identifier of MIDI messages.
-*/
-
-/*!
-\class BMidiRoster MidiRoster.h
-\ingroup midi2
-\ingroup libmidi2
-\brief Interface to the system-wide Midi Roster
-
-BMidiRoster allows you to find available MIDI consumer and producer objects. 
-You can locate these objects using the iterative NextEndpoint(), 
-NextProducer(), and NextConsumer() methods or by requesting notification 
-messages to be sent with StartWatching(). Notification messages may contain 
-object IDs which can be resolved using the FindEndpoint(), FindProducer(), and 
-FindConsumer() methods.
-
-The constructor and destructor of BMidiRoster are private, which means that you 
-cannot create or delete your own BMidiRoster objects. Every application can 
-have only one instance of BMidiRoster, which is automatically created the very 
-first time you use a Midi Kit function. 
-
-You can call BMidiRoster's functions like this:
-
-\code
-producer = BMidiRoster::FindProducer(someID);
-\endcode
-
-Or using the slightly more annoying:
-
-\code
-BMidiRoster* roster = BMidiRoster::MidiRoster();
-if (roster != NULL)
-{
-    producer = roster->FindProducer(someID);
-}
-\endcode
-*/
-
-/*!
-\fn BMidiEndpoint* BMidiRoster::NextEndpoint(int32* id)
-\brief Returns the next endpoint from the roster
-
-The "next endpoint" means: the endpoint with the ID that follows id. So if you 
-set id to 3, the first possible endpoint it returns is endpoint 4. No endpoint 
-can have ID 0, so passing 0 gives you the first endpoint. If you pass NULL 
-instead of an ID, NextEndpoint() always returns NULL. When the function 
-returns, it sets id to the ID of the endpoint that was found. If no more 
-endpoints exist, NextEndpoint() returns NULL and id is not changed. 
-NextEndpoint() does <I>not</I> return locally created endpoints, even if they 
-are Register()'ed.
-
-Usage example:
-
-\code
-int32 id = 0;
-BMidiEndpoint* endp;
-while ((endp = BMidiRoster::NextEndpoint(&id)) != NULL) 
-{
-    ...do something with endpoint ...
-    endp->Release();  // don't forget!
-}
-\endcode
-
-Remember that NextEndpoint() bumps the endpoint's reference count, so you 
-should always \link BMidiEndpoint::Release() Release() \endlink it when you are 
-done.
-
-*/
-
-/*!
-\fn BMidiProducer* BMidiRoster::NextProducer(int32* id)
-\brief Returns the next producer from the roster
-
-Like NextEndpoint(), but only returns producer endpoints.
-
-\sa NextConsumer
-\sa NextEndpoint
-*/
-
-/*!
-\fn BMidiConsumer* BMidiRoster::NextConsumer(int32* id)
-\brief Returns the next consumer from the roster
-
-Like NextEndpoint(), but only returns consumer endpoints.
-
-\sa NextProducer
-\sa NextEndpoint
-*/
-
-/*!
-\fn BMidiEndpoint* BMidiRoster::FindEndpoint(
-        int32 id, bool localOnly = false)
-\brief Returns the endpoint with the specified ID
-
-FindEndpoint() will always find <I>any</I> local endpoints created by this 
-application; they do not have to be published with Register() first. If 
-localOnly is false, FindEndpoint() also looks at remote endpoints, otherwise 
-only local endpoints will be resolved. Returns NULL if no such endpoint could 
-be found.
-
-You should use a dynamic_cast to convert the BMidiEndpoint into a producer or 
-consumer:
-
-\code
-BMidiEndpoint* endp = ...;
-BMidiProducer* prod = NULL;
-BMidiConsumer* cons = NULL;
-
-if (endp->IsProducer())
-{
-    prod = dynamic_cast<BMidiProducer*>(endp);
-}
-else if (endp->IsConsumer())
-{
-    cons = dynamic_cast<BMidiConsumer*>(endp);
-}
-\endcode
-
-Remember that FindEndpoint() increments the endpoint's reference count, so you 
-should always \link BMidiEndpoint::Release() Release() \endlink an endpoint 
-when you are done with it:
-
-\code
-BMidiEndpoint* endp = BMidiRoster::FindEndpoint(someID);
-if (endp != NULL) 
-{
-    ...do stuff with the endpoint...
-    endp->Release();
-}
-\endcode
-
-*/
-
-/*!
-\fn BMidiProducer* BMidiRoster::FindProducer(
-        int32 id, bool localOnly = false)
-\brief Finds the producer with the specified ID
-
-Like FindEndpoint(), but only looks for producer endpoints. Returns NULL if no 
-endpoint with that ID exists, or if that endpoint is not a producer.
-
-\sa FindConsumer
-\sa FindEndpoint
-*/
-
-/*!
-\fn BMidiConsumer* BMidiRoster::FindConsumer(
-        int32 id, bool localOnly = false)
-\brief Finds the consumer with the specified ID
-
-Like FindEndpoint(), but only looks for consumer endpoints. Returns NULL if no 
-endpoint with that ID exists, or if that endpoint is not a consumer.
-
-\sa FindProducer
-\sa FindEndpoint
-*/
-
-/*!
-\fn void BMidiRoster::StartWatching(const BMessenger* msngr)
-\brief Start receiving notifications from the Midi Roster
-
-When you start watching, BMidiRoster sends you notifications for all currently 
-<I>published</I> <I>remote</I> endpoints, and all the current connections 
-between them. (At this point, BMidiRoster does not let you know about 
-connections between unpublished endpoints, nor does it tell you anything about 
-your local endpoints, even though they may be published.)
-
-Thereafter, you'll receive notifications any time something important happens 
-to an object. The application that performs these operations is itself not 
-notified. The assumption here is that you already know about these changes, 
-because you are the one that is performing them.
-
-The notifications are BMessages with code B_MIDI_EVENT. You specify the 
-BMessenger that will be used to send these messages. Each message contains a 
-field called be:op that describes the type of notification.
-
-The "registered" and "unregistered" notifications are sent when a remote 
-endpoint Register()'s or Unregister()'s, respectively. You don't receive these 
-notifications when you register or unregister your local endpoints, but the 
-other apps will.
-
-<TABLE BORDER="1">
-<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_REGISTERED</TD></TR>
-<TR><TD>be:id</TD><TD>int32</TD><TD>ID of the endpoint</TD></TR>
-<TR><TD>be:type</TD><TD>string</TD><TD>"producer" or "consumer"</TD></TR>
-</TABLE>
-
-<TABLE BORDER="1">
-<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_UNREGISTERED</TD></TR>
-<TR><TD>be:id</TD><TD>int32</TD><TD>ID of the endpoint</TD></TR>
-<TR><TD>be:type</TD><TD>string</TD><TD>"producer" or "consumer"</TD></TR>
-</TABLE>
-
-The "connected" and "disconnected" notifications are sent when a consumer \link 
-BMidiProducer::Connect() Connect()\endlink's to a producer, or when they \link 
-BMidiProducer::Disconnect() Disconnect() \endlink. You will receive these 
-notifications when <I>any</I> two endpoints connect or disconnect, even if they 
-are not published. (The purpose of which is debatable.) You won't receive the 
-notifications if you are the one making the connection, even if both endpoints 
-are remote. You <I>will</I> be notified when another app connects one of your 
-published endpoints.
-
-<TABLE BORDER="1">
-<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_CONNECTED</TD></TR>
-<TR><TD>be:producer</TD><TD>int32</TD><TD>ID of the connector</TD></TR>
-<TR><TD>be:consumer</TD><TD>int32</TD><TD>ID of the connectee</TD></TR>
-</TABLE>
-
-<TABLE BORDER="1">
-<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_DISCONNECTED</TD></TR>
-<TR><TD>be:producer</TD><TD>int32</TD><TD>ID of the connector</TD></TR>
-<TR><TD>be:consumer</TD><TD>int32</TD><TD>ID of the connectee</TD></TR>
-</TABLE>
-
-The following notifications are sent when an endpoint's attributes are changed. 
-You receive these notifications only if another application is changing one of 
-its published endpoints.
-
-<TABLE BORDER="1">
-<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_CHANGED_NAME</TD></TR>
-<TR><TD>be:id</TD><TD>int32</TD><TD>ID of the endpoint</TD></TR>
-<TR><TD>be:type</TD><TD>string</TD><TD>"producer" or "consumer"</TD></TR>
-<TR><TD>be:name</TD><TD>string</TD><TD>the endpoint's new name</TD></TR>
-</TABLE>
-
-<TABLE BORDER="1">
-<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_CHANGED_LATENCY</TD></TR>
-<TR><TD>be:id</TD><TD>int32</TD><TD>ID of the endpoint</TD></TR>
-<TR><TD>be:type</TD><TD>string</TD><TD>"producer" or "consumer"</TD></TR>
-<TR><TD>be:latency</TD><TD>int64</TD><TD>the new latency (microseconds)</TD></TR>
-</TABLE>
-
-<TABLE BORDER="1">
-<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_CHANGED_PROPERTIES</TD></TR>
-<TR><TD>be:id</TD><TD>int32</TD><TD>ID of the endpoint</TD></TR>
-<TR><TD>be:type</TD><TD>string</TD><TD>"producer" or "consumer"</TD></TR>
-<TR><TD>be:properties</TD><TD>BMessage</TD><TD>the new properties</TD></TR>
-</TABLE>
-
-Typical usage example:
-
-\code
-void MyView::AttachedToWindow()
-{
-    BMessenger msgr(this);
-    BMidiRoster::StartWatching(&msgr);
-}
-
-void MyView::MessageReceived(BMessage* msg)
-{
-    switch (msg->what) 
-    {
-        case B_MIDI_EVENT:
-            HandleMidiEvent(msg);
-            break;
-        default:
-            super::MessageReceived(msg);
-            break;
-    }
-}
-\endcode
-
-For the possible midi options, see #BMidiOp
-*/
-
-/*!
-\fn void BMidiRoster::StopWatching()
-\brief Stop receiving notifications from the Midi Roster
-\sa StartWatching()
-*/
-
-/*!
-\fn status_t BMidiRoster::Register(BMidiEndpoint* object)
-\brief Publishes an endpoint to other applications
-
-Calls BMidiEndpoint's \link BMidiEndpoint::Register() Register() \endlink 
-method to publish an endpoint, which makes it visible to other applications.
-
-*/
-
-/*!
-\fn status_t BMidiRoster::Unregister(BMidiEndpoint* object)
-\brief Hides an endpoint from other applications
-
-Calls BMidiEndpoint's \link BMidiEndpoint::Unregister() Unregister() \endlink 
-method to hide a previously published endpoint from other applications.
-
-*/
-
-/*!
-\fn BMidiRoster* BMidiRoster::MidiRoster()
-\brief Returns a pointer to the only instance of BMidiRoster
-
-There is no real reason use this function, since all BMidiRoster's public 
-function are static.
-
-*/
-
-/*!
-\enum BMidiOp
-\brief Defines the status codes for MIDI Server notification messages.
-
-These codes are used when you request notification as in BMidiRoster::StartWatching().
-Check against these codes to determine what is happening. See the StartWatching() method
-for a more complete description of the codes and their meaning.
-*/

docs/user/posix/syslog.dox

@@ -0,0 +1,350 @@
+/*
+ * Copyright 2007 Haiku, Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		Axel Dörfler
+ *		Niels Sascha Reedijk, [email protected]
+ *
+ * Corresponds to:
+ *		headers/posix/syslog.h	rev 6684
+ */
+
+
+/*!
+	\file syslog.h
+	\ingroup libroot
+	\brief System logging capabilities
+
+	The functions described here are interacting with the syslog_daemon, a server
+	that provides the system logging capabilities.
+	The log can be found in /var/log/syslog.
+*/
+
+
+/*!
+	\fn void closelog(void)
+	\brief Closes the current log session
+*/
+
+
+/*!
+	\fn void openlog(const char *ident, int options, int facility)
+	\brief Starts a log session, and sets some output options
+
+	Like openlog_thread() this function defines the log session in thread context; the
+	global options set by openlog_team() are not affected by this function.
+*/
+
+
+/*!
+	\fn int setlogmask(int priorityMask)
+	\brief sets the logging priority mask
+*/
+
+
+/*!
+	\fn void syslog(int priority, const char *message, ...)
+	\brief sends a message to the system log
+*/
+
+
+/*!
+	\fn void closelog_team(void)
+	\brief Closes the log
+*/
+
+
+/*!
+	\fn void openlog_team(const char *ident, int logopt, int facility)
+	\brief Starts a log session, and sets some output options
+
+	This function defines the team-wide logging options. Thread local sessions
+	started with openlog() or openlog_thread() will inherit the options of the
+	global session.
+*/
+
+
+/*!
+	\fn void log_team(int priority, const char *message, ...)
+	\brief sends a message to the system log
+*/
+
+
+/*!
+	\fn int setlogmask_team(int priorityMask)
+	\brief sets the logging priority mask
+*/
+
+
+/*!
+	\fn void closelog_thread(void)
+	\brief Closes the log
+*/
+
+
+/*!
+	\fn void openlog_thread(const char *ident, int logopt, int facility)
+	\brief Starts a log session, and sets some output options
+*/
+
+
+/*!
+	\fn void log_thread(int priority, const char *message, ...)
+	\brief sends a message to the system log
+*/
+
+
+/*!
+	\fn int setlogmask_thread(int priorityMask)
+	\brief sets the logging priority mask
+*/
+
+
+/*!
+	\name Options for openlog()
+*/
+
+
+//! @{
+
+
+/*!
+	\def LOG_PID
+	\brief Log the process (thread/team) ID with each message 
+*/
+
+
+/*!
+	\def LOG_CONS
+	\brief Log to the system console on error
+*/
+
+
+/*!
+	\def LOG_ODELAY
+	\brief Delay open until syslog() is called 
+*/
+
+
+/*!
+	\def LOG_NDELAY
+	\brief Connect to the syslog daemon immediately 
+*/
+
+
+/*!
+	\def LOG_SERIAL
+	\brief Dump to serial output as well.
+	\attention This is not yet implemented
+*/
+
+
+/*!
+	\def LOG_PERROR
+	\brief Dump to stderr as well
+*/
+
+
+/*!
+	\def LOG_NOWAIT
+	\brief Do not wait for child processes
+*/
+
+
+//! @}
+
+
+/*!	\name Facilities for openlog()
+*/
+
+
+//! @{
+
+
+/*!
+	\def LOG_KERN
+	\brief Reserved for messages generated by the kernel.
+*/
+
+
+/*!
+	\def LOG_USER
+	\brief Reserved for messages generated by user processes.
+*/
+
+
+/*!
+	\def LOG_MAIL
+	\brief Standard (?) POSIX facility for messages by the mailing daemon.
+*/
+
+
+/*!
+	\def LOG_DAEMON
+	\brief Standard POSIX (?) facility for messages by daemons (and Haiku servers).
+*/
+
+
+/*!
+	\def LOG_AUTH
+	\brief Standard POSIX facility(?) for messages by the authentication services.
+*/
+
+
+/*!
+	\def LOG_SYSLOG
+	\brief Reserved for messages generated by the syslog daemon.
+*/
+
+
+/*! 
+	\def LOG_LPR
+	\brief Reserved for messages generated by the UNIX lpr printing tool.
+*/
+
+
+/*!
+	\def LOG_NEWS
+	\brief Reserved for messages generated by something UNIXy that does something with NEWS.
+*/
+
+
+/*!
+	\def LOG_UUCP
+	\brief Reserved for messages generated by UUCP
+*/
+
+
+/*!
+	\def LOG_CRON
+	\brief Reserved for messages generated by the CRON daemon.
+*/
+
+
+/*!
+	\def LOG_AUTHPRIV
+	\brief Reserved for private (?) messages that relate to authentication.
+*/
+
+
+/*!
+	\def LOG_LOCAL0
+	\brief For local use.
+*/
+
+
+/*!
+	\def LOG_LOCAL1
+	\brief For local use.
+*/
+
+
+/*!
+	\def LOG_LOCAL2
+	\brief For local use.
+*/
+
+
+/*!
+	\def LOG_LOCAL3
+	\brief For local use.
+*/
+
+
+/*!
+	\def LOG_LOCAL4
+	\brief For local use.
+*/
+
+
+/*!
+	\def LOG_LOCAL5
+	\brief For local use.
+*/
+
+
+/*! 
+	\def LOG_LOCAL6
+	\brief For local use.
+*/
+
+
+/*! 
+	\def LOG_LOCAL7
+	\brief For local use.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Priorities for syslog(), log_team() and log_thread()
+*/
+
+
+//! @{
+
+
+/*!
+	\def LOG_EMERG
+	\brief A panic condition
+*/
+
+
+/*!
+	\def LOG_PANIC
+	\brief An alias for LOG_EMERG
+*/
+
+
+/*!
+	\def LOG_ALERT
+	\brief A condition to that should be corrected immediately
+*/
+
+
+/*!
+	\def LOG_CRIT
+	\brief Critical conditions like hard drive errors
+*/
+
+
+/*! 
+	\def LOG_ERR
+	\brief Errors
+*/
+
+
+/*!
+	\def LOG_WARNING
+	\brief Warnings
+*/
+
+
+/*!
+	\def LOG_NOTICE
+	\brief Notices, instructions on how to use certain configuration options.
+*/
+
+
+/*!
+	\def LOG_INFO
+	\brief Information, like versions and so.
+*/
+
+
+/*!
+	\def LOG_DEBUG
+	\brief Debug information.
+*/
+
+
+//! @}
+
+
+/*!
+	\def LOG_MASK
+	\brief Converts a priority definition for use in setlogmask()
+*/

docs/user/storage/AppFileInfo.dox

@@ -1,18 +1,21 @@
 /*
- * Copyright 2011, Haiku inc.
+ * Copyright 2011 Haiku, Inc. All rights reserved.
- * Distributed under the terms of the MIT Licence.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		John Scipione, [email protected]
+ *		Ingo Weinhold, [email protected]
  *
- * Documentation by:
- *		John Scipione <[email protected]>
- *		Ingo Weinhold <[email protected]>
  * Corresponds to:
- *		/trunk/headers/os/storage/AppFileInfo.h	 rev 42274
+ *		headers/os/storage/AppFileInfo.h	 rev 42274
- *		/trunk/src/kits/storage/AppFileInfo.cpp	 rev 42274
+ *		src/kits/storage/AppFileInfo.cpp	 rev 42274
  */
 
 
 /*!
 	\file AppFileInfo.h
+	\ingroup storage
+	\ingroup libbe
 	\brief Provides the BAppFileInfo class.
 */
 
@@ -20,6 +23,7 @@
 /*!
 	\class BAppFileInfo
 	\ingroup storage
+	\ingroup libbe
 	\brief Provides access to the metadata associated with executables,
 		   libraries and add-ons.
 

docs/user/storage/Directory.dox

@@ -7,6 +7,7 @@
  *		Ingo Weinhold, [email protected]
  *		Axel Dörfler, [email protected]
  *		John Scipione, [email protected]
+ *
  * Corresponds to:
  *		headers/os/storage/Directory.h  hrev43528
  *		src/kits/storage/Directory.cpp  hrev43528
@@ -15,6 +16,8 @@
 
 /*!
 	\file Directory.h
+	\ingroup storage
+	\ingroup libbe
 	\brief Provides the BDirectory class.
 */
 

docs/user/storage/Entry.dox

@@ -6,6 +6,7 @@
  *		Tyler Dauwalder
  *		Simon Cusack, [email protected]
  *		John Scipione, [email protected]
+ *
  * Corresponds to:
  *		headers/os/storage/Entry.h  hrev43528
  *		src/kits/storage/Entry.cpp  hrev43528
@@ -14,12 +15,16 @@
 
 /*!
 	\file Entry.h
+	\ingroup storage
+	\ingroup libbe
 	\brief Provides the BEntry class and entry_ref implementations.
 */
 
 
 /*!
 	\struct entry_ref
+	\ingroup storage
+	\ingroup libbe
 	\brief A filesystem entry represented as a name in a concrete directory.
 
 	entry_refs may refer to pre-existing (concrete) files, as well as
@@ -120,20 +125,23 @@
 
 /*!
 	\var dev_t entry_ref::device
-	\brief The device id of the storage device on which the entry resides
+
+	The device id of the storage device on which the entry resides.
 
 */
 
 
 /*!
 	\var ino_t entry_ref::directory
-	\brief The inode number of the directory in which the entry resides
+
+	The inode number of the directory in which the entry resides.
 */
 
 
 /*!
 	\var char *entry_ref::name
-	\brief The leaf name of the entry
+
+	The leaf name of the entry
 */
 
 
@@ -162,10 +170,10 @@ BEntry entry("/boot/home/fido");
 
 	Should be followed by a call to one of the SetTo() methods, or an
 	assignment.
-		- SetTo(const BDirectory*, const char*, bool)
+	- SetTo(const BDirectory*, const char*, bool)
-		- SetTo(const entry_ref*, bool)
+	- SetTo(const entry_ref*, bool)
-		- SetTo(const char*, bool)
+	- SetTo(const char*, bool)
-		- operator=(const BEntry&)
+	- operator=(const BEntry&)
 */
 
 
@@ -250,7 +258,7 @@ BEntry entry("/boot/home/fido");
 	\fn bool BEntry::Exists() const
 	\brief Returns whether or not the entry exists in the filesystem.
 
-	\returns \c true if the entry exists, \c false if the entry does not exist.
+	\returns \c true if the entry exists, \c false if not.
 */
 
 

docs/user/storage/EntryList.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2011, Haiku, Inc. All Rights Reserved.
+ * Copyright 2011 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -7,13 +7,15 @@
  *		John Scipione, [email protected]
  * 
  * Corresponds to:
- *		/trunk/headers/os/storage/EntryList.h	 rev 42794
+ *		headers/os/storage/EntryList.h	 rev 42794
- *		/trunk/src/kits/storage/EntryList.cpp	 rev 42794
+ *		src/kits/storage/EntryList.cpp	 rev 42794
  */
 
 
 /*!
 	\file EntryList.h
+	\ingroup storage
+	\ingroup libbe
 	\brief Defines the BEntryList class.
 */
 

docs/user/storage/File.dox

@@ -15,6 +15,8 @@
 
 /*!
 	\file File.h
+	\ingroup storage
+	\ingroup libbe
 	\brief Provides the BFile class.
 */
 

docs/user/storage/FilePanel.dox

@@ -13,42 +13,50 @@
 
 /*!
 	\file FilePanel.h
+	\ingroup storage
+	\ingroup libbe
 	\brief Provides the BFilePanel and BRefFilter classes and support enums.
 */
 
 
 /*!
 	\enum file_panel_mode
-	Whether the file panel is a save or open panel.
+	\ingroup storage
+	\brief Whether the file panel is a save or open panel.
 */
 
 
 /*!
 	\var file_panel_mode B_OPEN_PANEL
+
 	Open panel
 */
 
 
 /*!
 	\var file_panel_mode B_SAVE_PANEL
+
 	Save panel
 */
 
 
 /*!
 	\enum file_panel_button
-	List of buttons used by the file panel
+	\ingroup storage
+	\brief List of buttons used by the file panel
 */
 
 
 /*!
 	\var file_panel_button B_CANCEL_BUTTON
+
 	Cancel button
 */
 
 
 /*!
 	\var file_panel_button B_DEFAULT_BUTTON
+
 	Default button
 */
 

docs/user/storage/FindDirectory.dox

@@ -1,9 +1,10 @@
 /*
- * Copyright 2011, Haiku inc.
+ * Copyright 2011 Haiku Inc. All rights reserved.
- * Distributed under the terms of the MIT Licence.
+ * Distributed under the terms of the MIT License.
  *
  * Documentation by:
- *		Adrien Destugues <[email protected]>
+ *		Adrien Destugues, [email protected]
+ *
  * Corresponds to:
  *		/trunk/headers/os/storage/FindDirectory.h	 rev 42600
  *		/trunk/src/kits/storage/FindDirectory.cpp	 rev 42600
@@ -13,6 +14,7 @@
 /*!
 	\file FindDirectory.h
 	\ingroup storage
+	\ingroup libbe
 	\brief Provides the find_directory function.
 
 	Haiku provides a set of directories for applications to use. These can be

docs/user/storage/Mime.dox

@@ -1,8 +1,8 @@
 /*
- * Copyright 2013 Haiku Inc.
+ * Copyright 2013 Haiku Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
+ * Authors:
  *		Ingo Weinhold, [email protected]
  *		John Scipione, [email protected]
  *
@@ -15,12 +15,14 @@
 /*!
 	\file Mime.h
 	\ingroup storage
+	\ingroup libbe
 	\brief Provides C and Haiku-only C++ MIME-type handling functions.
 */
 
 
 /*!
 	\enum icon_size
+	\ingroup storage
 	\brief Legacy BeOS icon size constants.
 */
 
@@ -62,26 +64,6 @@
 */
 
 
-/*!
-	\fn status_t do_mime_update(int32 what, const char *path, int recursive,
-		int synchronous, int force)
-	\brief Helper function that contacts the registrar for mime update calls.
-
-	\param what The message identifier.
-	\param path The path to a file or directory, or \c NULL.
-	\param recursive Triggers recursive behavior if not \c NULL.
-	\param synchronous If not \c NULL update_mime_info() waits until the
-		   operation is finished, otherwise it returns immediately and the
-		   update is done asynchronously.
-	\param force Specifies how to handle files that already have MIME
-		   information.
-
-	\returns A status code.
-
-	\see update_mime_info
-*/
-
-
 /*!
 	\fn int update_mime_info(const char *path, int recursive, int synchronous,
 		int force)

docs/user/storage/MimeType.dox

@@ -7,6 +7,7 @@
  *		Ingo Weinhold, [email protected]
  *		Axel Dörfler, [email protected]
  *		John Scipione, [email protected]
+ *
  * Corresponds to:
  *		headers/os/storage/MimeType.h  hrev43528
  *		src/kits/storage/MimeType.cpp  hrev43528
@@ -15,6 +16,8 @@
 
 /*!
 	\file MimeType.h
+	\ingroup storage
+	\ingroup libbe
 	\brief Provides the BMimeType class.
 */
 

docs/user/storage/Node.dox

@@ -1,25 +1,30 @@
 /*
- * Copyright 2002-2011, Haiku Inc.
+ * Copyright 2002-2011 Haiku Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		Tyler Dauwalder, [email protected]
  *		John Scipione, [email protected]
  *		Ingo Weinhold, [email protected]
+ *
  * Corresponds to:
- *		/trunk/headers/os/app/Node.h		 rev 42803
+ *		/trunk/headers/os/app/Node.h	rev 42803
- *		/trunk/src/kits/app/Node.cpp		 rev 42803
+ *		/trunk/src/kits/app/Node.cpp	rev 42803
  */
 
 
 /*!
 	\file Node.h
+	\ingroup storage
+	\ingroup libbe
 	\brief Provides the BNode class and node_ref structure.
 */
 
 
 /*!
 	\struct node_ref
+	\ingroup storage
+	\ingroup libbe
 	\brief Reference structure to a particular vnode on a device.
 */
 
@@ -71,6 +76,7 @@
 /*!
 	\class BNode
 	\ingroup storage
+	\ingroup libbe
 	\brief A BNode represents a chunk of data in the filesystem.
 
 	The BNode class provides an interface for manipulating the data and
@@ -82,18 +88,22 @@
 
 /*!
 	\var BNode::fFd
+
 	File descriptor for the given node.
 */
 
 
 /*!
 	\var BNode::fAttrFd
-	File descriptor for the attribute directory of the node. Initialized lazily.
+
+	File descriptor for the attribute directory of the node.
+	Initialized lazily.
 */
 
 
 /*!
 	\var BNode::fCStatus
+
 	The object's initialization status.
 */
 

docs/user/support/Archivable.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -11,18 +11,22 @@
  *		Thom Holwerda, [email protected]
  *
  * Corresponds to:
- *		/trunk/headers/os/support/Archivable.h rev 37751 
+ *		headers/os/support/Archivable.h rev 37751
- *		/trunk/src/kits/support/Archivable.cpp rev 37751
+ *		src/kits/support/Archivable.cpp rev 37751
  */
 
 
-/*!	\file Archivable.h
+/*!
+	\file Archivable.h
+	\ingroup support
+	\ingroup libbe
 	\brief Provides the BArchivable interface and declares the BArchiver and
 		BUnarchiver classes.
 */
 
 
-/*!	\class BArchivable
+/*!
+	\class BArchivable
 	\ingroup support
 	\ingroup libbe
 	\brief Interface for objects that can be archived into a BMessage.
@@ -37,8 +41,8 @@
 	disk. The objective of this interface, however, is to store objects that
 	will later be restored as new (but identical) objects. To illustrate this
 	point, BArchivable objects can be restored automatically to the correct
-	class, whereas BFlattenables have a data type which you need to map to
+	class, whereas BFlattenable objects have a data type which you need to map
-	classes manually.
+	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
@@ -65,12 +69,12 @@
 
 /*!
 	\fn BArchivable::BArchivable(BMessage* from)
-	\brief Constructor. Does important behind-the-scenes work in the unarchiving
+	\brief Constructor. Does important behind-the-scenes work in the
-		process.
+		   unarchiving process.
-	
+
 	If you inherit this interface you should provide at least one constructor
-	that takes one BMessage argument. In that constructor, you should call your
+	that takes one BMessage argument. In that constructor, you should call 
-	parent class' archive constructor (even if your parent class is
+	your parent class' archive constructor (even if your parent class is
 	BArchivable).
 */
 
@@ -130,7 +134,7 @@
 /*!
 	\fn virtual status_t BArchivable::Perform(perform_code d, void* arg)
 	\brief Perform some action (Internal method defined for binary
-		compatibility purposes).
+		   compatibility purposes).
 
 	\internal This method is defined for binary compatibility purposes, it is
 		used to ensure that the correct AllUnarchived() and AllArchived()
@@ -184,13 +188,18 @@
 
 
 ///// Global methods /////
+
+
 /*!
 	\addtogroup support_globals
-	@{
 */
 
 
-/*!	\typedef typedef BArchivable* (*instantiation_func)(BMessage*)
+//! @{
+
+
+/*!
+	\typedef typedef BArchivable* (*instantiation_func)(BMessage*)
 	\brief Internal definition of a function that can instantiate objects that
 		have been created with the BArchivable API.
 */

docs/user/support/Archiver.dox

@@ -1,16 +1,24 @@
 /*
- * Copyright 2010, Haiku, Inc. All Rights Reserved.
+ * Copyright 2010 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Author:
  *		Alex Wilson, [email protected]
  *
  * Corresponds to:
- *		/trunk/headers/os/support/Archivable.h rev 37751 
+ *		headers/os/support/Archivable.h rev 37751 
- *		/trunk/src/kits/support/Archivable.cpp rev 37751
+ *		src/kits/support/Archivable.cpp rev 37751
  */
 
 
+/*!
+	\file Archivable.h
+	\ingroup support
+	\ingroup libbe
+	\brief Contains BArchiver class.
+*/
+
+
 /*!
 	\class BArchiver
 	\ingroup support

docs/user/support/Autolock.dox

@@ -1,114 +1,121 @@
 /*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * 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]
+ *
  * Corresponds to:
- *   /trunk/headers/os/support/Autolock.h rev 19972
+ *		headers/os/support/Autolock.h	rev 19972
  */
 
+
 /*!
-  \file Autolock.h
+	\file Autolock.h
-  \brief Implements a handy locking utility.
+	\ingroup support
+	\ingroup libbe
+	\brief Implements a handy locking utility.
 */
 
+
 /*!
-  \class BAutolock
+	\class BAutolock
-  \ingroup support
+	\ingroup support
-  \ingroup libbe
+	\ingroup libbe
-  \brief Convenient utility to make parts of your code thread-safe easily.
+	\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
+	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
+	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
+	that protects a certain part of your code and data that are being
-  accessed by multiple threads. While BAutolock does not add any features
+	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
+	to locking, it provides a mechanism to easily lock and protect a part of your
-  code. 
+	code. 
 
-  Normally, when you need to protect data, you would have to make sure that
+	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
+	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
+	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
+	lot of time debugging a hang because you didn't pair all the Lock()s with an
-  Unlock(). See the example:
+	Unlock(). See the example:
 
 \code
 status_t
 Receiver::HandleCall(Call *call)
 {
-  ... work on call data ...
+	... work on call data ...
-
+	 fDataLocker->Lock()
-  fDataLocker->Lock()
+	 ... perform changes ...
-
+	 if (!success)
-  ... perform changes ...
+	{
-
+	  fDataLocker->Unlock();
-  if (!success)
+	  return B_ERROR;
-  {
+	}
-    fDataLocker->Unlock();
+	  
-    return B_ERROR;
+	fDataLocker->Unlock()
-  }
+	return B_OK;
-    
-  fDataLocker->Unlock()
-  return B_OK;
 }
 \endcode
-
+	With the BAutolock this example can be rewritten as follows:
-  With the BAutolock this example can be rewritten as follows:
 
 \code
 status_t
 Receiver::HandleCall(Call *call)
 {
-  ... work on call data ...
+	... work on call data ...
-  
+	
-  BAutolock autolock(fDataLocker);
+	BAutolock autolock(fDataLocker);
-  
+	
-  ... perform changes ...
+	... perform changes ...
-  
+	
-  if (!success)
+	if (!success)
-    return B_ERROR;
+	  return B_ERROR;
-  
+	
-  return B_OK;
+	return B_OK;
 }
 \endcode
 
-  Since the object is created on stack, it is destroyed as soon as we leave
+	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 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
+	the BLocker or BLooper, you don't have to manually make sure that every
-  exit from the function is properly unlocked.
+	exit from the function is properly unlocked.
 */
 
+
 /*!
-  \fn BAutolock::BAutolock(BLooper *looper)
+	\fn BAutolock::BAutolock(BLooper *looper)
-  \brief Create an object and lock the BLooper
+	\brief Create an object and lock the BLooper
 */
 
+
 /*!
-  \fn BAutolock::BAutolock(BLocker *locker)
+	\fn BAutolock::BAutolock(BLocker *locker)
-  \brief Create an object and lock the BLocker
+	\brief Create an object and lock the BLocker
 */
 
+
 /*!
-  \fn BAutolock::BAutolock(BLocker &locker)
+	\fn BAutolock::BAutolock(BLocker &locker)
-  \brief Create an object and lock the BLocker
+	\brief Create an object and lock the BLocker
 */
 
+
 /*!
-  \fn BAutolock::~BAutolock()
+	\fn BAutolock::~BAutolock()
-  \brief Destroy the object and unlock the associated BLocker or BLooper
+	\brief Destroy the object and unlock the associated BLocker or BLooper
 */
 
+
 /*!
-  \fn bool BAutolock::IsLocked(void)
+	\fn bool BAutolock::IsLocked(void)
-  \brief Verify whether the  associated BLocker or BLooper are actually locked.
+	\brief Verify whether the  associated BLocker or BLooper are actually
+		locked.
 
-  Basically you may assume that when the object is created, you are
+	Basically you may assume that when the object is created, you are
-  almost always sure the actual locking succeeds. It might fail if the
+	almost always sure the actual locking succeeds. It might fail if the
-  BLocker or BLooper are destroyed though. The semaphore will be
+	BLocker or BLooper are destroyed though. The semaphore will be
-  released and the Lock() call will fail. 
+	released and the Lock() call will fail.
 
-  If you expect this to happen, you can use this method to help you
+	If you expect this to happen, you can use this method to help you
-  protect yourself from any harm.
+	protect yourself from any harm.
-  \retval true The lock was acquired.
+	\retval true The lock was acquired.
-  \retval false Failed to acquire the lock.
+	\retval false Failed to acquire the lock.
 */

docs/user/support/Beep.dox

@@ -1,54 +1,61 @@
 /*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * 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]
+ *
  * Corresponds to:
- *   /trunk/headers/os/support/Beep.h  rev 19972
+ *		headers/os/support/Beep.h	rev 19972
- *   /trunk/src/kits/support/Beep.cpp rev 20711
+ *		src/kits/support/Beep.cpp	rev 20711
  */
- 
+
- /////!!!!!! Note that the workings of the beep still aren't completely clear
+
- ///// and not completely implemented, so this needs revision if everything
+/////!!!!!! Note that the workings of the beep still aren't completely clear
- ///// is finished.
+///// and not completely implemented, so this needs revision if everything
- 
+///// is finished.
-/*!
+
-  \file Beep.h
-  \brief Functions to generate sounds from the computer.
-*/
 
 /*!
-  \addtogroup support_globals
+	\file Beep.h
+	\ingroup support
+	\ingroup libbe
+	\brief Functions to generate sounds from the computer.
 */
 
+
+/*!
+	\addtogroup support_globals
+*/
+
+
 //! @{
 
-/*!	\fn status_t beep()
+
+/*!
+	\fn status_t beep()
 	\brief Invoke the standard system beep to alert users.
-
 	From Beep.h and in libbe.so.
-
 	\see system_beep() and add_system_beep_event()
 */
 
-/*!	\fn status_t system_beep(const char* eventName)
+
+/*!
+	\fn status_t system_beep(const char* eventName)
 	\brief Invokes the sound for event \a eventName.
-
 	You can add the events using add_system_beep_event().
-
 	From Beep.h and in libbe.so.
 */
 
-/*!	\fn status_t add_system_beep_event(const char* eventName, uint32 flags = 0)
+
+/*!
+	\fn status_t add_system_beep_event(const char* eventName, uint32 flags = 0)
 	\brief Adds an event to the media server.
-
 	Call this method to add a specific event to the media server.
-
 	From Beep.h and in libbe.so.
-
 	\param eventName The name of the event.
 	\param flags Currently unused. Pass \c 0.
 */
 
+
 //! @}

docs/user/support/BlockCache.dox

@@ -1,22 +1,24 @@
 /*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007 Haiku, Inc. All rights reserved.
  * 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]
- * 
+ *
  * Corresponds to:
- *		/trunk/headers/os/support/BlockCache.h  rev 19972
+ *		headers/os/support/BlockCache.h  rev 19972
- *		/trunk/src/kits/support/BlockCache.cpp  rev 4568
+ *		src/kits/support/BlockCache.cpp  rev 4568
  */
 
 
  /*!
 	\file BlockCache.h
+	\ingroup support
+	\ingroup libbe
 	\brief Implements a mechanism to store and retrieve memory blocks.
 */
 
@@ -40,14 +42,14 @@
 	\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 'expensive'
 	operations, it is 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 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
 	allocation. This can either be #B_OBJECT_CACHE or #B_MALLOC_CACHE.
@@ -55,14 +57,14 @@
 	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 new ones, so
 	you will not have to worry about availability. As soon as you are done you
 	can Save() the memory back into the pool. BBlockCache will make sure that no
 	more blocks will be saved than the initial number you 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 of it yourself. It
 	also means that when you delete your BBlockCache instance, any blocks of
@@ -73,7 +75,7 @@
 	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 by itself.
-	
+
 	\note BBlockCache is thread-safe.
 */
 
@@ -82,7 +84,7 @@
 	\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
 		initially. This number is also used as the maximum number of free blocks
 		that will be kept.
@@ -95,7 +97,7 @@
 /*!
 	\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.
@@ -105,12 +107,12 @@
 /*!
 	\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, 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.
@@ -120,12 +122,12 @@
 /*!
 	\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 of
 	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. Therefore, only feed blocks that

docs/user/support/BufferIO.dox

@@ -1,184 +1,207 @@
 /*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007,Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by: 
+ * Authors:
- *   Niels Sascha Reedijk <[email protected]>
+ *		Stefano Ceccherini, [email protected]
- *   Stefano Ceccherini ([email protected]) 
+ *		Niels Sascha Reedijk, [email protected]
+ *
  * Corresponds to:
- *   /trunk/headers/os/support/BufferIO.h  rev 19972
+ *		headers/os/support/BufferIO.h	rev 19972
- *   /trunk/src/kits/support/BufferIO.cpp  rev 20510
+ *		src/kits/support/BufferIO.cpp	rev 20510
  */
 
+
 /*!
-  \file BufferIO.h
+	\file BufferIO.h
-  \brief Provides the BBufferIO class.
+	\ingroup support
+	\ingroup libbe
+	\brief Provides the BBufferIO class.
+*/
+
+
+/*!
+	\class BBufferIO
+	\ingroup support
+	\ingroup libbe
+	\brief A buffered adapter for BPositionIO objects.
+
+	This class differs from other classes derived from BPositionIO in a sense
+	that it does not actually provide an actual entity to be read or written 
+	to, but rather acts like a "frontend" to a stream. This class especially
+	comes in handy when working with files that are constantly written and
+	rewritten and where you want do this writing buffered so that the hard
+	disk or the network will not have to be accessed so frequently.
+
+	This class works as follows. After constructing a BBufferIO object that
+	you want to be buffered, you can create this object. The constructor
+	takes a \a stream parameter that points to the object to be buffered.
+
+	You then use this object as a proxy to the resource you want to read
+	of or write to. As soon as you use ReadAt(), the buffer will be
+	initialized to the contents of the original stream, and subsequent calls
+	to the positions within the buffer will not be routed to the original
+	stream. In the same way WriteAt() will change the data in the buffer,
+	but not in the actual stream. In order to flush the changes to the
+	original stream, use the Flush() method. Deleting the object when you are
+	done with it will also flush the stream and update the original stream.
+
+	\note This class is not meant to be used in cases where the
+		original stream requires to be in a consistent state. Neither should
+		this class be used as a way to perform 'atomic' writes, because the
+		object might need to do partial writes if it needs to 'move' the
+		buffer. This happens for instance if the original stream is bigger
+		than the buffer.
 */
 
 /*!
-  \class BBufferIO
+	\fn BBufferIO::BBufferIO(BPositionIO *stream, size_t bufferSize,
-  \ingroup support
+		bool ownsStream)
-  \ingroup libbe
+	\brief Initialize a BBufferIO object.
-  \brief A buffered adapter for BPositionIO objects.
-  \author Stefano Ceccherini \<[email protected]\>
 
-  This class differs from other classes derived from BPositionIO in a sense that
+	The constructor will create a buffer of the given size
-  it does not actually provide an actual entity to be read or written to, but
+	and associate the object with the given BPositionIO stream.
-  rather acts like a "frontend" to a stream. This class especially comes in
-  handy when working with files that are constantly written and rewritten and
-  where you want do this writing buffered so that the hard disk or the network
-  will not have to be accessed so frequently.
 
-  This class works as follows. After constructing a BBufferIO object that you
+	\param stream A pointer to a BPositionIO object.
-  want to be buffered, you can create this object. The constructor takes a 
+	\param bufferSize The size of the buffer that the object will allocate and 
-  \a stream parameter that points to the object to be buffered. You then use
+    	use.
-  this object as a proxy to the resource you want to read of or write to. As
+	\param ownsStream Specifies if the object will delete the stream on 
-  soon as you use ReadAt(), the buffer will be initialised to the contents
+		destruction.
-  of the original stream,
-  and subsequent calls to the positions within the buffer will not be
-  routed to the original stream. In the same way WriteAt() will change
-  the data in the buffer, but not in the actual stream. In order to flush
-  the changes to the original stream, use the Flush() method. Deleting
-  the object when you are done with it will also flush the stream and
-  update the original stream.
-
-  \note This class is not meant to be used in cases where the 
-  original stream requires to be in a consistent state. Neither should this
-  class be used as a way to perform 'atomic' writes, because the object 
-  might need to do partial writes if it needs to 'move' the buffer. This 
-  happens for instance if the original stream is bigger than the buffer. 
 */
 
 /*!
-  \fn BBufferIO::BBufferIO(BPositionIO *stream, size_t bufferSize, bool ownsStream)
+	\fn BBufferIO::~BBufferIO()
-  \brief Initialize a BBufferIO object.
+	\brief Free the resources allocated by the object
-    
-  The constructor will create a buffer of the given size
-  and associate the object with the given BPositionIO stream.
 
-  \param stream A pointer to a BPositionIO object.
+	Flush pending changes to the stream and free the allocated memory.
-  \param bufferSize The size of the buffer that the object will allocate and 
+	If the \c owns_stream property is \c true, the destructor also
-    use.
+	deletes the stream associated with the BBufferIO object.
-  \param ownsStream Specifies if the object will delete the stream on 
-    destruction.
-*/
-
-/*!
-  \fn BBufferIO::~BBufferIO()
-  \brief Free the resources allocated by the object
-
-  Flush pending changes to the stream and free the allocated memory.
-  If the \c owns_stream property is \c true, the destructor also
-  deletes the stream associated with the BBufferIO object.
 */
 
 
 /*! 
-  \fn ssize_t BBufferIO::ReadAt(off_t pos, void *buffer, size_t size)
+	\fn ssize_t BBufferIO::ReadAt(off_t pos, void *buffer, size_t size)
-  \brief Read the specified amount of bytes at the given position.
+	\brief Read the specified amount of bytes at the given position.
-  \param pos The offset into the stream where to read.
+
-  \param buffer A pointer to a buffer where to copy the read data.
+	\param pos The offset into the stream where to read.
-  \param size The amount of bytes to read.
+	\param buffer A pointer to a buffer where to copy the read data.
-  \return The amount of bytes actually read, or an error code.
+	\param size The amount of bytes to read.
-  \retval B_NO_INIT The object is not associated with a valid BPositionIO
+
+	\return The amount of bytes actually read, or an error code.
+	\retval B_NO_INIT The object is not associated with a valid BPositionIO
     stream.
-  \retval B_BAD_VALUE The \c buffer parameter is not valid.
+	\retval B_BAD_VALUE The \c buffer parameter is not valid.
 */
 
 /*! 
-  \fn ssize_t BBufferIO::WriteAt(off_t pos, const void *buffer, size_t size)
+	\fn ssize_t BBufferIO::WriteAt(off_t pos, const void *buffer, size_t size)
-  \brief Write the specified amount of bytes at the given position.
+	\brief Write the specified amount of bytes at the given position.
-  \param pos The offset into the stream where to write.
+
-  \param buffer A pointer to a buffer which contains the data to write.
+	\param pos The offset into the stream where to write.
-  \param size The amount of bytes to write.
+	\param buffer A pointer to a buffer which contains the data to write.
-  \return The amount of bytes actually written, or an error code.
+	\param size The amount of bytes to write.
-  \retval B_NO_INIT The object is not associated with a valid BPositionIO
+
-    stream.
+	\return The amount of bytes actually written, or an error code.
-  \retval B_BAD_VALUE The \c buffer parameter is not valid.
+	\retval B_NO_INIT The object is not associated with a valid BPositionIO
+		stream.
+	\retval B_BAD_VALUE The \c buffer parameter is not valid.
 */
 
 /*! 
-  \fn off_t BBufferIO::Seek(off_t position, uint32 seekMode)
+	\fn off_t BBufferIO::Seek(off_t position, uint32 seekMode)
-  \brief Set the position in the stream.
+	\brief Set the position in the stream.
-    
-   Set the position in the stream where the Read() and Write() functions
-   (inherited from BPositionIO) begin reading and writing.
-   How the position argument is understood depends on the seek_mode flag.
-   
-   \param position The position where you want to seek.
-   \param seekMode Can have three values:
-   - \c SEEK_SET. The position passed is an offset from the beginning of the
-     stream; in other words, the current position is set to position.
-    For this mode, position should be a positive value. 
-   - \c SEEK_CUR. The position argument is an offset from the current position;
-    the value of the argument is added to the current position.
-   - \c SEEK_END. The position argument is an offset from the end of the
-     stream. In this mode the position argument should be negative (or zero).
 
-   \return The current position as an offset in bytes from the beginning of
+	Set the position in the stream where the Read() and Write() functions
-     the stream.
+	(inherited from BPositionIO) begin reading and writing.
-    
+	How the position argument is understood depends on the seek_mode flag.
-    \retval B_NO_INIT The object is not associated with a valid BPositionIO
-      stream.
-*/
 
-/*! 
+	\param position The position where you want to seek.
-  \fn off_t BBufferIO::Position() const
+	\param seekMode Can have three values:
-  \brief Return the current position in the stream.
+		- \c SEEK_SET The position passed is an offset from the beginning of
-  \return The current position as an offset in bytes
+			the stream; in other words, the current position is set to
-    from the beginning of the stream.
+			position. For this mode, position should be a positive value. 
-  \retval B_NO_INIT The object is not associated with a valid BPositionIO
+		- \c SEEK_CUR The position argument is an offset from the current
-    stream.
+			position; the value of the argument is added to the current
-*/
+			position.
+		- \c SEEK_END. The position argument is an offset from the end of the
+			stream. In this mode the position argument should be negative
+			(or zero).
 
-/*! 
+	\return The current position as an offset in bytes from the beginning of
-  \fn status_t BBufferIO::SetSize(off_t size)
+		the stream.
-  \brief Call the SetSize() function of the assigned BPositionIO stream.
+	\retval B_NO_INIT The object is not associated with a valid BPositionIO
-  \param size The new size of the BPositionIO object.
+		stream.
-  \retval B_OK The stream is resized.
-  \retval B_NO_INIT The object is not associated with a valid BPositionIO
-    stream.
 */
 
 /*!
-  \fn status_t BBufferIO::Flush()
+	\fn off_t BBufferIO::Position() const
-  \brief Write pending modifications to the stream.
+	\brief Return the current position in the stream.
-  \return The amount of bytes written, or if it failed it will return an error
+
+	\return The current position as an offset in bytes
+	from the beginning of the stream.
+	\retval B_NO_INIT The object is not associated with a valid BPositionIO
+		stream.
+*/
+
+/*!
+	\fn status_t BBufferIO::SetSize(off_t size)
+	\brief Call the SetSize() function of the assigned BPositionIO stream.
+
+	\param size The new size of the BPositionIO object.
+
+	\returns A status code.
+	\retval B_OK The stream is resized.
+	\retval B_NO_INIT The object is not associated with a valid BPositionIO
+		stream.
+*/
+
+/*!
+	\fn status_t BBufferIO::Flush()
+	\brief Write pending modifications to the stream.
+
+	\return The amount of bytes written, or if it failed it will return an error
     code.
 */
 
 
 /*! 
-  \fn BPositionIO *BBufferIO::Stream() const
+	\fn BPositionIO *BBufferIO::Stream() const
-  \brief Return a pointer to the stream specified on construction.
+	\brief Return a pointer to the stream specified on construction.
-  \return A pointer to the BPositionIO stream specified on construction.
+
+	\return A pointer to the BPositionIO stream specified on construction.
 */
 
 
-/*! 
+/*!
-  \fn size_t BBufferIO::BufferSize() const
+	\fn size_t BBufferIO::BufferSize() const
-  \brief Return the size of the internal buffer.
+	\brief Return the size of the internal buffer.
-  \return The size of the buffer allocated by the object.
-*/
 
-/*! 
+	\return The size of the buffer allocated by the object.
-  \fn bool BBufferIO::OwnsStream() const
-  \brief Tell if the BBufferIO object "owns" the specified stream.
-  \retval true The object "owns" the stream and will destroy it upon
-    destruction.
-  \retval false The object does not own the stream.
-  \see SetOwnsStream()
-*/
-
-/*! 
-  \fn void BBufferIO::SetOwnsStream(bool owns_stream)
-  \brief Set the \c owns_stream property of the object.
-  \param owns_stream If you pass \c true, the object will delete the stream
-    upon destruction, if you pass \c false it will not.
 */
 
 
-/*! 
+/*!
-  \fn void BBufferIO::PrintToStream() const
+	\fn bool BBufferIO::OwnsStream() const
-  \brief Print the object to stdout.
+	\brief Tell if the BBufferIO object "owns" the specified stream.
+
+	\retval true The object "owns" the stream and will destroy it upon
+		destruction.
+	\retval false The object does not own the stream.
+
+	\see SetOwnsStream()
+*/
+
+
+/*!
+	\fn void BBufferIO::SetOwnsStream(bool owns_stream)
+	\brief Set the \c owns_stream property of the object.
+
+	\param owns_stream If you pass \c true, the object will delete the stream
+		upon destruction, if you pass \c false it will not.
+*/
+
+
+/*!
+	\fn void BBufferIO::PrintToStream() const
+	\brief Print the object to stdout.
 */

docs/user/support/DataIO.dox

@@ -1,424 +1,470 @@
 /*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by: 
+ * Authors:
- *   Niels Sascha Reedijk <[email protected]>
+ *		Stefano Ceccherini, [email protected]
- *   Stefano Ceccherini ([email protected]) 
+ *		Niels Sascha Reedijk, [email protected]
+ *
  * Corresponds to:
- *   /trunk/headers/os/support/DataIO.h  rev 17981
+ *		headers/os/support/DataIO.h	rev 17981
- *   /trunk/src/kits/support/DataIO.cpp  rev 20510
+ *		src/kits/support/DataIO.cpp	rev 20510
  */
 
+
 /*!
-  \file DataIO.h
+	\file DataIO.h
-  \brief Defines abstract BDataIO and BPositionIO and the derived BMallocIO and BMemoryIO classes.
+	\ingroup support
+	\ingroup libbe
+	\brief Defines abstract BDataIO and BPositionIO and the derived BMallocIO and BMemoryIO classes.
 
-  Pure virtual BDataIO and BPositioIO classes provide
+	Pure virtual BDataIO and BPositioIO classes provide
-  the protocol for Read()/Write()/Seek().
+	the protocol for Read()/Write()/Seek().
 
-  BMallocIO and BMemoryIO classes implement the protocol,
+	BMallocIO and BMemoryIO classes implement the protocol,
-  as does BFile in the Storage Kit.
+	as does BFile in the Storage Kit.
 */
 
+
 ///// BDataIO /////
 
+
 /*!
-  \class BDataIO
+	\class BDataIO
-  \ingroup support
+	\ingroup support
-  \ingroup libbe
+	\ingroup libbe
-  \brief Abstract interface for objects that provide read and write access to 
+	\brief Abstract interface for objects that provide read and write access to 
-    data.
+		   data.
 
-  The interface provided by this class applies to objects or data that are
+	The interface provided by this class applies to objects or data that are
-  limited to reading and writing data. Classes derived from this class should
+	limited to reading and writing data. Classes derived from this class should
-  reimplement both the Read() and Write() method from this class.
+	re-implement both the Read() and Write() method from this class.
 
-  Candidates of types of data or objects that should be derived from this class
+	Candidates of types of data or objects that should be derived from this class
-  are probably broadcasting media streams (which don't support reading at a
+	are probably broadcasting media streams (which don't support reading at a
-  certain point in the data) or network streams that output data continously.
+	certain point in the data) or network streams that output data continuously.
-  Objects and data that support more advanced operations like seeking or
+	Objects and data that support more advanced operations like seeking or
-  reading at writing at defined positions should derive their classes from
+	reading at writing at defined positions should derive their classes from
-  BPositionIO, which inherits this class.
+	BPositionIO, which inherits this class.
 */
 
+
 /*!
-  \fn BDataIO::BDataIO()
+	\fn BDataIO::BDataIO()
-  \brief This constructor does nothing.
+	\brief This constructor does nothing.
 */
 
+
 /*!
-  \fn BDataIO::~BDataIO()
+	\fn BDataIO::~BDataIO()
-  \brief This destructor does nothing.
+	\brief This destructor does nothing.
 */
 
-/*!
-  \fn virtual ssize_t BDataIO::Read(void *buffer, size_t size) = 0
-  \brief Pure virtual to read data.
 
-  Your implementation should copy data into \c buffer, with the maximum size
+/*!
-  of \c size. 
+	\fn virtual ssize_t BDataIO::Read(void *buffer, size_t size) = 0
-  \return You should return the amount of bytes actually read, or an error code
+	\brief Pure virtual to read data.
+
+	Your implementation should copy data into \c buffer, with the maximum size
+	of \c size. 
+	\return You should return the amount of bytes actually read, or an error code
     in case of failure.
 */
 
-/*!
-  \fn virtual ssize_t BDataIO::Write(const void *buffer, size_t size) = 0
-  \brief Pure virtual to write data.
 
-  Your implementation should copy data from \c buffer, with the maximum size
+/*!
-  of \c size. 
+	\fn virtual ssize_t BDataIO::Write(const void *buffer, size_t size) = 0
-  \return You should return the amount of bytes actually written, or an error 
+	\brief Pure virtual to write data.
+
+	Your implementation should copy data from \c buffer, with the maximum size
+	of \c size. 
+	\return You should return the amount of bytes actually written, or an error 
     code in case of failure.
 */
 
+
 //////////// BPositionIO
+
+
 /*!
-  \class BPositionIO
+	\class BPositionIO
-  \ingroup support
+	\ingroup support
-  \ingroup libbe
+	\ingroup libbe
-  \brief Abstract interface that provides advanced read, write and seek access
+	\brief Abstract interface that provides advanced read, write and seek access
-    to data.
+		   to data.
 
-  The interface of this object applies to objects or data that allows
+	The interface of this object applies to objects or data that allows
-  position-aware reading and writing of data. Classes that derive from this
+	position-aware reading and writing of data. Classes that derive from this
-  class should at least reimplement ReadAt(), WriteAt(), Seek(), Position(),
+	class should at least re-implement ReadAt(), WriteAt(), Seek(), Position(),
-  SetSize() and GetSize() methods.
+	SetSize() and GetSize() methods.
 
-  A good example of a form of data that can derive from this object, are files.
+	A good example of a form of data that can derive from this object, are files.
-  The BFile class derives from BPositionIO and provides this interface to 
+	The BFile class derives from BPositionIO and provides this interface to 
-  files. If your object or data only supports linear reading and writing, 
+	files. If your object or data only supports linear reading and writing, 
-  consider deriving from the baseclass BDataIO.
+	consider deriving from the base-class BDataIO.
 
-  A final note, from BDataIO this class inherits Read() and Write(). The 
+	A final note, from BDataIO this class inherits Read() and Write(). The 
-  default implementation is to read or write the data at the current position 
+	default implementation is to read or write the data at the current position 
-  indicated by Position(). Reimplement the methods if you require a different
+	indicated by Position(). Re-implement the methods if you require a different
-  behaviour.
+	behavior.
 */
 
+
 /*!
-  \fn BPositionIO::BPositionIO()
+	\fn BPositionIO::BPositionIO()
-  \brief This constructor does nothing.
+	\brief This constructor does nothing.
 */
 
+
 /*!
-  \fn virtual BPositionIO::~BPositionIO()
+	\fn virtual BPositionIO::~BPositionIO()
-  \brief This destructor does nothing.
+	\brief This destructor does nothing.
 */
 
-/*!
-  \fn virtual ssize_t BPositionIO::Read(void *buffer, size_t size)
-  \brief Read data from current position.
 
-  This method is derived from BDataIO. The default implementation reads data 
+/*!
-  from the current position of the cursor, pointed at by Position(). If you
+	\fn virtual ssize_t BPositionIO::Read(void *buffer, size_t size)
-  require different behaviour, please look at BDataIO::Read() for what is 
+	\brief Read data from current position.
-  expected of this method.
+
+	This method is derived from BDataIO. The default implementation reads data 
+	from the current position of the cursor, pointed at by Position(). If you
+	require different behaviour, please look at BDataIO::Read() for what is 
+	expected of this method.
 */
 
-/*!
-  \fn virtual ssize_t BPositionIO::Write(const void *buffer, size_t size)
-  \brief Write data to the current position.
 
-  This method is derived from BDataIO. The default implementation writes data
+/*!
-  to the current position of the cursor, pointed at by Position(). If you
+	\fn virtual ssize_t BPositionIO::Write(const void *buffer, size_t size)
-  require different behaviour, please look at BDataIO::Write() for what is
+	\brief Write data to the current position.
-  expected of this method.
+
+	This method is derived from BDataIO. The default implementation writes data
+	to the current position of the cursor, pointed at by Position(). If you
+	require different behaviour, please look at BDataIO::Write() for what is
+	expected of this method.
 */
 
+
 /*!
-  \fn virtual ssize_t BPositionIO::ReadAt(off_t position, void *buffer, size_t size) = 0
+	\fn virtual ssize_t BPositionIO::ReadAt(off_t position, void *buffer, size_t size) = 0
-  \brief Pure virtual to read data from a certain position.
+	\brief Pure virtual to read data from a certain position.
 
-  Your implementation should copy data from the position indicated by 
+	Your implementation should copy data from the position indicated by 
-  \a position into the \a buffer with the maximum size of \a size.
+	\a position into the \a buffer with the maximum size of \a size.
 
-  \return The amount of bytes actually read, or an error code.
+	\return The amount of bytes actually read, or an error code.
 */
 
+
 /*!
-  \fn virtual ssize_t BPositionIO::WriteAt(off_t position, const void *buffer, size_t size) = 0
+	\fn virtual ssize_t BPositionIO::WriteAt(off_t position, const void *buffer, size_t size) = 0
-  \brief Pure virtual to write data to a certain position.
+	\brief Pure virtual to write data to a certain position.
 
-  Your implementation should copy data from \a buffer to the position indicated
+	Your implementation should copy data from \a buffer to the position indicated
-  by \a buffer with the maximum size of \a size.
+	by \a buffer with the maximum size of \a size.
 
-  \return The amount of bytes actually written, or an error code.
+	\return The amount of bytes actually written, or an error code.
 */
 
+
 /*!
-  \fn virtual off_t BPositionIO::Seek(off_t position, uint32 seekMode) = 0
+	\fn virtual off_t BPositionIO::Seek(off_t position, uint32 seekMode) = 0
-  \brief Pure virtual to move the cursor to a certain position.
+	\brief Pure virtual to move the cursor to a certain position.
 
-  Your implementation should move the position of the cursor to the provided
+	Your implementation should move the position of the cursor to the provided
-  point. What this actually means, depends on your object or data. 
+	point. What this actually means, depends on your object or data. 
 
-  \param position An integer that defines a position.
+	\param position An integer that defines a position.
-  \param seekMode You will get one of the following values:
+	\param seekMode You will get one of the following values:
     - \c SEEK_SET Set the cursor to the position indicated by \c position.
     - \c SEEK_END Set the cursor to the end of the buffer, and go
       \c position beyond that.
     - \c SEEK_CUR Set the cursor the the current position plus \c position.
-  \return The new position.
+	\return The new position.
 */
 
-/*!
-  \fn virtual off_t BPositionIO::Position() const = 0
-  \brief Pure virtual to return the current position of the cursor.
 
-  \return Your implementation should return the current position of the cursor.
+/*!
+	\fn virtual off_t BPositionIO::Position() const = 0
+	\brief Pure virtual to return the current position of the cursor.
+
+	\return Your implementation should return the current position of the cursor.
 */
 
+
 /*!
-  \fn virtual status_t BPositionIO::SetSize(off_t size)
+	\fn virtual status_t BPositionIO::SetSize(off_t size)
-  \brief Set the size of the object or data.
+	\brief Set the size of the object or data.
 
-  The default implementation returns \c B_ERROR. If your object or data allows
+	The default implementation returns \c B_ERROR. If your object or data allows
-  the size to be changed, reimplement this method.
+	the size to be changed, reimplement this method.
 
-  \return Return \c B_OK if everything succeeded, else return the appropriate
+	\return Return \c B_OK if everything succeeded, else return the appropriate
     error code.
 */
 
+
 /*!
-  \fn virtual status_t BPositionIO::GetSize(off_t* size) const
+	\fn virtual status_t BPositionIO::GetSize(off_t* size) const
-  \brief Get the size of the object or data.
+	\brief Get the size of the object or data.
 
-  The default implementation uses Seek() with the \c SEEK_END flag to
+	The default implementation uses Seek() with the \c SEEK_END flag to
-  determine the size of the buffer. If your data or object has a different way
+	determine the size of the buffer. If your data or object has a different way
-  of determining size, reimplement this method.
+	of determining size, reimplement this method.
 
-  Please check that NULL is not passed into \c size if you reimplement it in
+	Please check that NULL is not passed into \c size if you reimplement it in
-  your class.
+	your class.
 
-  \param[out] size The size of the object is put into this parameter.
+	\param[out] size The size of the object is put into this parameter.
-  \return This method returns \c B_OK on success or an error code on error.
+	\return This method returns \c B_OK on success or an error code on error.
-  \see Seek()
+	\see Seek()
 */
 
+
 //////////// BMemoryIO
+
+
 /*!
-  \class BMemoryIO
+	\class BMemoryIO
-  \ingroup support
+	\ingroup support
-  \ingroup libbe
+	\ingroup libbe
-  \brief A BPositionIO derived class that works on memory buffers.
+	\brief A BPositionIO derived class that works on memory buffers.
 
-  This class is used if you require access that confirms to the BPositionIO
+	This class is used if you require access that confirms to the BPositionIO
-  interface on memory buffers that you created. If you would like to use that
+	interface on memory buffers that you created. If you would like to use that
-  interface on new buffers, have a look at BMallocIO.
+	interface on new buffers, have a look at BMallocIO.
 
-  This class is particularly useful if you would like to use a class or method
+	This class is particularly useful if you would like to use a class or method
-  that are written to make use of the BPositionIO interface. It might also
+	that are written to make use of the BPositionIO interface. It might also
-  be used for 'secure' reading and writing from buffers, since this class
+	be used for 'secure' reading and writing from buffers, since this class
-  automatically checks the bounds of anything you might want to do.
+	automatically checks the bounds of anything you might want to do.
 
-  This class reimplements the Read(), Write(), ReadAt(), Writeat(), Seek() and
+	This class reimplements the Read(), Write(), ReadAt(), Writeat(), Seek() and
-  Position() interface from BPositionIO.
+	Position() interface from BPositionIO.
 */
 
-/*!
-  \fn BMemoryIO::BMemoryIO(void *data, size_t length)
-  \brief Create a read/write object.
 
-  \param data A pointer to the buffer to adopt.
+/*!
-  \param length The size of the buffer.
+	\fn BMemoryIO::BMemoryIO(void *data, size_t length)
-  \see BMemoryIO(const void *buffer, size_t length) for a read-only 
+	\brief Create a read/write object.
+
+	\param data A pointer to the buffer to adopt.
+	\param length The size of the buffer.
+	\see BMemoryIO(const void *buffer, size_t length) for a read-only 
     implementation.
 */
 
-/*!
-  \fn BMemoryIO::BMemoryIO(const void *buffer, size_t length)
-  \brief Create a read-only object.
 
-  \param buffer A pointer to the \c const (read-only) buffer to adopt.
+/*!
-  \param length The size of the buffer.
+	\fn BMemoryIO::BMemoryIO(const void *buffer, size_t length)
-  \see BMemoryIO(void *buffer, size_t length) for a read-write implementation.
+	\brief Create a read-only object.
+
+	\param buffer A pointer to the \c const (read-only) buffer to adopt.
+	\param length The size of the buffer.
+	\see BMemoryIO(void *buffer, size_t length) for a read-write implementation.
 */
 
+
 /*!
-  \fn BMemoryIO::~BMemoryIO()
+	\fn BMemoryIO::~BMemoryIO()
-  \brief The destructor does nothing.
+	\brief The destructor does nothing.
 */
 
-/*!
-  \fn ssize_t BMemoryIO::ReadAt(off_t pos, void *buffer, size_t size)
-  \brief Read from a given position.
 
-  \param[in] pos The offset where to start reading data.
+/*!
-  \param[out] buffer The buffer to copy the read bytes into.
+	\fn ssize_t BMemoryIO::ReadAt(off_t pos, void *buffer, size_t size)
-  \param[in] size The size of the \a buffer.
+	\brief Read from a given position.
-  \return The amount of read bytes or an error code.
+
-  \retval B_BAD_VALUE The position is less than zero or the buffer given on
+	\param[in] pos The offset where to start reading data.
+	\param[out] buffer The buffer to copy the read bytes into.
+	\param[in] size The size of the \a buffer.
+	\return The amount of read bytes or an error code.
+	\retval B_BAD_VALUE The position is less than zero or the buffer given on
     construction is invalid.
 */
 
-/*!
-  \fn ssize_t BMemoryIO::WriteAt(off_t pos, const void *buffer, size_t size)
-  \brief Write at a given position.
 
-  \param pos The offset to write to.
+/*!
-  \param buffer The buffer to copy the bytes from.
+	\fn ssize_t BMemoryIO::WriteAt(off_t pos, const void *buffer, size_t size)
-  \param size The number of bytes to write.
+	\brief Write at a given position.
-  \return The amount of bytes written or an error code.
+
-  \retval B_NOT_ALLOWED The object is constructed as a read-only object.
+	\param pos The offset to write to.
-  \retval B_BAD_VALUE The position is less than zero or the buffer given on
+	\param buffer The buffer to copy the bytes from.
+	\param size The number of bytes to write.
+	\return The amount of bytes written or an error code.
+	\retval B_NOT_ALLOWED The object is constructed as a read-only object.
+	\retval B_BAD_VALUE The position is less than zero or the buffer given on
     construction is invalid.
 */
 
-/*!
-  \fn off_t BMemoryIO::Seek(off_t position, uint32 seek_mode)
-  \brief Move the cursor to a given position.
 
-  \param position The position to move the cursor to.
+/*!
-  \param seek_mode The mode determines where the cursor is placed. 
+	\fn off_t BMemoryIO::Seek(off_t position, uint32 seek_mode)
+	\brief Move the cursor to a given position.
+
+	\param position The position to move the cursor to.
+	\param seek_mode The mode determines where the cursor is placed. 
     Possibilities:
     - \c SEEK_SET The cursor is set to \a position.
     - \c SEEK_CUR The \a position is added to the current position of the 
       cursor.
     - \c SEEK_END The cursor is put at the end of the data, plus
       \a position added to it. 
-  \return The new position.
+	\return The new position.
 */
 
+
 /*!
-  \fn off_t BMemoryIO::Position() const
+	\fn off_t BMemoryIO::Position() const
-  \brief Return the current position.
+	\brief Return the current position.
 */
 
+
 /*!
-  \fn status_t BMemoryIO::SetSize(off_t size)
+	\fn status_t BMemoryIO::SetSize(off_t size)
-  \brief Resize the buffer.
+	\brief Resize the buffer.
 
-  This method does not actually resize the buffer. If the new size is greater
+	This method does not actually resize the buffer. If the new size is greater
-  than the size of the buffer, resizing will fail. It will only succeed if the 
+	than the size of the buffer, resizing will fail. It will only succeed if the 
-  new size is less than the size of the buffer. The buffer itself will not be
+	new size is less than the size of the buffer. The buffer itself will not be
-  resized though. 
+	resized though. 
 
-  This method might be useful in some cases. If the buffer is larger than the
+	This method might be useful in some cases. If the buffer is larger than the
-  data it holds, changing the size will enable you to use the Seek() method
+	data it holds, changing the size will enable you to use the Seek() method
-  with the flag \c SEEK_END and not get an error if you read or write from
+	with the flag \c SEEK_END and not get an error if you read or write from
-  that position, since you actually have a buffer at the end.
+	that position, since you actually have a buffer at the end.
 
-  \retval B_OK The buffer is resized.
+	\retval B_OK The buffer is resized.
-  \retval B_NOT_ALLOWED The buffer is read-only.
+	\retval B_NOT_ALLOWED The buffer is read-only.
-  \retval B_ERROR The \c size is larger than the size of the buffer.
+	\retval B_ERROR The \c size is larger than the size of the buffer.
 */
 
+
 //////////// BMallocIO
+
+
 /*!
-  \class BMallocIO
+	\class BMallocIO
-  \ingroup support
+	\ingroup support
-  \ingroup libbe
+	\ingroup libbe
-  \brief A BPositionIO derived class that creates a memory buffer.
+	\brief A BPositionIO derived class that creates a memory buffer.
 
-  This class creates a memory buffer and provides a BPositionIO interface to
+	This class creates a memory buffer and provides a BPositionIO interface to
-  work on it. The memory buffer grows and shrinks automatically.
+	work on it. The memory buffer grows and shrinks automatically.
-  This is especially useful if you want to use a method or function that
+	This is especially useful if you want to use a method or function that
-  works on an object derived from BPositionIO and you want to do something with
+	works on an object derived from BPositionIO and you want to do something with
-  the resulting data, or it could be useful if you want to read and write to
+	the resulting data, or it could be useful if you want to read and write to
-  memory in a safe way, since this class has boundary checking.
+	memory in a safe way, since this class has boundary checking.
 
-  BMallocIO allocates a buffer based on a certain blocksize. This provides a
+	BMallocIO allocates a buffer based on a certain block size. This provides a
-  mechanism that will prevent it from needing to allocate new memory too often.
+	mechanism that will prevent it from needing to allocate new memory too often.
-  The default blocksize is 256 bytes, you can change it with SetBlockSize(). If
+	The default block size is 256 bytes, you can change it with SetBlockSize(). If
-  you are sure you are going to use a bigger buffer, change the blocksize so 
+	you are sure you are going to use a bigger buffer, change the block size so 
-  that you won't have to allocate more memory too often, especially if you use
+	that you won't have to allocate more memory too often, especially if you use
-  this class in performance-critical code.
+	this class in performance-critical code.
 
-  If you require a BPositionIO derived object that works on buffers you
+	If you require a BPositionIO derived object that works on buffers you
-  provide, have a look at BMemoryIO.
+	provide, have a look at BMemoryIO.
 */
 
+
 /*!
-  \fn BMallocIO::BMallocIO()
+	\fn BMallocIO::BMallocIO()
-  \brief Create a new memory buffer with block size 256.
+	\brief Create a new memory buffer with block size 256.
-  \see SetBlockSize()
+	\see SetBlockSize()
 */
 
+
 /*!
-  \fn BMallocIO::~BMallocIO()
+	\fn BMallocIO::~BMallocIO()
-  \brief Destroy the object and free the internal buffer.
+	\brief Destroy the object and free the internal buffer.
 */
 
-/*!
-  \fn ssize_t BMallocIO::ReadAt(off_t pos, void *buffer, size_t size)
-  \brief Read data at a certain position.
 
-  \param[in] pos Offset into the data where to read from.
+/*!
-  \param[out] buffer The buffer to copy the read bytes in.
+	\fn ssize_t BMallocIO::ReadAt(off_t pos, void *buffer, size_t size)
-  \param [in] size Size of the buffer.
+	\brief Read data at a certain position.
-  \return The number of read bytes, or \c B_BAD_VALUE if
+
+	\param[in] pos Offset into the data where to read from.
+	\param[out] buffer The buffer to copy the read bytes in.
+	\param [in] size Size of the buffer.
+	\return The number of read bytes, or \c B_BAD_VALUE if
     the provided \a buffer is invalid.
 */
 
-/*!
-  \fn ssize_t BMallocIO::WriteAt(off_t pos, const void *buffer, size_t size)
-  \brief Write data to a certain position.
 
-  \param pos Offset into the data where to write to.
+/*!
-  \param buffer The buffer to copy from.
+	\fn ssize_t BMallocIO::WriteAt(off_t pos, const void *buffer, size_t size)
-  \param size The size of the buffer.
+	\brief Write data to a certain position.
-  \return The number of bytes written or \c B_BAD_VALUE if the provided.
+
-  \a buffer is invalid.
+	\param pos Offset into the data where to write to.
+	\param buffer The buffer to copy from.
+	\param size The size of the buffer.
+	\return The number of bytes written or \c B_BAD_VALUE if the provided.
+	\a buffer is invalid.
 */
 
-/*!
-  \fn off_t BMallocIO::Seek(off_t position, uint32 seekMode)
-  \brief Move the cursor to a given position.
 
-  \param position The position to move the cursor to.
+/*!
-  \param seekMode The mode determines where the cursor is placed. Possibilities:
+	\fn off_t BMallocIO::Seek(off_t position, uint32 seekMode)
+	\brief Move the cursor to a given position.
+
+	\param position The position to move the cursor to.
+	\param seekMode The mode determines where the cursor is placed. Possibilities:
     - \c SEEK_SET The cursor is set to \a position.
     - \c SEEK_CUR The \c position is added to the current position of the
       cursor.
     - \c SEEK_END The cursor is put at the end of the data, plus
       \a position added to it. 
-  \return The new position.
+	\return The new position.
 */
 
+
 /*!
-  \fn off_t BMallocIO::Position() const
+	\fn off_t BMallocIO::Position() const
-  \brief Return the position of the cursor.
+	\brief Return the position of the cursor.
 */
 
+
 /*!
-  \fn status_t BMallocIO::SetSize(off_t size)
+	\fn status_t BMallocIO::SetSize(off_t size)
-  \brief Change the size of the buffer.
+	\brief Change the size of the buffer.
 
-  This method changes the size of the current buffer. If \a size is smaller 
+	This method changes the size of the current buffer. If \a size is smaller 
-  than the current size, the data will be cleared.
+	than the current size, the data will be cleared.
 
-  \param size The new size of the buffer.
+	\param size The new size of the buffer.
-  \retval B_OK Resizing the data succeeded.
+	\retval B_OK Resizing the data succeeded.
-  \retval B_NO_MEMORY Failed to allocate the necessary memory.
+	\retval B_NO_MEMORY Failed to allocate the necessary memory.
 */
 
+
 /*!
-  \fn void BMallocIO::SetBlockSize(size_t blockSize)
+	\fn void BMallocIO::SetBlockSize(size_t blockSize)
-  \brief Change the block size to a certain value.
+	\brief Change the block size to a certain value.
 
-  This class allocates memory in blocks. If you are in performance-critical 
+	This class allocates memory in blocks. If you are in performance-critical 
-  code you might want to tweak this setting to create a better performance in
+	code you might want to tweak this setting to create a better performance in
-  case you know you are going to allocate more than the default blocksize of
+	case you know you are going to allocate more than the default blocksize of
-  256.
+	256.
 
-  \param blockSize The new block size.
+	\param blockSize The new block size.
 */
 
+
 /*!
-  \fn const void *BMallocIO::Buffer() const
+	\fn const void *BMallocIO::Buffer() const
-  \brief Return a pointer to the internal buffer.
+	\brief Return a pointer to the internal buffer.
 
-  As with any pointer to internal buffers the Haiku API exposes,
+	As with any pointer to internal buffers the Haiku API exposes,
-  make sure you don't change anything since it doesn't belong to you.
+	make sure you don't change anything since it doesn't belong to you.
 */
 
+
 /*!
-  \fn size_t BMallocIO::BufferLength() const
+	\fn size_t BMallocIO::BufferLength() const
-  \brief Return the number of bytes in the buffer.
+	\brief Return the number of bytes in the buffer.
 
-  This number doesn't have to be the same size as the buffer is. Because memory
+	This number doesn't have to be the same size as the buffer is. Because memory
-  is allocated in blocks the actual size of the buffer may be greater, but this
+	is allocated in blocks the actual size of the buffer may be greater, but this
-  method only returns the number of bytes that are actually used.
+	method only returns the number of bytes that are actually used.
 */
-

docs/user/support/Flattenable.dox

@@ -1,171 +1,188 @@
 /*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation written by:
+ * Authors:
- *   Niels Sascha Reedijk <[email protected]>
+ *		Niels Sascha Reedijk <[email protected]>
+ *
  * Corresponds to:
- *   /trunk/headers/os/support/Flattenable.h rev 19972
+ *		headers/os/support/Flattenable.h	rev 19972
- *   /trunk/src/kits/support/Flattenable.cpp rev 12963
+ *		src/kits/support/Flattenable.cpp	rev 12963
  */
 
-/*!
-  \file Flattenable.h
-  \brief Provides the BFlattenable interface
-*/
 
 /*!
-  \class BFlattenable
+	\file Flattenable.h
-  \ingroup support
+	\ingroup support
-  \ingroup libbe
+	\ingroup libbe
-  \brief Interface for classes that can flatten and unflatten themselves to
+	\brief Provides the BFlattenable interface
-    a stream of bytes.
+*/
-   
+
-  It is convenient that objects can be stored as a flat stream of bytes. In
+
-  this way, they can be written to disk, exchanged between applications or send
+/*!
-  over networks. This ability, which is known in many other programming
+	\class BFlattenable
-  languages as marshalling, is not native in C++. The Haiku API has created a
+	\ingroup support
-  universal interface that classes have if they are able to be flattened. This
+	\ingroup libbe
-  class defines the interface. This class does nothing on its own, and
+	\brief Interface for classes that can flatten and unflatten themselves to
-  therefore contains pure virtuals. By inheriting this class and inmplementing
+		   a stream of bytes.
-  the methods in your own class, you will be able to use your objects as
+
-  flattenable objects throughout the Haiku API.
+	It is convenient that objects can be stored as a flat stream of bytes. In
-  
+	this way, they can be written to disk, exchanged between applications or send
-  Flattened objects can be used for example when sending messages within an
+	over networks. This ability, which is known in many other programming
-  application or between applications. The BMessage class uses the interface
+	languages as marshalling, is not native in C++. The Haiku API has created a
-  to store and transmit custom classes. 
+	universal interface that classes have if they are able to be flattened. This
-  
+	class defines the interface. This class does nothing on its own, and
-  If you want to be able to flatten your objects, you will need to implement
+	therefore contains pure virtuals. By inheriting this class and inmplementing
-  various methods. Flatten() and Unflatten() are where the magic happen. These
+	the methods in your own class, you will be able to use your objects as
-  methods handle the actual flattening and unflattening. To identify flattened
+	flattenable objects throughout the Haiku API.
-  data in for example BMessage, the object has a type_code. Type codes are
+
-  four byte long integers. You can choose to flatten to one of the existing
+	Flattened objects can be used for example when sending messages within an
-  types, if you are certain that you are compatible to those, but you'll
+	application or between applications. The BMessage class uses the interface
-  usually define your own type. Your best option is by using a multicharacter
+	to store and transmit custom classes. 
-  constant, such as 'STRI'. Implement TypeCode() to return the type you
+
-  support. Implement FlattenedSize() to make sure that other objects can
+	If you want to be able to flatten your objects, you will need to implement
-  provide the right buffers. Implement IsFixedSize() to return whether your
+	various methods. Flatten() and Unflatten() are where the magic happen. These
-  objects always store to a fixed size.
+	methods handle the actual flattening and unflattening. To identify flattened
-  
+	data in for example BMessage, the object has a type_code. Type codes are
-  See the following example:
+	four byte long integers. You can choose to flatten to one of the existing
-  \code
+	types, if you are certain that you are compatible to those, but you'll
+	usually define your own type. Your best option is by using a multicharacter
+	constant, such as 'STRI'. Implement TypeCode() to return the type you
+	support. Implement FlattenedSize() to make sure that other objects can
+	provide the right buffers. Implement IsFixedSize() to return whether your
+	objects always store to a fixed size.
+
+	See the following example:
+\code
 type_code CUSTOM_STRING_TYPE = 'CUST';
 
 class CustomString : public BFlattenable
 {
 public:
-  char data[100];
+    char data[100];
 
-  // From BFlattenable
+    // From BFlattenable
-  bool IsFixedSize() const { return false; };
+    bool IsFixedSize() const { return false; };
-  type_code TypeCode() const { return CUSTOM_STRING_TYPE; };
+    type_code TypeCode() const { return CUSTOM_STRING_TYPE; };
-  ssize_t FlattenedSize() const { return strlen(data); };
+    ssize_t FlattenedSize() const { return strlen(data); };
-  
+
-  status_t Flatten(void* buffer, ssize_t size) const
+    status_t Flatten(void* buffer, ssize_t size) const
-  {
+    {
-    if ((strlen(data) + 1) < size)
+        if ((strlen(data) + 1) < size)
-      return B_BAD_VALUE;
+            return B_BAD_VALUE;
-    memcpy(buffer, data, size);
+        memcpy(buffer, data, size);
-    return B_OK;
+        return B_OK;
-  };
+    };
-  
+
-  status_t Unflatten(type_code code, const void* buffer, ssize_t size)
+    status_t Unflatten(type_code code, const void* buffer, ssize_t size)
-  {
+    {
-    if (code != CUSTOM_STRING_TYPE)
+        if (code != CUSTOM_STRING_TYPE)
-      return B_BAD_TYPE;
+            return B_BAD_TYPE;
-    if (size > 100)
+        if (size > 100)
-      return B_NO_MEMORY;
+            return B_NO_MEMORY;
-    memcpy(data, buffer, size);
+        memcpy(data, buffer, size);
-    return B_OK;
+        return B_OK;
-  };
+    };
 };
-  \endcode
+\endcode
-  
+
-  Have a look at TypeConstants.h for a list of all the types that the Haiku
+	Have a look at TypeConstants.h for a list of all the types that the Haiku
-  API defines. 
+	API defines.
-  
+
-  The Haiku API has a second interface for storing objects, which is with
+	The Haiku API has a second interface for storing objects, which is with
-  BArchivable. BArchivable is for more complex cases. Instead of one flat
+	BArchivable. BArchivable is for more complex cases. Instead of one flat
-  datastream, it stores an object in a BMessage. In that way you can reflect
+	datastream, it stores an object in a BMessage. In that way you can reflect
-  internals of a class better. It also provides an interface for instantiating
+	internals of a class better. It also provides an interface for instantiating
-  objects, that is, for objects to restore themselves from a BMessage. In
+	objects, that is, for objects to restore themselves from a BMessage. In
-  essence, BArchivable is more suitable for objects that are alive. In short
+	essence, BArchivable is more suitable for objects that are alive. In short
-  BFlattenable is for data objects, BArchivable is for 'live' objects.
+	BFlattenable is for data objects, BArchivable is for 'live' objects.
-  
+
-  Other classes in the API that support flattening and unflattening are for
+	Other classes in the API that support flattening and unflattening are for
-  example BMessage, which enables you to conveniently write flattened data
+	example BMessage, which enables you to conveniently write flattened data
-  to disk. Another example is BPath. Because of that you can store paths and
+	to disk. Another example is BPath. Because of that you can store paths and
-  send them over via messages. Throughout the Haiku API you will find classes
+	send them over via messages. Throughout the Haiku API you will find classes
-  that provide the flattening interface.
+	that provide the flattening interface.
 */
 
-/*!
-  \fn virtual bool BFlattenable::IsFixedSize() const = 0
-  \brief Pure virtual that should return whether or not flattened objects of 
-    this type always have a fixed size. 
-*/
 
 /*!
-  \fn virtual type_code BFlattenable::TypeCode() const = 0
+	\fn virtual bool BFlattenable::IsFixedSize() const
-  \brief Pure virtual that should return which type_code this class flattens 
+	\brief Pure virtual that should return whether or not flattened objects of 
-    to.
+		   this type always have a fixed size.
-  
-  \return Either one of the existing typecodes, found in TypeConstants.h, 
-  <em>if your class actually is compatible to those formats</em>, or a custom
-  four byte integer constant.
 */
 
-/*!
-  \fn virtual ssize_t BFlattenable::FlattenedSize() const = 0
-  \brief Pure virtual that should return the size of the flattened object in
-    bytes.
-*/
 
 /*!
-  \fn virtual	status_t BFlattenable::Flatten(void* buffer, ssize_t size) const = 0
+	\fn virtual type_code BFlattenable::TypeCode() const
-  \brief Pure virtual that should flatten the object into the supplied 
+	\brief Pure virtual that returns the type_code this class flattens to.
-    \a buffer.
+
-  
+	\return Either one of the existing typecodes found in TypeConstants.h
-  Please make sure that you check that the supplied buffer is not a \c NULL
+		if your class actually is compatible to those formats, or a
-  pointer. Also make sure that the size of the flattened object does isn't
+		custom four-byte integer constant if not.
-  larger than the size of the buffer. 
-  
-  \param buffer The buffer to flatten in.
-  \param size The size of the buffer.
-  \retval B_OK The object was flattened.
-  \retval B_NO_MEMORY The buffer was smaller than required.
-  \retval B_BAD_VALUE The buffer was a \c NULL pointer.
 */
 
-/*!
-  \fn bool BFlattenable::AllowsTypeCode(type_code code) const
-  \brief Return whether or not the supplied type_code is supported.
-  
-  This default implementation checks the \a code argument against the type_code
-  returned by TypeCode().
-  
-  \param code The type_code constant you want to check for.
-  \retval true The type_code is supported.
-  \retval false The type_code is not supported.
-*/
 
 /*!
-  \fn virtual status_t BFlattenable::Unflatten(type_code code, const void* buffer, ssize_t size) = 0
+	\fn virtual ssize_t BFlattenable::FlattenedSize() const
-  \brief Pure virtual that should unflatten the buffer and put the contents
+	\brief Pure virtual that should return the size of the flattened object in
-    into the current object.
+		   bytes.
-    
-  Make sure that the supplied buffer is not \c NULL and that you actually
-  support the typecode.
-  
-  \param code The type_code this data is.
-  \param buffer The buffer to unflatten the data from.
-  \param size The size of the data.
-  \retval B_OK The object is unflattened.
-  \retval B_BAD_VALUE The \a buffer pointer is \c NULL or the data is invalid.
-  \retval B_BAD_TYPE You don't support data with this \a code. 
 */
 
+
 /*!
-  \fn virtual BFlattenable::~BFlattenable()
+	\fn virtual status_t BFlattenable::Flatten(void* buffer, ssize_t size) const
-  \brief Destructor. Does nothing.
+	\brief Pure virtual that should flatten the object into the supplied
+		   \a buffer.
+
+	Please make sure that you check that the supplied buffer is not a \c NULL
+	pointer. Also make sure that the size of the flattened object does isn't
+	larger than the size of the buffer.
+
+	\param buffer The buffer to flatten in.
+	\param size The size of the buffer.
+
+	\retval B_OK The object was flattened.
+	\retval B_NO_MEMORY The buffer was smaller than required.
+	\retval B_BAD_VALUE The buffer was a \c NULL pointer.
+*/
+
+
+/*!
+	\fn bool BFlattenable::AllowsTypeCode(type_code code) const
+	\brief Get whether or not the supplied type_code is supported.
+
+	This default implementation checks the \a code argument against the type_code
+	returned by TypeCode().
+
+	\param code The type_code constant you want to check for.
+
+	\returns Whether or not the supplied type_code is supported.
+	\retval true The type_code is supported.
+	\retval false The type_code is not supported.
+*/
+
+
+/*!
+	\fn virtual status_t BFlattenable::Unflatten(type_code code,
+		const void* buffer, ssize_t size)
+	\brief Pure virtual that should unflatten the buffer and put the contents
+		   into the current object.
+
+	Make sure that the supplied buffer is not \c NULL and that you actually
+	support the typecode.
+
+	\param code The type_code this data is.
+	\param buffer The buffer to unflatten the data from.
+	\param size The size of the data.
+
+	\returns A status code.
+	\retval B_OK The object is unflattened.
+	\retval B_BAD_VALUE The \a buffer pointer is \c NULL or the data is invalid.
+	\retval B_BAD_TYPE You don't support data with this \a code. 
+*/
+
+
+/*!
+	\fn virtual BFlattenable::~BFlattenable()
+	\brief Destructor. Does nothing.
 */

docs/user/support/List.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -11,13 +11,15 @@
  *		John Drinkwater, [email protected]
  *
  * Corresponds to:
- *		/trunk/headers/os/support/List.h  rev 19972
+ *		headers/os/support/List.h	rev 19972
- *		/trunk/src/kits/support/List.cpp  rev 18649
+ *		src/kits/support/List.cpp	rev 18649
  */
 
 
 /*!
 	\file List.h
+	\ingroup support
+	\ingroup libbe
 	\brief Defines the BList class.
 */
 
@@ -28,37 +30,36 @@
 	\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 programmer
 	to make sure proper data is entered since the compiler cannot check this by
 	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 nor any ordering. These properties makes it useful in a whole
 	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 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 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
@@ -68,49 +69,43 @@
 	large number of items, choose a higher value. 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 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
 	performance critical parts of the code, you are safe to go with the default
 	values.
-	
+
 	\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.
-	
+
 	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.
@@ -119,25 +114,23 @@
 	\see 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 false Item was not appended, since resizing the list failed.
 	\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 altered.
-	
+
 	\param list The list to be added.
 	\param index The position in the current list where the new item(s) should
 		be put.
@@ -147,14 +140,13 @@
 	\see AddList(const BList *list)
 */
 
-
 /*!
 	\fn bool BList::AddList(const BList *list)
 	\brief Append a list to this list.
-	
+
 	Note that the \a list parameter is a \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 of
@@ -162,160 +154,142 @@
 	\see 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.
 	\see RemoveItem(int32 index)
 */
 
-
 /*!
 	\fn void * BList::RemoveItem(int32 index)
 	\brief Remove the item at \a 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.
 	\see 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 an 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 was invalid.
 */
 
-
 /*!
 	\fn bool BList::MoveItem(int32 fromIndex, int32 toIndex)
 	\brief Move an item to a new place
-	
+
 	This moves a list item from position 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
-	
+
 	Moving 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 due to the indexes being 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.
 	\see 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.
 	\see LastItem() const
 */
 
-
 /*!
 	\fn void *BList::ItemAtFast(int32 index) const
 	\brief Get an item.
-	
+
 	This method does not perform any boundary checks when it retrieves an item.
 	Use this method in a performance critical area of your program where you are
 	sure you will not get an invalid item.
-	
+
 	\return A pointer to the item.
 */
 
-
 /*!
 	\fn void *BList::LastItem() const
 	\brief Get the last item.
@@ -323,18 +297,17 @@ 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 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 a bad idea to begin with and that you should avoid this method.
@@ -343,75 +316,63 @@ A C D E F G B H I J
 	\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 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.
 	\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.
-	
+
 	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 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.
@@ -419,5 +380,4 @@ A C D E F G B H I J
 	\see DoForEach(bool (*func)(void* item))
 */
 
-
 //! @}