Update App Kit Documentation.

The biggest change is the addition of \since to each method. I've gone
through old versions of the BeBook and documented what version of BeOS
each method was introduced in. I'm only counting production releases
so I'm starting with BeOS R3 ignoring all DR and PR releases. Likewise,
all methods new to Haiku are listed as being introduced \since Haiku R1
ignoring alpha releases.

docs/user/app/Application.dox

@@ -1,13 +1,13 @@
 /*
- * Copyright 2011 Haiku, Inc. All rights reserved.
+ * Copyright 2011-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		John Scipione, [email protected]
  * 
  * Corresponds to:
- *		headers/os/app/Application.h	rev 42794
+ *		headers/os/app/Application.h	hrev47355
- *		src/kits/app/Application.cpp	rev 42794
+ *		src/kits/app/Application.cpp	hrev47355
  */
 
 
@@ -19,6 +19,22 @@
 */
 
 
+/*!
+	\var be_app
+	\brief Global system app object.
+
+	\since BeOS R3
+*/
+
+
+/*!
+	\var be_app_messenger
+	\brief Global system app messenger object.
+
+	\since BeOS R3
+*/
+
+
 /*!
 	\class BApplication
 	\ingroup app
@@ -45,7 +61,7 @@
 	Typically, you initialize the BApplication object in the programs main()
 	function. A typical main() function looks something like this:
 
-	\code
+\code
 #include Application.h
 
 main()
@@ -57,12 +73,14 @@ main()
 
 	return 0;
 }
-	\endcode
+\endcode
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BApplication::BApplication(const char *signature)
+	\fn BApplication::BApplication(const char* signature)
 	\brief Initialize a BApplication with the passed in \a signature.
 
 	The new BApplication is, by default, not running yet. If you have
@@ -72,11 +90,13 @@ main()
 	errors.
 
 	\param signature The \a signature of the application.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BApplication::BApplication(const char *signature, status_t *_error)
+	\fn BApplication::BApplication(const char* signature, status_t* _error)
 	\brief Initialize a BApplication with the passed in \a signature and a
 	       pointer to an error message.
 
@@ -90,6 +110,8 @@ main()
 	\param signature The \a signature of the application.
 	\param _error A pointer to a \c status_t set by the BApplication
 		constructor.
+
+	\since BeOS R5
 */
 
 /*!
@@ -98,6 +120,8 @@ main()
 
 	\returns If initialization succeeded returns \c B_OK, otherwise returns an
 	         error status.
+
+	\since BeOS R5
 */
 
 
@@ -110,21 +134,25 @@ main()
 
 
 /*!
-	\fn BApplication::BApplication(BMessage *data)
+	\fn BApplication::BApplication(BMessage* data)
 	\brief Initialize a BApplication object from a message.
 
 	The message must contain the signature of the application you wish to
 	initialize in the "mime_sig" variable.
 
 	\param data The message to initialize the BApplication from.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BApplication::Archive(BMessage *data, bool deep) const
+	\fn status_t BApplication::Archive(BMessage* data, bool deep) const
 	\brief Archive the BApplication object into a BMessage.
 
 	\sa BArchivable::Archive()
+
+	\since BeOS R3
 */
 
 
@@ -133,6 +161,8 @@ main()
 	\brief Restores the BApplication object from a BMessage.
 
 	\sa BArchivable::Instantiate()
+
+	\since BeOS R3
 */
 
 
@@ -142,6 +172,8 @@ main()
 /*!
 	\fn BApplication::~BApplication()
 	\brief Destructor Method
+
+	\since BeOS R3
 */
 
 
@@ -156,10 +188,13 @@ main()
 /*!
 	\fn thread_id BApplication::Run()
 	\brief Starts the message loop in the thread that it is called from,
-		and doesn't return until the message loop stops. Run() does not spawn
+	       and doesn't return until the message loop stops.
-		a new thread.
 
-	\returns the thread_id of the thread that the BApplication is called from.
+	Run() does not spawn a new thread.
+
+	\return The thread_id of the thread that the BApplication is called from.
+
+	\since BeOS R3
 */
 
 
@@ -175,6 +210,8 @@ main()
 	should delete the BApplication object yourself one Run() returns.
 	However Quit() does delete the object if it's called before the message loop
 	starts i.e. before Run() is called.
+
+	\since BeOS R3
 */
 
 
@@ -200,8 +237,10 @@ main()
 	\c true. If any of the BWindow returns \c false, the BWindow s
 	are not destroyed and QuitRequested() returns \c false.
 
-	\retval true The application quit.
+	\return \c true if the application quit or \c false if the
-	\retval false The application failed to quit.
+	        application failed to quit.
+
+	\since BeOS R3
 */
 
 
@@ -219,11 +258,13 @@ main()
 	ReadyToRun() method to do whatever you want to do. If you haven't
 	constructed any windows in your application yet then this would be a good
 	place to do so.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn void BApplication::ArgvReceived(int32 argc, char **argv)
+	\fn void BApplication::ArgvReceived(int32 argc, char** argv)
 	\brief Hook method that gets invoked when the application receives a
 	       \c B_ARGV_RECEIVED message.
 
@@ -251,6 +292,8 @@ main()
 	generate a \c B_ARGV_RECEIVED message and send it to the already running
 	instance. Thus in this case the \c B_ARGV_RECEIVED message can show
 	up at any time.
+
+	\since BeOS R3
 */
 
 
@@ -270,11 +313,13 @@ main()
 
 	This method is called after ReadyToRun() provided the application is
 	displaying a window that can be set active.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn void BApplication::RefsReceived(BMessage *message)
+	\fn void BApplication::RefsReceived(BMessage* message)
 	\brief Hook method that gets invoked when the application receives a
 	       \c B_REFS_RECEIVED message.
 
@@ -288,8 +333,10 @@ main()
 	something with the received refs. Typically you create BEntry or BFile
 	objects from the passed in refs.
 
-	\param message contains a single field named "be:refs" that contains one or
+	\param message contains a single field named "be:refs" that contains one
-		more entry_ref (\c B_REF_TYPE) items, one for each file sent.
+	       or more entry_ref (\c B_REF_TYPE) items, one for each file sent.
+
+	\since BeOS R3
 */
 
 
@@ -302,6 +349,8 @@ main()
 	about the application.
 
 	The default implementation pops a basic alert dialog.
+
+	\since BeOS R3
 */
 
 
@@ -319,18 +368,24 @@ main()
 /*!
 	\fn BApplication::ShowCursor()
 	\brief Restores the cursor.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn void BApplication::HideCursor()
 	\brief Hides the cursor from the screen.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn void BApplication::ObscureCursor()
 	\brief Hides the cursor until the mouse is moved.
+
+	\since BeOS R3
 */
 
 
@@ -339,11 +394,13 @@ main()
 	\brief Returns whether or not the cursor is hidden.
 
 	\returns \c true if the cursor is hidden, \c false if not.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn void BApplication::SetCursor(const void *cursor)
+	\fn void BApplication::SetCursor(const void* cursor)
 	\brief Sets the \a cursor to be used when the application is active.
 
 	You can pass one of the pre-defined cursor constants such as
@@ -352,11 +409,13 @@ main()
 	class.
 
 	\param cursor The cursor data to set the cursor to.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn void BApplication::SetCursor(const BCursor *cursor, bool sync)
+	\fn void BApplication::SetCursor(const BCursor* cursor, bool sync)
 	\brief Sets the \a cursor to be used when the application is active
 	       with \a sync immediately option.
 
@@ -365,6 +424,8 @@ main()
 
 	\param cursor A BCursor object to set the \a cursor to.
 	\param sync synchronize the cursor immediately.
+
+	\since BeOS R5
 */
 
 
@@ -384,6 +445,8 @@ main()
 	\brief Returns the number of windows created by the application.
 
 	\returns the number of windows created by the application.
+
+	\since BeOS R3
 */
 
 
@@ -400,6 +463,8 @@ main()
 
 	\returns The BWindow object at the specified \a index or \c NULL
 	         if the \a index is out of range.
+
+	\since BeOS R3
 */
 
 
@@ -410,6 +475,8 @@ main()
 	\warning This method may return \c B_ERROR.
 
 	\returns The number of BLoopers in the application.
+
+	\since BeOS R5
 */
 
 
@@ -422,6 +489,8 @@ main()
 
 	\returns The BLooper object at the specified \a index or \c NULL
 	         if the \a index is out of range.
+
+	\since BeOS R5
 */
 
 
@@ -443,6 +512,8 @@ main()
 
 	\returns \c true if the application is launching, \c false if the
 	         application is already running.
+
+	\since BeOS R3
 */
 
 
@@ -457,12 +528,16 @@ main()
 	\returns \c B_NO_INIT on an error or \c B_OK if all goes well.
 
 	\sa BRoster::GetAppInfo()
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BResources* BApplication::AppResources()
 	\brief Returns a BResources object for the application.
+
+	\since BeOS R5
 */
 
 
@@ -479,14 +554,14 @@ main()
 
 /*!
 	\fn void BApplication::MessageReceived(BMessage *message)
-	\sa BHandler::MessageReceived()
+	\copydoc BHandler::MessageReceived()
 */
 
 
 /*!
 	\fn void BApplication::DispatchMessage(BMessage *message,
 		BHandler *handler)
-	\sa BLooper::DispatchMessage()
+	\copydoc BLooper::DispatchMessage()
 */
 
 
@@ -512,6 +587,8 @@ main()
 	is no better than once per 100,000 microseconds.
 
 	\sa SetPulseRate()
+
+	\since BeOS R3
 */
 
 
@@ -524,6 +601,8 @@ main()
 
 	\param rate The rate at which \c B_PULSE messages are sent to the
 	       application.
+
+	\since BeOS R3
 */
 
 
@@ -539,15 +618,15 @@ main()
 
 
 /*!
-	\fn BHandler* BApplication::ResolveSpecifier(BMessage *message, int32 index,
+	\fn BHandler* BApplication::ResolveSpecifier(BMessage* message,
-		BMessage *specifier, int32 what, const char *property)
+		int32 index, BMessage *specifier, int32 what, const char *property)
-	\sa BHandler::ResolveSpecifier()
+	\copydoc BHandler::ResolveSpecifier()
 */
 
 
 /*!
-	\fn status_t BApplication::GetSupportedSuites(BMessage *data)
+	\fn status_t BApplication::GetSupportedSuites(BMessage* data)
-	\sa BHandler::GetSupportedSuites()
+	\copydoc BHandler::GetSupportedSuites()
 */
 
 

docs/user/app/Clipboard.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2011 Haiku, Inc. All rights reserved.
+ * Copyright 2011-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -7,8 +7,8 @@
  *		John Scipione, [email protected]
  * 
  * Corresponds to:
- *		headers/os/app/Clipboard.h	 rev 42274
+ *		headers/os/app/Clipboard.h	 hrev47355
- *		src/kits/app/Clipboard.cpp	 rev 42274
+ *		src/kits/app/Clipboard.cpp	 hrev47355
  */
 
 
@@ -23,6 +23,8 @@
 /*!
 	\var be_clipboard
 	\brief Global system clipboard object.
+
+	\since BeOS R3
 */
 
 
@@ -97,11 +99,13 @@ if (be_clipboard->Lock()) {
 } else
 	fprintf(stderr, "could not lock clipboard.\n");
 \endcode
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BClipboard::BClipboard(const char *name, bool transient = false)
+	\fn BClipboard::BClipboard(const char* name, bool transient = false)
 	\brief Create a BClipboard object with the given \a name.
 
 	If the \a name parameter is \c NULL then the "system" BClipboard object
@@ -109,12 +113,16 @@ if (be_clipboard->Lock()) {
 
 	\param name The \a name of the clipboard.
 	\param transient If \c true, lose data after a reboot (currently unused).
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BClipboard::~BClipboard()
 	\brief Destroys the BClipboard object. The clipboard data is not destroyed.
+
+	\since BeOS R3
 */
 
 
@@ -123,11 +131,13 @@ if (be_clipboard->Lock()) {
 	\brief Returns the name of the BClipboard object.
 
 	\returns The name of the clipboard.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\name Commit Count Methods
+	\name Commit Count
 */
 
 
@@ -147,6 +157,8 @@ if (be_clipboard->Lock()) {
 	\return The number of commits to the clipboard.
 
 	\sa SystemCount()
+
+	\since BeOS R5
 */
 
 
@@ -164,6 +176,8 @@ if (be_clipboard->Lock()) {
 	\return The number of commits to the clipboard.
 
 	\sa LocalCount()
+
+	\since BeOS R5
 */
 
 
@@ -171,7 +185,7 @@ if (be_clipboard->Lock()) {
 
 
 /*!
-	\name Monitoring Methods
+	\name Monitoring
 */
 
 
@@ -190,6 +204,8 @@ if (be_clipboard->Lock()) {
 	\retval B_ERROR An error occured.
 
 	\sa StopWatching()
+
+	\since BeOS R5
 */
 
 
@@ -202,6 +218,8 @@ if (be_clipboard->Lock()) {
 	\retval B_ERROR An error occurred.
 
 	\sa StartWatching()
+
+	\since BeOS R5
 */
 
 
@@ -209,7 +227,7 @@ if (be_clipboard->Lock()) {
 
 
 /*!
-	\name Locking Methods
+	\name Locking
 */
 
 
@@ -226,6 +244,8 @@ if (be_clipboard->Lock()) {
 	\returns \c true if the clipboard was locked, \c false otherwise.
 
 	\sa Unlock()
+
+	\since BeOS R3
 */
 
 
@@ -234,6 +254,8 @@ if (be_clipboard->Lock()) {
 	\brief Unlocks the clipboard.
 
 	\sa Lock()
+
+	\since BeOS R3
 */
 
 
@@ -242,6 +264,8 @@ if (be_clipboard->Lock()) {
 	\brief Returns whether or not the clipboard is locked.
 
 	\returns \c true if the clipboard is locked, \c false if it is unlocked.
+
+	\since BeOS R5
 */
 
 
@@ -249,7 +273,7 @@ if (be_clipboard->Lock()) {
 
 
 /*!
-	\name Clipboard Data Transaction Methods
+	\name Clipboard Data Transaction
 */
 
 
@@ -262,10 +286,13 @@ if (be_clipboard->Lock()) {
 
 	You should call Clear() before adding new data to the BClipboard object.
 
+	\return A status code.
 	\retval B_OK Everything went find.
 	\retval B_NOT_ALLOWED The clipboard is not locked.
 	\retval B_NO_MEMORY Ran out of memory initializing the data message.
 	\retval B_ERROR Another error occurred.
+
+	\since BeOS R3
 */
 
 
@@ -273,9 +300,12 @@ if (be_clipboard->Lock()) {
 	\fn status_t BClipboard::Commit()
 	\brief Commits the clipboard data to the BClipboard object.
 
+	\return A status code.
 	\retval B_OK Everything went find.
 	\retval B_NOT_ALLOWED The clipboard is not locked.
 	\retval B_ERROR Another error occurred.
+
+	\since BeOS R3
 */
 
 
@@ -287,9 +317,12 @@ if (be_clipboard->Lock()) {
 	\param failIfChanged Whether or not to fail to commit the changes
 		if there is a change in the clipboard data.
 
+		\return A status code.
 	\retval B_OK Everything went find.
 	\retval B_NOT_ALLOWED The clipboard is not locked.
 	\retval B_ERROR Another error occurred.
+
+	\since BeOS R5
 */
 
 
@@ -301,10 +334,13 @@ if (be_clipboard->Lock()) {
 	clipboard data message and then decide to revert the change instead of
 	committing it.
 
+	\return A status code.
 	\retval B_OK Everything went find.
 	\retval B_NOT_ALLOWED The clipboard is not locked.
 	\retval B_NO_MEMORY Ran out of memory initializing the data message.
 	\retval B_ERROR Another error occurred.
+
+	\since BeOS R5
 */
 
 
@@ -312,7 +348,7 @@ if (be_clipboard->Lock()) {
 
 
 /*!
-	\name Clipboard Data Message Methods
+	\name Clipboard Data Message
 */
 
 
@@ -328,6 +364,8 @@ if (be_clipboard->Lock()) {
 
 	\returns A BMessenger object that targets the application that last
 		modified the clipboard.
+
+	\since BeOS R3
 */
 
 
@@ -340,6 +378,8 @@ if (be_clipboard->Lock()) {
 
 	\returns A pointer to the BMessage object that holds the clipboard
 		data or \c NULL if the clipboard is not locked.
+
+	\since BeOS R3
 */
 
 

docs/user/app/Cursor.dox

@@ -1,13 +1,13 @@
 /*
- * Copyright 2012 Haiku, Inc. All rights reserved.
+ * Copyright 2012-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		John Scipione, [email protected]
  * 
  * Corresponds to:
- *		headers/os/app/Cursor.h	 hrev45039
+ *		headers/os/app/Cursor.h	 hrev47355
- *		src/kits/app/Cursor.cpp	 hrev45039
+ *		src/kits/app/Cursor.cpp	 hrev47355
  */
 
 
@@ -22,180 +22,240 @@
 /*!
 	\enum BCursorID
 	List of predefined cursor IDs
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_SYSTEM_DEFAULT
 	System default cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_CONTEXT_MENU
 	Context menu cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_COPY
 	Copy cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_CREATE_LINK
 	Symlink cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_CROSS_HAIR
 	Cross hairs cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_FOLLOW_LINK
 	Follow html link cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_GRAB
 	Grab cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_GRABBING
 	Grabbing cursor (mouse down)
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_HELP
 	Help cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_I_BEAM
 	I beam cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_I_BEAM_HORIZONTAL
 	Horizontal I beam cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_MOVE
 	Move cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_NO_CURSOR
 	No cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_NOT_ALLOWED
 	Not allowed cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_PROGRESS
 	Progress cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_RESIZE_NORTH
 	Resize north cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_RESIZE_EAST
 	Resize east cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_RESIZE_SOUTH
 	Resize south cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_RESIZE_WEST
 	Resize west cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_RESIZE_NORTH_EAST
 	Resize north east cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_RESIZE_NORTH_WEST
 	Resize north west cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_RESIZE_SOUTH_EAST
 	Resize south east cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_RESIZE_SOUTH_WEST
 	Resize south west cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_RESIZE_NORTH_SOUTH
 	Resize north south cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_RESIZE_EAST_WEST
 	Resize east west cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_RESIZE_NORTH_EAST_SOUTH_WEST
 	Resize north east south west cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_RESIZE_NORTH_WEST_SOUTH_EAST
 	Resize north west south east cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_ZOOM_IN
 	Zoom in cursor
+
+	\since BeOS R5
 */
 
 
 /*!
 	\var BCursorID B_CURSOR_ID_ZOOM_OUT
 	Zoom out cursor
+
+	\since BeOS R5
 */
 
 
@@ -207,6 +267,8 @@
 
 	\note As BeOS only supports 16x16 monochrome cursors, to see a nice
 		  shadowed one we will need to extend this.
+
+	\since BeOS R5
 */
 
 
@@ -218,6 +280,8 @@
 	with the cursor data.
 
 	\param cursorData The cursor data.
+
+	\since BeOS R5
 */
 
 
@@ -226,6 +290,8 @@
 	\brief Initializes a new cursor object from a predefined cursor \a id.
 
 	\param id The predefined \a id to initialize to.
+
+	\since BeOS R5
 */
 
 
@@ -234,6 +300,8 @@
 	\brief Initializes a new cursor object from another cursor object.
 
 	\param other The cursor object to initialize from.
+
+	\since BeOS R5
 */
 
 
@@ -242,24 +310,32 @@
 	\brief Initializes a new cursor object from a message archive.
 
 	\param data The message data to initialize from.
+
+	\since BeOS R5
 */
 
 
 /*!
 	\fn BCursor::~BCursor()
 	\brief Destroy the cursor and free it's memory.
+
+	\since BeOS R5
 */
 
 
 /*!
 	status_t BCursor::Archive(BMessage *into, bool deep) const
 	\brief Archive the cursor. Not implemented.
+
+	\since BeOS R5
 */
 
 
 /*!
 	BArchivable* BCursor::Instantiate(BMessage *data)
 	\brief Instantiate the cursor from a message. Not implemented.
+
+	\since BeOS R5
 */
 
 
@@ -270,6 +346,8 @@
 	\param other The cursor object to copy from.
 
 	\returns the new cursor object.
+
+	\since BeOS R5
 */
 
 
@@ -281,6 +359,8 @@
 
 	\returns \c true if the cursor objects are equal, \c false if the cursor
 	         objects are not equal.
+
+	\since BeOS R5
 */
 
 
@@ -292,4 +372,6 @@
 
 	\returns \c true if the cursor objects are not equal, \c false if the cursor
 		objects are equal.
+
+	\since BeOS R5
 */

docs/user/app/Handler.dox

@@ -1,13 +1,14 @@
 /*
- * Copyright 2007 Haiku, Inc. All rights reserved.
+ * Copyright 2007-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		Niels Sascha Reedijk, [email protected]
+ *		John Scipione, [email protected]
  *
  * Corresponds to:
- *		headers/os/app/Handler.h	rev 22577
+ *		headers/os/app/Handler.h	hrev47355
- *		src/kits/app/Handler.cpp	rev 21332
+ *		src/kits/app/Handler.cpp	hrev47355
  */
 
 /*!
@@ -24,6 +25,8 @@
 /*!
 	\def B_OBSERVE_WHAT_CHANGE
 	\brief Internal.
+
+	\since BeOS R5
 */
 
 
@@ -37,6 +40,8 @@
 	but with the what constant set to \c B_OBSERVER_NOTICE_CHANGE. The original
 	\c what constant of the transmitted data message is stored behind the
 	label defined by this constant.
+
+	\since BeOS R5
 */
 
 
@@ -46,6 +51,8 @@
 	
 	\note Specifying this parameter as the \a what value, leads to the same
 		results as calling BHandler::StartWatchingAll().
+
+	\since BeOS R5
 */
 
 
@@ -120,16 +127,20 @@
 	BHandler is a part of the chain in the eloquent messaging structure. For a
 	proper understanding of all its facets, have a look at the \ref app_messaging
 	"messaging overview".
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BHandler::BHandler(const char *name)
+	\fn BHandler::BHandler(const char* name)
 	\brief Construct a new handler with a \a name.
 
 	The newly constructed handler is not associated with a looper until you
 	explicitly request this to happen. To associate this handler with a looper,
 	use BLooper::AddHandler().
+
+	\since BeOS R3
 */
 
 
@@ -144,16 +155,21 @@
 	\warning This constructor does no type check whatsoever. Since you can pass
 		any BMessage, you should - if you are not sure about the exact type -
 		use the Instantiate() method, which does check the type.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BArchivable *BHandler::Instantiate(BMessage *data)
+	\fn BArchivable* BHandler::Instantiate(BMessage* data)
 	\brief Static method to instantiate a handler from an archived message.
 
 	\return A pointer to the instantiated handler, or \c NULL if the \a data
 		is not a valid archived BHandler object.
+
 	\see BHandler(BMessage* data)
+
+	\since BeOS R3
 */
 
 
@@ -178,11 +194,13 @@
 	Note that only the name is stored. The filters, the associated looper and
 	the observers are not stored, and should be manually added when you are
 	using this object.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BHandler::Archive(BMessage *data, bool deep) const
+	\fn status_t BHandler::Archive(BMessage* data, bool deep) const
 	\brief Archive a handler to a message
 
 	Currently, only the name is archived. The filters, the associated looper
@@ -190,9 +208,14 @@
 
 	\param data The message to archive the object in.
 	\param deep This parameter is ignored, as BHandler does not have children.
+
+	\return A status code.
 	\retval B_OK Archiving succeeded.
 	\retval B_BAD_VALUE The \a data parameter is not a valid message.
-	\see BHandler::Instantiate(BMessage *data)
+
+	\see BHandler::Instantiate(BMessage* data)
+
+	\since BeOS R3
 */
 
 
@@ -211,7 +234,7 @@
 
 
 /*!
-	\fn void BHandler::MessageReceived(BMessage *message)
+	\fn void BHandler::MessageReceived(BMessage* message)
 	\brief Handle \a message that has been received by the associated looper.
 
 	This method is reimplemented by subclasses. If the messages that have
@@ -250,40 +273,51 @@ ShowImageApp::MessageReceived(BMessage *message)
 	which will reply with \c B_MESSAGE_NOT_UNDERSTOOD.
 
 	\attention If you want to keep or manipulate the \a message, have a
-		look at BLooper::DetachCurrentMessage() to receive ownership of
+	           look at BLooper::DetachCurrentMessage() to receive ownership
-		the \a message.
+	           of the \a message.
 
 	\param message The message that needs to be handled.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BLooper *BHandler::Looper() const
+	\fn BLooper* BHandler::Looper() const
 	\brief Return a pointer to the looper that this handler is associated with.
 
 	\return If the handler is not yet associated with a looper, it will return
 	        \c NULL.
+
 	\see BLooper::AddHandler()
 	\see LockLooper()
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn void BHandler::SetName(const char *name)
 	\brief Set or change the name of this handler.
+
 	\see Name()
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn const char *BHandler::Name() const
+	\fn const char* BHandler::Name() const
 	\brief Return the name of this handler.
+
 	\see SetName()
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn void BHandler::SetNextHandler(BHandler *handler)
+	\fn void BHandler::SetNextHandler(BHandler* handler)
 	\brief Set the next handler in the chain that the message is passed on to
 	       if this \a handler cannot process it.
 
@@ -299,14 +333,19 @@ ShowImageApp::MessageReceived(BMessage *message)
 	a looper with BLooper::AddHander().
 
 	\see NextHandler()
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BHandler *BHandler::NextHandler() const
+	\fn BHandler* BHandler::NextHandler() const
 	\brief Return the next hander in the chain to which the message is passed
 	       on.
+
 	\see SetNextHandler()
+
+	\since BeOS R3
 */
 
 
@@ -335,12 +374,15 @@ ShowImageApp::MessageReceived(BMessage *message)
 	stored. As such, you need to make sure that the \a filter object exists as
 	long as it is added to this handler.
 
-	\see RemoveFilter(), SetFilterList()
+	\see RemoveFilter()
+	\see SetFilterList()
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn bool BHandler::RemoveFilter(BMessageFilter *filter)
+	\fn bool BHandler::RemoveFilter(BMessageFilter* filter)
 	\brief Remove \a filter from the filter list.
 
 	If the handler is associated with a looper, this looper needs to be locked
@@ -349,10 +391,13 @@ ShowImageApp::MessageReceived(BMessage *message)
 	Note that the \a filter is not deleted, merely removed from the list. You
 	need to take care of the memory yourself.
 
-	\retval true The \a filter was in the filter list and is removed.
+	\return \c true if the \a filter was in the filter list and is removed,
-	\retval false The \a filter was not found in the filter list.
+	        \c false if the \a filter was not found in the filter list.
 
-	\see AddFilter(), FilterList()
+	\see AddFilter()
+	\see FilterList()
+
+	\since BeOS R3
 */
 
 
@@ -367,18 +412,24 @@ ShowImageApp::MessageReceived(BMessage *message)
 	existing filters will be \b deleted.
 
 	\see AddFilter(), FilterList()
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BList *BHandler::FilterList()
+	\fn BList* BHandler::FilterList()
 	\brief Return a pointer to the list of filters.
 
 	\return A pointer to the list of filters. Do not manipulate the list of
-		filters directly, but use the methods provided by this class, in order
+	        filters directly, but use the methods provided by this class, in
-		to maintain internal consistency.
+	        order to maintain internal consistency.
 
-	\see AddFilter(), RemoveFilter(), SetFilterList().
+	\see AddFilter()
+	\see RemoveFilter()
+	\see SetFilterList().
+
+	\since BeOS R3
 */
 
 
@@ -403,10 +454,13 @@ ShowImageApp::MessageReceived(BMessage *message)
 	\fn bool BHandler::LockLooper()
 	\brief Lock the looper associated with this handler.
 
-	\retval true The looper is locked.
+	\return \c true if the looper is locked, \c false if there was an error
-	\retval false There was an error acquiring the lock.
+	        acquiring the lock.
 
-	\see LockLooperWithTimeout(), UnlockLooper()
+	\see LockLooperWithTimeout()
+	\see UnlockLooper()
+
+	\since BeOS R4
 */
 
 
@@ -415,21 +469,27 @@ ShowImageApp::MessageReceived(BMessage *message)
 	\brief Lock the looper associated with this handler, with a time out value.
 
 	\param timeout The time to wait for acquiring the lock in microseconds. You
-		may also use B_INFINITE_TIMEOUT, in which this method will wait as long
+	       may also use \c B_INFINITE_TIMEOUT, in which this method will wait
-		as it takes to acquire the lock.
+	       as long as it takes to acquire the lock.
 
+	\return A status code.
 	\retval B_OK Locking succeeded.
 	\retval B_BAD_VALUE This handler is not associated with a looper (anymore).
 	\retval B_TIMED_OUT The time specified in \a timeout has passed without
 		locking the looper.
 
-	\see LockLooper(), UnlockLooper()
+	\see LockLooper()
+	\see UnlockLooper()
+
+	\since BeOS R4
 */
 
 
 /*!
 	\fn void BHandler::UnlockLooper()
 	\brief Unlock the looper.
+
+	\since BeOS R4
 */
 
 
@@ -448,16 +508,29 @@ ShowImageApp::MessageReceived(BMessage *message)
 
 
 /*!
-	\fn BHandler * BHandler::ResolveSpecifier(BMessage *msg, int32 index,
+	\fn BHandler* BHandler::ResolveSpecifier(BMessage* message, int32 index,
-		BMessage *specifier, int32 form, const char *property)
+		BMessage* specifier, int32 what, const char* property)
 	\brief Determine the proper handler for a scripting message.
+
+	\param message The scripting message to determine the handler.
+	\param index The index of the specifier.
+	\param specifier The message which contains the specifier.
+	\param what The 'what' field of the specifier message.
+	\param property The name of the target property.
+
+	\return A pointer to the proper BHandler for the given scripting
+	        message.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BHandler::GetSupportedSuites(BMessage *data)
+	\fn status_t BHandler::GetSupportedSuites(BMessage* data)
 	\brief Reports the suites of messages and specifiers that derived classes
 		understand.
+
+	\since BeOS R3
 */
 
 
@@ -502,14 +575,16 @@ BMessenger messengerA(&A)
 B.StartWatching(messengerA, kNetworkConnection);
 \endcode
 
-	\param target The messenger from which the notifications would be
+	\param target The messenger from which the notifications would be received.
-		received.
 	\param what The state that needs to be watched.
+
 	\return During the call of this method, a notification will be transmitted
 	        using the \a target. If this works, then this method will return
 	        \c B_OK.
 
 	\see StartWatchingAll(BMessenger), StopWatching(BMessenger, uint32)
+
+	\since BeOS R5
 */
 
 
@@ -521,6 +596,8 @@ B.StartWatching(messengerA, kNetworkConnection);
 	but it will subscribe to all the state changes the \a target knows. 
 
 	\see StartWatching(BMessenger, uint32), StopWatchingAll(BMessenger)
+
+	\since BeOS R5
 */
 
 
@@ -532,6 +609,8 @@ B.StartWatching(messengerA, kNetworkConnection);
 	in a \a target.
 
 	\see StartWatching(BMessenger, uint32)
+
+	\since BeOS R5
 */
 
 
@@ -542,6 +621,8 @@ B.StartWatching(messengerA, kNetworkConnection);
 	This method will unsubscribe the \a target from watching all state changes.
 
 	\see StartWatchingAll(BMessenger)
+
+	\since BeOS R5
 */
 
 
@@ -570,6 +651,8 @@ A.StartWatching(&B, kNetworkConnection);
 		\c B_OK.
 
 	\see StartWatchingAll(BHandler*), StopWatching(BHandler*, uint32)	
+
+	\since BeOS R5
 */
 
 
@@ -582,6 +665,8 @@ A.StartWatching(&B, kNetworkConnection);
 	tracks.
 
 	\see StartWatching(BHandler*, uint32), StopWatchingAll(BHandler*)	
+
+	\since BeOS R5
 */
 
 
@@ -592,6 +677,8 @@ A.StartWatching(&B, kNetworkConnection);
 	This method will unsubscribe the \a handler from watching a specific event.
 
 	\see StartWatching(BHandler*, uint32)
+
+	\since BeOS R5
 */
 
 
@@ -602,6 +689,8 @@ A.StartWatching(&B, kNetworkConnection);
 	This method will unsubscribe the \a handler from watching all state changes.
 
 	\see StartWatchingAll(BHandler*)
+
+	\since BeOS R5
 */
 
 
@@ -624,26 +713,31 @@ A.StartWatching(&B, kNetworkConnection);
 
 
 /*!
-	\fn void BHandler::SendNotices(uint32 what, const BMessage *msg)
+	\fn void BHandler::SendNotices(uint32 what, const BMessage* notice)
 	\brief Emit a state change to the observers.
 
 	The actual state (specified by \a what) will not be transmitted. This is
 	merely for internal bookkeeping. It is not entirely unimaginable that you
 	still want to inform the observers of what actually took place. You can
-	use the \a msg to transmit this, and any other data you want. Note that the
+	use the \a msg to transmit this, and any other data you want. Note that
-	message will be copied and slightly altered: the \c what member of the
+	the message will be copied and slightly altered: the \c what member of the
 	message will be \c B_OBSERVER_NOTICE_CHANGE, and the \c what constant you
 	specified will be stored in the #B_OBSERVE_ORIGINAL_WHAT label.
 
 	\param what The identifier of the state.
-	\param msg Any data associated with the state change. You retain ownership
+	\param notice Any data associated with the state change. You retain
-		of this data, so make sure you dispose it when you are done.
+	       ownership of this data, so make sure you dispose it when you are
+	       done.
+
+	\since BeOS R5
 */
 
 
 /*!
 	\fn bool BHandler::IsWatched() const
 	\brief Check if there are any observers watching this handler.
+
+	\since BeOS R5
 */
 
 

docs/user/app/Looper.dox

@@ -1,15 +1,17 @@
 /*
- * Copyright 2008 Haiku, Inc. All rights reserved.
+ * Copyright 2008-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		Niels Sascha Reedijk, [email protected]
+ *		John Scipione, [email protected]
  *
  * Corresponds to:
- *		headers/os/app/Looper.h	rev 21863
+ *		headers/os/app/Looper.h	hrev47355
- *		src/kits/app/Looper.cpp	rev 21864
+ *		src/kits/app/Looper.cpp	hrev47355
  */
 
+
 /*!
 	\file Looper.h
 	\ingroup app
@@ -21,6 +23,8 @@
 /*!
 	\def B_LOOPER_PORT_DEFAULT_CAPACITY
 	\brief The default size of the port of a BLooper.
+
+	\since BeOS R3
 */
 
 
@@ -82,11 +86,13 @@
 	BLooper is a part of the chain in the eloquent messaging structure. For a
 	proper understanding of all its facets, have a look at the \ref app_messaging
 	"messaging overview".
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BLooper::BLooper(const char* name, int32 priority, int32 port_capacity)
+	\fn BLooper::BLooper(const char* name, int32 priority, int32 portCapacity)
 	\brief Construct a new BLooper with a \a priority and an \a capacity.
 
 	The new looper is, by default, not running yet. If you have set up
@@ -98,20 +104,22 @@
 	\param name The name of the looper.
 	\param priority The priority of the message thread of this looper. The
 	       default priority should be good enough for most tasks. Also, some
-		derived versions of BLooper will use a specialized priority. So it is
+	       derived versions of BLooper will use a specialized priority. So it
-		advised to leave this setting at the default, unless you know why you
+	       is advised to leave this setting at the default, unless you know
-		would like another setting.
+	       why you would like another setting.
-	\param port_capacity Loopers use ports to send and receive messages (see
+	\param portCapacity Loopers use ports to send and receive messages (see
 	       the kernel kit). Ports have a maximum capacity; if there are so many
-		messages queued that the port is full, all other incoming messages are
+	       messages queued that the port is full, all other incoming messages
-		dropped. There are situations where the size of the port should be
+	       are dropped. There are situations where the size of the port should
-		different from the default. This might be when your looper receives
+	       be different from the default. This might be when your looper
-		a lot of messages, or if the message handling thread runs at a lower
+	       receives a lot of messages, or if the message handling thread runs
-		priority than normal, which would decrease the processing speed.
+	       at a lower priority than normal, which would decrease the processing
-		Finding a suitable value for these custom scenarios would be done by
+	       speed. Finding a suitable value for these custom scenarios would be
-		testing. 
+	       done by testing. 
 
 	\see Run()
+
+	\since BeOS R3
 */
 
 
@@ -124,6 +132,8 @@
 	inside its own message handling thread, you should call Quit().
 
 	\see Quit()
+
+	\since BeOS R3
 */
 
 
@@ -139,7 +149,7 @@
 
 
 /*!
-	\fn BLooper::BLooper(BMessage *data)
+	\fn BLooper::BLooper(BMessage* data)
 	\brief Construct a looper from an archived message.
 
 	The \a data message has to be constructed by a BLooper::Archive() call.
@@ -148,26 +158,31 @@
 	the default archiver.
 
 	\warning This constructor does no type check whatsoever. Since you can pass
-		any BMessage, you should - if you are not sure about the exact type -
+	         any BMessage, you should - if you are not sure about the exact
-		use the Instantiate() method, which does check the type.
+	         type - use the Instantiate() method, which does check the type.
 
 	\see Instantiate()
 	\see Archive()
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BArchivable *BLooper::Instantiate(BMessage *data)
+	\fn BArchivable* BLooper::Instantiate(BMessage* data)
 	\brief Static method to instantiate a looper from an archived message.
 
 	\return A pointer to the instantiated looper, or \c NULL if the \a data
 	        is not a valid archived BLooper object.
+
 	\see BLooper(BMessage* data)
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BLooper::Archive(BMessage *data, bool deep) const
+	\fn status_t BLooper::Archive(BMessage* data, bool deep) const
 	\brief Archive a looper to a message
 
 	Currently, only the name and the port capacity are archived. Any other
@@ -175,9 +190,13 @@
 
 	\param data The message to archive the object in.
 	\param deep This parameter is ignored, as BLooper does not have children.
+
 	\retval B_OK Archiving succeeded.
 	\retval B_BAD_VALUE The \a data parameter is not a valid message.
-	\see BLooper::Instantiate(BMessage *data)
+
+	\see BLooper::Instantiate(BMessage* data)
+
+	\since BeOS R3
 */
 
 
@@ -202,6 +221,7 @@
 
 	\param command The \c what identifier of the message that needs to be sent.
 
+	\return A status code.
 	\retval B_OK The operation succeeded, and the message is sent to the port.
 	\retval B_ERROR There was a general operation error.
 	\retval B_BAD_VALUE This looper is not yet running and therefore cannot
@@ -213,11 +233,13 @@
 	     message to a specific handler, and request a reply.
 	\see PostMessage(BMessage *, BHandler *, BHandler *) for the same thing,
 		but with a complete message.
+
+	\since BeOS R5
 */
 
 
 /*!
-	\fn status_t BLooper::PostMessage(BMessage *message)
+	\fn status_t BLooper::PostMessage(BMessage* message)
 	\brief Post a \a message to this looper.
 
 	Posting a message puts it in the message queue. The message passes through
@@ -225,7 +247,6 @@
 
 	The \a message is copied, and as such, you should make sure you will not
 	leak it. The best way to send messages is like this:
-
 \code
 	BMessage message;
 	message.what = B_DO_SOMETHING;
@@ -236,6 +257,7 @@
 
 	\param message The message you would like to pass to this method.
 
+	\return A status code.
 	\retval B_OK The operation succeeded, and the message is sent to the port.
 	\retval B_ERROR There was a general operation error.
 	\retval B_BAD_VALUE This looper is not yet running and therefore cannot
@@ -247,12 +269,14 @@
 	     message to a specific handler, and request a reply.
 	\see PostMessage(BMessage *, BHandler *, BHandler *) for the same thing,
 	     but with a complete message.
+
+	\since BeOS R5
 */
 
 
 /*!
-	\fn status_t BLooper::PostMessage(uint32 command, BHandler *handler,
+	\fn status_t BLooper::PostMessage(uint32 command, BHandler* handler,
-		BHandler *replyTo)
+		BHandler* replyTo)
 	\brief Send a message with the \a command as \c what identifier to the
 	      \a handler associated with this looper, and (optionally) request a
 	      reply.
@@ -263,9 +287,10 @@
 	\param command The value you want as the message's \c what identifier.
 	\param handler The handler you would like to pass this message to.
 	\param replyTo If you would like to request a reply, pass the handler to
-		which this reply should be directed to. If you pass \c NULL, you will
+	       which this reply should be directed to. If you pass \c NULL, you
-		not receive a reply.
+	       will not receive a reply.
 
+	\return A status code.
 	\retval B_OK The operation succeeded, and the message is sent to the port.
 	\retval B_ERROR There was a general operation error.
 	\retval B_BAD_VALUE This looper is not yet running and therefore cannot
@@ -279,12 +304,14 @@
 	     members.
 	\see PostMessage(BMessage *, BHandler *, BHandler *) if you want to send a
 	     message to a specific handler, and request a reply.
+
+	\since BeOS R5
 */
 
 
 /*!
-	\fn status_t BLooper::PostMessage(BMessage *message, BHandler *handler,
+	\fn status_t BLooper::PostMessage(BMessage* message, BHandler* handler,
-		BHandler *replyTo)
+		BHandler* replyTo)
 	\brief Send a \a message to the \a handler associated with this looper, 
 	       and (optionally) request a reply.
 
@@ -293,7 +320,6 @@
 
 	The \a message is copied, and as such, you should make sure you will not
 	leak it. The best way to send messages is like this:
-
 \code
 	BMessage message;
 	message.what = B_DO_SOMETHING;
@@ -305,9 +331,10 @@
 	\param message The message you want to pass.
 	\param handler The handler you would like to pass this message to.
 	\param replyTo If you would like to request a reply, pass the handler to
-		which this reply should be directed to. If you pass \c NULL, you will
+	       which this reply should be directed to. If you pass \c NULL, you
-		not receive a reply.
+	       will not receive a reply.
 
+	\return A status code.
 	\retval B_OK The operation succeeded, and the message is sent to the port.
 	\retval B_ERROR There was a general operation error.
 	\retval B_BAD_VALUE This looper is not yet running and therefore cannot
@@ -321,6 +348,8 @@
 	     members.
 	\see PostMessage(uint32, BHandler *, BHandler *) if you want to send a
 	     message without data to a specific handler, and request a reply.
+
+	\since BeOS R5
 */
 
 
@@ -355,14 +384,18 @@
 
 	If you do override this method, please remember to call the
 	DispatchMessage() method of the parent class.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn void BLooper::MessageReceived(BMessage *msg)
+	\fn void BLooper::MessageReceived(BMessage* message)
 	\brief Process a message received by the internal handler of this looper.
 
 	Reimplemented from BHandler::MessageReceived();
+
+	\since BeOS R5
 */
 
 
@@ -371,16 +404,19 @@
 	\brief Retrieve the current message.
 
 	\attention Only call this method from within the thread that processes the
-		messages. It contains a pointer to the message that is currently being
+	           messages. It contains a pointer to the message that is currently
-		handled. Due to the multithreaded nature of the operating system, this
+	           being handled. Due to the multithreaded nature of the operating
-		method will not safely let you read the message that is being processed
+	           system, this method will not safely let you read the message
-		by this handler from outside the context of the processing. If you do
+	           that is being processed by this handler from outside the context
-		want to use a message outside of the processing thread, have a look at
+	           of the processing. If you do want to use a message outside of
-		DetachCurrentMessage() to safely retrieve a message.
+	           the processing thread, have a look at DetachCurrentMessage() to
+	           safely retrieve a message.
 
 	\return A pointer to the message that is currently being processed. Note
 	        that calling it from outside the thread that processes the message,
 	        could give you a \c NULL pointer or an invalid pointer.
+
+	\since BeOS R5
 */
 
 
@@ -393,9 +429,11 @@
 	You can then use it for different purposes.
 
 	\attention Only call this method from within the thread that processes the
-	messages. Due to the multithreaded nature of the operating system, calling
+	           messages. Due to the multithreaded nature of the operating
-	it from another thread is very likely to give you an invalid or a \c NULL
+	           system, calling it from another thread is very likely to give
-	pointer.
+	           you an invalid or a \c NULL pointer.
+
+	\since BeOS R5
 */
 
 
@@ -407,6 +445,8 @@
 	message that is being processed is already detached from this queue.
 
 	\return A pointer to the internal message queue.
+
+	\since BeOS R5
 */
 
 
@@ -414,8 +454,8 @@
 	\fn bool BLooper::IsMessageWaiting() const
 	\brief Check if there is a message waiting.
 
-	\retval true There are still messages to be processed.
+	\return \c true if there are still messages to be processed,
-	\retval false There is no message waiting.
+	        \c false if there is no message waiting.
 */
 
 
@@ -437,12 +477,14 @@
 	The \a handler will be associated to this looper. By default, the handler
 	in this looper will be chained to the supplied \a handler.
 
-	\param handler The handler to associate with this looper. If the handler is
+	\param handler The handler to associate with this looper. If the handler
-		already associated to another looper, the operation will fail silently.
+	       is already associated to another looper, the operation will fail
-		Check beforehand if you cannot be sure that the \a handler is
+	       silently. Check beforehand if you cannot be sure that the
-		unassociated.
+	       \a handler is unassociated.
 
 	\see RemoveHandler()
+
+	\since BeOS R3
 */
 
 
@@ -452,10 +494,13 @@
 
 	If the handler is disassociated, it can be reassociated to another looper.
 
-	\retval true The \a handler has been removed from this looper.
+	\return \c true if the \a handler has been removed from this looper,
-	\retval false The \a handler was invalid. or the handler was not
+	        \c false The \a handler was invalid or the handler was not
 	           associated to this looper.
+
 	\see AddHandler()
+
+	\since BeOS R3
 */
 
 
@@ -463,7 +508,10 @@
 	\fn int32 BLooper::CountHandlers() const
 	\brief Get the number of handlers associated with this looper.
 
-	\see HandlerAt(), IndexOf()
+	\see HandlerAt()
+	\see IndexOf()
+
+	\since BeOS R3
 */
 
 
@@ -474,7 +522,10 @@
 	\return A pointer to the handler at that \a index, or \c NULL if the
 	        \a index is out of range.
 
-	\see CountHandlers(), IndexOf()
+	\see CountHandlers()
+	\see IndexOf()
+
+	\since BeOS R3
 */
 
 
@@ -483,8 +534,10 @@
 	\brief Get the index of the \a handler that is in the associated handler
 	       list.
 
-	\return If the \a handler is not in the list, this method will return -1.
+	\return The index of the handler in the list if the \a handler is in the
-		Else, you will get the index of the handler in the list.
+	        list, else this method will return -1.
+
+	\since BeOS R3
 */
 
 
@@ -493,7 +546,10 @@
 	\brief Get the preferred handler.
 
 	\return A pointer to the preferred handler, or \c NULL if none is set.
+
 	\see SetPreferredHandler()
+
+	\since BeOS R3
 */
 
 
@@ -509,10 +565,14 @@
 	not ask to be directly passed on to a specific handler.
 
 	\param handler The preferred handler you want undesignated messages to be
-		handled by. If you want to unset the preferred handler, pass \c NULL.
+	       handled by. If you want to unset the preferred handler, pass
-		If the supplied \a handler is not associated with this looper, this
+	       \c NULL. If the supplied \a handler is not associated with this
-		call will fail silently and the current preferred handler will be unset.
+	       looper, this call will fail silently and the current preferred
+	       handler will be unset.
+
 	\see PreferredHandler()
+
+	\since BeOS R3
 */
 
 
@@ -538,6 +598,8 @@
 
 	\return A (positive) thread id if spawning the thread succeeded, or an
 	        error code.
+
+	\since BeOS R3
 */
 
 
@@ -557,6 +619,8 @@
 
 	\attention You will not have to delete the looper object, if a looper quits
 	           it will delete itself.
+
+	\since BeOS R3
 */
 
 
@@ -572,9 +636,11 @@
 	BLooper), which contains a modified document. The condition may be that a
 	modal dialog requesting a path of action is closed.
 
-	\retval true The looper can be quit and destroyed.
+	\return \c true if the looper can be quit and destroyed,
-	\retval false Do not accept the quit message and continue processing
+	        \c false if this method does not accept the quit message
-		messages.
+	           and continue processing messages.
+
+	\since BeOS R3
 */
 
 
@@ -591,11 +657,16 @@
 	a thread that actually holds the lock, will not cause a deadlock. See
 	BLocker for more information on locking internals.
 
-	\retval true The locking request succeeded.
+	\return \c true if the locking request succeeded,
-	\retval false The locking request could not be completed. There are a
+	        \c false if the locking request could not be completed. There are a
-		variety of reasons for this to happen, for example when the looper is
+	           variety of reasons for this to happen, for example when the
-		destroyed.
+	           looper is destroyed.
-	\see Unlock(), LockWithTimeout(), IsLocked()
+
+	\see Unlock()
+	\see LockWithTimeout()
+	\see IsLocked()
+
+	\since BeOS R5
 */
 
 
@@ -606,7 +677,11 @@
 	Use this method paired with Lock() calls, to release a lock. Make sure that
 	this method is only called on a locked looper.
 
-	\see Lock(), LockWithTimeout(), IsLocked()
+	\see Lock()
+	\see LockWithTimeout()
+	\see IsLocked()
+
+	\since BeOS R5
 */
 
 
@@ -614,9 +689,15 @@
 	\fn bool BLooper::IsLocked() const
 	\brief Check if a looper is locked.
 
-	\retval true The looper is locked.
+	\return \c true if the looper is locked,
-	\retval false The looper is not locked, or the looper has been deleted.
+	        \c false if the looper is not locked, or the looper has been
-	\see Lock(), Unlock(), LockWithTimeout()
+	           deleted.
+
+	\see Lock()
+	\see Unlock()
+	\see LockWithTimeout()
+
+	\since BeOS R5
 */
 
 
@@ -629,10 +710,16 @@
 
 	\param timeout The maximum time to wait for the lock request to succeed.
 
+	\return A status code.
 	\retval B_OK The lock is acquired.
 	\retval B_BAD_VALUE The looper has been destroyed.
 	\retval "other errors" There was an error acquiring the lock.
-	\see Lock(), Unlock(), IsLocked()
+
+	\see Lock()
+	\see Unlock()
+	\see IsLocked()
+
+	\since BeOS R5
 */
 
 
@@ -643,18 +730,24 @@
 	If the looper is not yet running, this method will return 0.
 
 	\see Run()
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn team_id BLooper::Team() const
 	\brief Return the team id in which this looper exists.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BLooper* BLooper::LooperForThread(thread_id thread)
 	\brief Static method to retrieve a BLooper for a specified \a thread.
+
+	\since BeOS R3
 */
 
 
@@ -662,10 +755,10 @@
 
 
 /*!
-	\name Loop debugging
+	\name Loop Debugging
 
 	These methods may aid you in debugging problems when they occur, but do not
-	use these in actual production code. These methods are unrealiable because
+	use these in actual production code. These methods are unreliable because
 	they are not thread-safe, and as such are only useful in specific debugging
 	situations. Handle with care.
 */
@@ -676,26 +769,34 @@
 
 /*!
 	\fn thread_id BLooper::LockingThread() const
-	\brief Return the thread id of the thread that currenty holds the lock.
+	\brief Return the thread id of the thread that currently holds the lock.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn int32 BLooper::CountLocks() const
 	\brief Return the number of recursive locks that are currently being held
-	on this looper
+	       on this looper.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn int32 BLooper::CountLockRequests() const
 	\brief Return the number of pending locks.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn sem_id BLooper::Sem() const
 	\brief Return the id of the semaphore that is used to lock this looper.
+
+	\since BeOS R3
 */
 
 
@@ -703,7 +804,7 @@
 
 
 /*!
-	\name Scripting Functions
+	\name Scripting
 */
 
 
@@ -711,11 +812,11 @@
 	
 
 /*!
-	\fn BHandler* BLooper::ResolveSpecifier(BMessage* msg, int32 index,
+	\fn BHandler* BLooper::ResolveSpecifier(BMessage* message, int32 index,
-		BMessage* specifier, int32 form, const char* property)
+		BMessage* specifier, int32 what, const char* property)
 	\brief Determine the proper handler for a scripting message.
 
-	\see BHandler::ResolveSpecifier()
+	\copydetails BHandler::ResolveSpecifier()
 */
 
 
@@ -724,9 +825,7 @@
 	\brief Reports the suites of messages and specifiers that derived classes
 		understand.
 
-	\param data The message to report the suite of messages and specifiers.
+	\copydetails BHandler::GetSupportedSuites()
-
-	\see BHandler::GetSupportedSuites()
 */
 
 
@@ -735,6 +834,7 @@
 
 /*!
 	\name Looper Message Filters
+
 	Note that filters added with these methods will be applied to all
 	associated handlers. Have a look at the filtering methods of the BHandler
 	class to see how filters can be applied to the inherited handler of this
@@ -756,7 +856,11 @@
 	The \a filter is not copied; rather a pointer is stored. Keep the \a filter
 	alive as long as it is used by a looper.
 
-	\see RemoveCommonFilter(), SetCommonFilterList(), CommonFilterList()
+	\see RemoveCommonFilter()
+	\see SetCommonFilterList()
+	\see CommonFilterList()
+
+	\since BeOS R3
 */
 
 
@@ -767,7 +871,11 @@
 	Note that this will not free the memory used by the \a filter, so you
 	should dispose of it yourself. 
 
-	\see AddCommonFilter(), SetCommonFilterList(), CommonFilterList()
+	\see AddCommonFilter()
+	\see SetCommonFilterList()
+	\see CommonFilterList()
+
+	\since BeOS R3
 */
 
 
@@ -783,7 +891,11 @@
 	Note that filters can only be applied to one looper or handler. If any
 	of the filters is already associated with another one, this call will fail.
 
-	\see AddCommonFilter(), RemoveCommonFilter(), CommonFilterList()
+	\see AddCommonFilter()
+	\see RemoveCommonFilter()
+	\see CommonFilterList()
+
+	\since BeOS R3
 */
 
 
@@ -792,18 +904,26 @@
 	\brief Return a list of filters applied to all incoming messages.
 
 	\return A pointer to the internal filter list, or \c NULL if such a list
-		has not yet been created. Please note that you should use the internal
+	        has not yet been created. Please note that you should use the
-		list management functions to manipulate the internal filter list, in
+	        internal list management functions to manipulate the internal
-		order to maintain internal consistency.
+	        filter list, in order to maintain internal consistency.
-	\see AddCommonFilter(), RemoveCommonFilter(), SetCommonFilterList()
+
+	\see AddCommonFilter()
+	\see RemoveCommonFilter()
+	\see SetCommonFilterList()
+
+	\since BeOS R3
 */
 
+
 //! @}
 
 
 /*!
 	\fn status_t BLooper::Perform(perform_code d, void* arg)
 	\brief Internal method.
+
+	\since Haiku R1
 */
 
 
@@ -821,5 +941,6 @@
 	the message. If you override this method, remember to call the base
 	implementation every now and then, in order to retrieve the messages
 	arriving at the default port.
-*/
 
+	\since Haiku R1
+*/

docs/user/app/MessageFilter.dox

@@ -1,13 +1,14 @@
 /*
- * Copyright 2007 Haiku, Inc. All rights reserved.
+ * Copyright 2007-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		Niels Sascha Reedijk, [email protected]
+ *		John Scipione, [email protected]
  *
  * Corresponds to:
- *		headers/os/app/MessageFilter.h
+ *		headers/os/app/MessageFilter.h	hrev47355
- *		src/kits/app/MessageFilter.cpp
+ *		src/kits/app/MessageFilter.cpp	hrev47355
  */
 
 
@@ -25,6 +26,8 @@
 
 	These return codes should be used in your own filter_hook function, or by
 	your overridden BMessageFilter::Filter() method.
+
+	\since BeOS R3
 */
 
 
@@ -32,6 +35,8 @@
 	\var B_SKIP_MESSAGE
 	\brief The message does not pass the filter criteria and should not be
 	       handled.
+
+	\since BeOS R3
 */
 
 
@@ -39,6 +44,8 @@
 	\var B_DISPATCH_MESSAGE
 	\brief The message passes the filter criteria and should be dispatched to
 	       a BHandler.
+
+	\since BeOS R3
 */
 
 
@@ -56,17 +63,19 @@
 	\param[in] message The message that needs to be verified.
 	\param[out] target If your filter hook is conscious about the available
 	            handlers, you can set a specific BHandler based on your filters
-		requirements. You do not have to change this field, because there will
+	            requirements. You do not have to change this field, because
-		always be a working default.
+	            there will always be a working default.
 	\param[in] filter A pointer to the filter from which this hook is called.
 
 	\return You should return #B_SKIP_MESSAGE in case the message does not
-		conform to the filter criteria, or #B_DISPATCH_MESSAGE if the message
+	        conform to the filter criteria, or #B_DISPATCH_MESSAGE if the
-		passes these criteria.
+	        message passes these criteria.
 
 	\see BMessageFilter(uint32, filter_hook)
-		BMessageFilter(message_delivery, message_source, filter_hook)
+	\see BMessageFilter(message_delivery, message_source, filter_hook)
-		BMessageFilter(message_delivery, message_source, uint32, filter_hook)
+	\see BMessageFilter(message_delivery, message_source, uint32, filter_hook)
+
+	\since BeOS R3
 */
 
 
@@ -81,18 +90,24 @@
 	With this filter you can, for example, specify that your handler only
 	handles deliveries that were programmed by you, and not any random drag and
 	drop actions initiated by the user.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\var B_ANY_DELIVERY
 	\brief Accept both delivery methods.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\var B_DROPPED_DELIVERY
 	\brief Only accept messages that were dropped by the user in the GUI.
+
+	\since BeOS R3
 */
 
 
@@ -100,6 +115,8 @@
 	\var B_PROGRAMMED_DELIVERY
 	\brief Only accept messages that were delivered using the
 	       BLooper::PostMessage() method.
+
+	\since BeOS R3
 */
 
 
@@ -116,14 +133,18 @@
 	You use these constants in the constructors of the BMessageFilter class.
 
 	\warning System messages, for example from the \c app_server, are
-		considered remote messages. Keep this in mind when you want to set up
+	         considered remote messages. Keep this in mind when you want
-		criteria for your window and application loopers.
+	         to set up criteria for your window and application loopers.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\var B_ANY_SOURCE
 	\brief Accept both local and remote messages.
+
+	\since BeOS R3
 */
 
 
@@ -131,12 +152,16 @@
 	\var B_REMOTE_SOURCE
 	\brief Only accept messages from a remote source, so from other
 	       applications.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\var B_LOCAL_SOURCE
 	\brief Only accept messages from your own local application.
+
+	\since BeOS R3
 */
 
 
@@ -159,7 +184,6 @@
 	-# Subclass the BMessageFilter class and override the Filter() function.
 	   This has the same capabilities as using a #filter_hook, but it allows
 	   cleaner code (in some cases).
-	
 	Both methods have their merits, but please remember that you have to choose
 	which one you want to use, since you can't use both. The order of
 	processing the criteria is in this order: the source, the delivery method,
@@ -212,6 +236,8 @@ looper->AddCommonFilter(filter);
 	The two classes that use BMessageFilter are BLooper and BHandler. In the
 	general messaging introduction, there is also a section on 
 	\ref app-messaging-receiving "handling messages".
+
+	\since BeOS R3
 */
 
 
@@ -225,6 +251,8 @@ looper->AddCommonFilter(filter);
 
 	\see BMessageFilter(message_delivery, message_source, filter_hook)
 	\see BMessageFilter(message_delivery, message_source, uint32 what, filter_hook)
+
+	\since BeOS R3
 */
 
 
@@ -239,6 +267,8 @@ looper->AddCommonFilter(filter);
 
 	\see BMessageFilter(uint32 what,filter_hook)
 	\see BMessageFilter(message_delivery, message_source, uint32 what, filter_hook)
+
+	\since BeOS R3
 */
 
 
@@ -253,30 +283,40 @@ looper->AddCommonFilter(filter);
 
 	\see BMessageFilter(uint32 what,filter_hook)
 	\see BMessageFilter(message_delivery, message_source, filter_hook)
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BMessageFilter::BMessageFilter(const BMessageFilter& filter)
 	\brief Copy constructor. Copy the criteria from another object.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BMessageFilter::BMessageFilter(const BMessageFilter* filter)
 	\brief Create a new object based on criteria of another object.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BMessageFilter::~BMessageFilter()
 	\brief Destructor. Does nothing.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BMessageFilter &BMessageFilter::operator=(const BMessageFilter& from)
+	\fn BMessageFilter& BMessageFilter::operator=(const BMessageFilter& from)
 	\brief Assignment operator. Copies criteria from another filter.
+
+	\since BeOS R3
 */
 
 
@@ -296,18 +336,24 @@ looper->AddCommonFilter(filter);
 
 	\return You should return \c B_DISPATCH_MESSAGE in case the message passes
 	        the tests, or \c B_SKIP_MESSAGE in case the message does not pass.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn message_delivery BMessageFilter::MessageDelivery() const
 	\brief Return the message_delivery criterium of this filter.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn message_source BMessageFilter::MessageSource() const
 	\brief Return the message_source criterium of this filter.
+
+	\since BeOS R3
 */
 
 
@@ -319,6 +365,8 @@ looper->AddCommonFilter(filter);
 	the message constant.
 
 	\see FiltersAnyCommand() const
+
+	\since BeOS R3
 */
 
 
@@ -327,10 +375,14 @@ looper->AddCommonFilter(filter);
 	\brief Return whether or not this filter has a message command criterium.
 
 	\see Command() const
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BLooper *BMessageFilter::Looper() const
+	\fn BLooper* BMessageFilter::Looper() const
 	\brief Return the looper this filter is associated with.
+
+	\since BeOS R3
 */

docs/user/app/MessageQueue.dox

@@ -1,15 +1,17 @@
 /*
- * Copyright 2007, Haiku, Inc. All rights reserved.
+ * Copyright 2007-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		Niels Sascha Reedijk, [email protected]
+ *		John Scipione, [email protected]
  *
  * Corresponds to:
- *		/trunk/headers/os/app/MessageQueue.h  rev 19956
+ *		/trunk/headers/os/app/MessageQueue.h	hrev47355
- *		/trunk/src/kits/app/MessageQueue.cpp  rev 19956
+ *		/trunk/src/kits/app/MessageQueue.cpp	hrev47355
  */
 
+
 /*!
 	\file MessageQueue.h
 	\ingroup app
@@ -37,12 +39,16 @@
 	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
 	complied with this requirement.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BMessageQueue::BMessageQueue()
 	\brief Constructs an empty message queue.
+
+	\since BeOS R3
 */
 
 
@@ -58,6 +64,8 @@
 	BLocker from the destructor once it is acquired. That way, any thread
 	waiting to do a AddMessage() will fail to acquire the lock since the
 	BLocker will be deleted before they can acquire it.
+
+	\since BeOS R3
 */
 
 
@@ -71,6 +79,8 @@
 
 	Because a BMessageQueue claims ownership of the \a message, it is important
 	that the message does not belong to another BMessageQueue.
+
+	\since BeOS R3
 */
 
 
@@ -80,23 +90,29 @@
 
 	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.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn int32 BMessageQueue::CountMessages() const
 	\brief Return the number of messages waiting in the queue.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn bool BMessageQueue::IsEmpty() const
 	\brief Check if there are messages waiting in the queue.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BMessage *BMessageQueue::FindMessage(int32 index) const
+	\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.
@@ -105,11 +121,13 @@
 	        bounds.
 	\see FindMessage(uint32, int32) for a variant that takes a specific \c what
 	     identifier.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BMessage *BMessageQueue::FindMessage(uint32 what, int32 index) const
+	\fn BMessage* BMessageQueue::FindMessage(uint32 what, int32 index) const
 	\brief Retrieve the message at the \a index of this queue, but only if it
 	       has a specific \a what constant.
 
@@ -119,6 +137,8 @@
 	\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.
+
+	\since BeOS R3
 */
 
 
@@ -127,6 +147,8 @@
 	\brief Lock the queue so no other thread can perform operations on it.
 
 	\see Unlock()
+
+	\since BeOS R3
 */
 
 
@@ -135,6 +157,8 @@
 	\brief Unlock the queue after a Lock() request.
 
 	\see Lock()
+
+	\since BeOS R3
 */
 
 
@@ -142,12 +166,15 @@
 	\fn bool BMessageQueue::IsLocked() const
 	\brief Check if the queue is locked.
 
-	\see Lock() and Unlock()
+	\see Lock()
+	\see Unlock()
+
+	\since Haiku R1
 */
 
 
 /*!
-	\fn BMessage *BMessageQueue::NextMessage()
+	\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
@@ -155,8 +182,11 @@
 
 	\return A pointer to a message, or \c NULL if the queue is empty, or the
 	        object has not been properly locked.
+
 	\see Lock()
 	\see IsNextMessage()
+
+	\since BeOS R3
 */
 
 
@@ -164,4 +194,6 @@
 	\fn bool BMessageQueue::IsNextMessage(const BMessage* message) const
 	\brief Check if the pointer to a \a message points at the next message on
 		the queue.
+
+	\since Haiku R1
 */