Merge work by John Scipione on the Haiku Book.

* Some new classes documented
 * Screenshots for the interface kit controls
 * A lot of typo fixes
 * Some css tweaks

This has some backporting to the current version of Doxygen, since 
there are experiments to get coloring similar to the one in the Be 
Book that will hopefully be upstreamed in Doxygen.


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

docs/user/Doxyfile

@@ -177,7 +177,8 @@ TAB_SIZE               = 4
 # will result in a user-defined paragraph with heading "Side Effects:". 
 # You can put \n's in the value part of an alias to insert newlines.
 
-ALIASES                = 
+# For keyboard shortcuts and anything related to pressing keys
+ALIASES                = "key{1}=<span class=\"keycap\">\1</span>"
 
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C 
 # sources only. Doxygen will then generate output that is more tailored for C. 
@@ -475,16 +476,21 @@ INPUT                  = . \
                          ../../headers/os/drivers/USB3.h \
                          ../../headers/os/drivers/USB_spec.h \
 						 ../../headers/os/interface/AbstractLayout.h \
+						 ../../headers/os/interface/Alert.h \
+						 ../../headers/os/interface/Button.h \
+						 ../../headers/os/interface/Bitmap.h \
 						 ../../headers/os/interface/Box.h \
 						 ../../headers/os/interface/GridLayout.h \
 						 ../../headers/os/interface/GroupLayout.h \
 						 ../../headers/os/interface/IconUtils.h \
+						 ../../headers/os/interface/InterfaceDefs.h \
 						 ../../headers/os/interface/Layout.h \
 						 ../../headers/os/interface/LayoutBuilder.h \
 						 ../../headers/os/interface/LayoutItem.h \
 						 ../../headers/os/interface/TwoDimensionalLayout.h \
                          ../../headers/os/locale \
                          ../../headers/os/midi2 \
+						 ../../headers/os/storage/AppFileInfo.h \
                          ../../headers/os/support \
                          ../../headers/posix/syslog.h
 
@@ -565,6 +571,7 @@ EXAMPLE_RECURSIVE      = NO
 # the \image command).
 
 IMAGE_PATH             = . \
+						 interface\
                          midi2
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should 

docs/user/app/Application.dox

@@ -0,0 +1,550 @@
+/*
+ * 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 42274
+ *		/trunk/src/kits/app/Application.cpp	 rev 42274
+ */
+
+
+/*!
+	\file Application.h
+	\brief Provides the BApplication class.
+*/
+
+
+/*!
+	\class BApplication
+	\ingroup app
+	\brief A container object for an application.
+
+	A BApplication establishes a connection between the application and the
+	Application Server.
+
+	The most common task performed by a BApplication object is to handle
+	messages sent to it. The BApplication object also is used
+	to get information about your application such as the number of windows
+	it has, its signature, executable location, and launch flags.
+
+	The BApplication object is automatically assigned to the global \c be_app
+	variable. The \c be_app variable allows you to refer to your BApplication
+	object from anywhere in the code.
+
+	To use a BApplication you first construct the object and then begin its
+	message loop by calling the Run() method. The Run() method
+	continues until the application is told to quit. Once Run() returns you
+	should then delete the BApplication object to free its memory usage.
+
+	Typically, you initialize the BApplication object in the programs main()
+	function. A typical main() function looks something like this:
+
+	\code
+#include Application.h
+
+main()
+{
+	/* Vendor is your vendor name, application is your application name */
+	BApplication app("application/x-vnd.vendor-application");
+	app->Run();
+	delete app;
+
+	return 0;
+}
+	\endcode
+*/
+
+
+/*!
+	\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
+	everything set up properly call Run() to start the application.
+
+	You should call InitCheck() to check for constructor initialization
+	errors.
+
+	\param signature The \a signature of the application.
+*/
+
+
+/*!
+	\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.
+
+	Any error that occurs while constructing the BApplication will be
+	set to the \a _error pointer. If \a _error points to a \c status_t
+	error then you should not call Run().
+
+	Alternately, you can call InitCheck() to check for constructor 
+	initialization errors.
+
+	\param signature The \a signature of the application.
+	\param _error A pointer to a \c status_t set by the BApplication
+		constructor.
+*/
+
+/*!
+	\fn status_t BApplication::InitCheck() const
+	\brief Returns the status of the constructor.
+
+	\returns If initialization succeeded returns \c B_OK, otherwise returns an
+		error status.
+*/
+
+
+/*!
+	\name Archiving
+*/
+
+
+//! @{
+
+
+/*!
+	\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.
+*/
+
+
+/*!
+	\fn status_t BApplication::Archive(BMessage *data, bool deep) const
+	\brief Archive the BApplication object into a BMessage.
+
+	\sa BArchivable::Archive()
+*/
+
+
+/*!
+	\fn BArchivable* BApplication::Instantiate(BMessage* data)
+	\brief Restores the BApplication object from a BMessage.
+
+	\sa BArchivable::Instantiate()
+*/
+
+
+//! @}
+
+
+/*!
+	\fn BApplication::~BApplication()
+	\brief Destructor Method
+*/
+
+
+/*!
+	\name Message Loop Control
+*/
+
+
+//! @{
+
+
+/*!
+	\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
+		a new thread.
+
+	\returns the thread_id of the thread that the BApplication is called from.
+*/
+
+
+/*!
+	\fn void BApplication::Quit()
+	\brief Tells the thread to finish processing the message queue, disallowing
+		any new messages.
+
+	Quit() doesn't kill the looper thread. After Quit() returns, it doesn't wait
+	for the message queue to empty. Run() will be then able to return. 
+
+	Quit() doesn't delete the BApplication object after Run() is called. You
+	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.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Hook Methods
+*/
+
+
+//! @{
+
+
+/*!
+	\fn bool BApplication::QuitRequested()
+	\brief Hook method that gets invoked when the BApplication receives a
+		\c B_QUIT_REQUESTED message.
+
+	BApplication sends a QuitRequested() message to each of its BWindow objects.
+	If all of the BWindow s return \c true then the windows are
+	each destroyed (through BWindow::Quit()) and QuitRequested() returns
+	\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.
+	\retval false The application failed to quit.
+*/
+
+
+/*!
+	\fn void BApplication::ReadyToRun()
+	\brief Hook method that's invoked when the BApplication receives a
+		\c B_READY_TO_RUN message.
+
+	The ReadyToRun() method is automatically called by the Run() method. It is
+	sent after the initial \c B_REFS_RECEIVED and \c B_ARGV_RECEIVED messages
+	(if any) have already been handled. ReadyToRun() is the only message that
+	every running application is guaranteed to receive.
+
+	The default version of ReadyToRun() is empty. You should override the
+	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.
+*/
+
+
+/*!
+	\fn void BApplication::ArgvReceived(int32 argc, char **argv)
+	\brief Hook method that gets invoked when the application receives a
+		\c B_ARGV_RECEIVED message.
+
+	If command line arguments are specified when the application is launched
+	from the the shell, or if \c argv/argc values are passed to
+	BRoster::Launch(), then this method is executed.
+
+	\warning ArgvReceived() is not called if no command line arguments are
+	specified, or if BRoster::Launch() was called without any \c argv/argc
+	values.
+
+	The arguments passed to ArgvReceived() are the constructed in the same way
+	as those passed to command line programs. The number of command line
+	arguments is passed in \a argc and the arguments themselves are passed as an
+	array of strings in \a argv. The first \a argv string is the name of the
+	program and the rest of the strings are the command line arguments.
+
+	BRoster::Launch() adds the program name to the front of the \a argv array
+	and increments the \a argc value.
+
+	The \c B_ARGV_RECEIVED message (if sent) is sent only once, just
+	before the \c B_READY_TO_RUN message is sent. However, if you try to
+	relaunch an application that is already running and the application is set
+	to \c B_EXCLUSIVE_LAUNCH or \c B_SINGLE_LAUNCH then the application will
+	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.
+*/
+
+
+/*!
+	\fn void BApplication::AppActivated(bool active)
+	\brief Hook method that gets invoked when the application receives
+	\c B_APP_ACTIVATED message.
+
+	The message is sent whenever the application changes its active application
+	status. The active flag set to is \c true when the application becomes
+	active and is set to \c false when the application becomes inactive.
+
+	The application becomes activated in response to a user action such as
+	clicking on or unhiding one of its windows. The application can have its
+	active status set programmatically by calling either the BWindow::Activate()
+	or BRoster::ActivateApp() methods.
+
+	This method is called after ReadyToRun() provided the application is
+	displaying a window that can be set active.
+*/
+
+
+/*!
+	\fn void BApplication::RefsReceived(BMessage *message)
+	\brief Hook method that gets invoked when the application receives a
+		\c B_REFS_RECEIVED message.
+
+	The message is sent in response to a user action such as a user
+	drag-and-dropping a file on your app's icon or opening a file that the
+	application is set to handle. You can use the IsLaunching() method to
+	discern whether the message arrived when the application is launched or
+	after the application has already been running.
+
+	The default implementation is empty. You can override this method to do
+	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
+		more entry_ref (\c B_REF_TYPE) items, one for each file sent.
+*/
+
+
+/*!
+	\fn void BApplication::AboutRequested()
+	\brief Hook method that gets invoked when the BApplication receives a
+	\c B_ABOUT_REQUESTED message.
+
+	You should override this method to pop an alert to provide information
+	about the application.
+
+	The default implementation pops a basic alert dialog.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Cursor
+*/
+
+
+//! @{
+
+
+/*!
+	\fn BApplication::ShowCursor()
+	\brief Restores the cursor.
+*/
+
+
+/*!
+	\fn void BApplication::HideCursor()
+	\brief Hides the cursor from the screen.
+*/
+
+
+/*!
+	\fn void BApplication::ObscureCursor()
+	\brief Hides the cursor until the mouse is moved.
+*/
+
+
+/*!
+	\fn bool BApplication::IsCursorHidden() const
+	\brief Returns whether or not the cursor is hidden.
+
+	\returns \c true if the cursor is hidden, \c false if not.
+*/
+
+
+/*!
+	\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
+	\c B_HAND_CURSOR or \c B_I_BEAM_CURSOR or you can create your own pass
+	in your own cursor image. The cursor data format is described in the BCursor
+	class.
+
+	\param cursor The cursor data to set the cursor to.
+*/
+
+
+/*!
+	\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.
+
+	The default BCursors to use are \c B_CURSOR_SYSTEM_DEFAULT for the hand
+	cursor and \c B_CURSOR_I_BEAM for the I-beam cursor.
+
+	\param cursor A BCursor object to set the \a cursor to.
+	\param sync synchronize the cursor immediately.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Info
+*/
+
+
+//! @{
+
+
+/*!
+	\fn int32 BApplication::CountWindows() const
+	\brief Returns the number of windows created by the application.
+
+	\returns the number of windows created by the application.
+*/
+
+
+/*!
+	\fn BWindow* BApplication::WindowAt(int32 index) const
+	\brief Returns the BWindow object at the specified index in the
+		application's window list.
+		
+	If index is out of range, this function returns \c NULL.
+
+	\warning Locking the BApplication object doesn't lock the window list.
+
+	\param index The \a index of the desired BWindow.
+
+	\returns The BWindow object at the specified \a index or \c NULL
+		if the \a index is out of range.
+*/
+
+
+/*!
+	\fn int32 BApplication::CountLoopers() const
+	\brief Returns the number of BLoopers created by the application.
+
+	\warning This method may return \c B_ERROR.
+
+	\returns The number of BLoopers in the application.
+*/
+
+
+/*!
+	\fn BLooper* BApplication::LooperAt(int32 index) const
+	\brief Returns the BLooper object at the specified index in the
+		application's looper list.
+
+	If index is out of range, this function returns \c NULL.
+
+	\returns The BLooper object at the specified \a index or \c NULL
+		if the \a index is out of range.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Status
+*/
+
+
+//! @{
+
+
+/*!
+	\fn bool BApplication::IsLaunching() const
+	\brief Returns whether or not the application is in the process of
+		launching.
+
+	\returns \c true if the application is launching, \c false if the
+		application is already running.
+*/
+
+
+/*!
+	\fn status_t BApplication::GetAppInfo(app_info *info) const
+	\brief Fills out the \a info parameter with information about the
+		application.
+
+	This is equivalent to
+	be_roster->GetRunningAppInfo(be_app->Team(), info);
+
+	\returns \c B_NO_INIT on an error or \c B_OK if all goes well.
+
+	\sa BRoster::GetAppInfo()
+*/
+
+
+/*!
+	\fn BResources* BApplication::AppResources()
+	\brief Returns a BResources object for the application.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Message Mechanics
+*/
+
+
+//! @{
+
+
+/*!
+	\fn void BApplication::MessageReceived(BMessage *message)
+	\sa BHandler::MessageReceived()
+*/
+
+
+/*!
+	\fn void BApplication::DispatchMessage(BMessage *message,
+		BHandler *handler)
+	\sa BLooper::DispatchMessage()
+*/
+
+
+//! @}
+
+
+/*!
+	\name Pulse
+*/
+
+
+//! @{
+
+
+/*!
+	\fn void BApplication::Pulse()
+	\brief Hook method that gets invoked when the BApplication receives a
+		\c B_PULSE message.
+
+	An action is performed each time app_server calls the Pulse() method. 
+	The pulse rate is set by SetPulseRate(). You can implement Pulse() to do
+	anything you want. The default version does nothing. The pulse granularity
+	is no better than once per 100,000 microseconds.
+
+	\sa SetPulseRate()
+*/
+
+
+/*!
+	\fn void BApplication::SetPulseRate(bigtime_t rate)
+	\brief Sets the interval that the \c B_PULSE messages are sent.
+
+	If the \a rate is set to 0 then the \c B_PULSE messages are not sent.
+	The pulse rate can be no faster than once per 100,000 microseconds or so.
+
+	\param rate The rate \a B_PULSE messages are sent to the application.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Scripting
+*/
+
+
+//! @{
+
+
+/*!
+	\fn BHandler* BApplication::ResolveSpecifier(BMessage *message, int32 index,
+		BMessage *specifier, int32 what, const char *property)
+	\sa BHandler::ResolveSpecifier()
+*/
+
+
+/*!
+	\fn status_t BApplication::GetSupportedSuites(BMessage *data)
+	\sa BHandler::GetSupportedSuites()
+*/
+
+
+//! @}

docs/user/app/Handler.dox

@@ -444,13 +444,14 @@ ShowImageApp::MessageReceived(BMessage *message)
 /*!
 	\fn BHandler * BHandler::ResolveSpecifier(BMessage *msg, int32 index,
 		BMessage *specifier, int32 form, const char *property)
-	\brief Undocumented.
+	\brief Determine the proper handler for a scripting message.
 */
 
 
 /*!
 	\fn status_t BHandler::GetSupportedSuites(BMessage *data)
-	\brief Undocumented.
+	\brief Reports the suites of messages and specifiers that derived classes
+		understand.
 */
 
 

docs/user/app/Looper.dox

@@ -147,7 +147,7 @@
 	\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.
-	
+
 	\see Instantiate()
 	\see Archive()
 */
@@ -710,13 +710,20 @@
 /*!
 	\fn BHandler* BLooper::ResolveSpecifier(BMessage* msg, int32 index,
 		BMessage* specifier, int32 form, const char* property)
-	\brief Undocumented.
+	\brief Determine the proper handler for a scripting message.
+
+	\see BHandler::ResolveSpecifier()
 */
 
 
 /*!
 	\fn status_t BLooper::GetSupportedSuites(BMessage* data)
-	\brief Undocumented.
+	\brief Reports the suites of messages and specifiers that derived classes
+		understand.
+
+	\param data The message to report the suite of messages and specifiers.
+
+	\see BHandler::GetSupportedSuites()
 */
 
 
@@ -799,7 +806,7 @@
 
 /*!
 	\fn BMessage* BLooper::MessageFromPort(bigtime_t timeout)
-	\brief Hook function to retrieve a message from the looper's port.
+	\brief Hook method to retrieve a message from the looper's port.
 	
 	The default implementation is called by the internal message looping thread
 	and retrieves the next message from the port that belongs to this looper.
@@ -813,5 +820,3 @@
 	arriving at the default port.
 */
 
-
-	

docs/user/book.css

@@ -186,6 +186,24 @@ div.contents {
 	background: #ffeae6 url(images/alert_stop_32.png) 15px 15px no-repeat;
 }
 
+
+/* For keyboard shortcuts and the like (also from userguide) */
+
+div.contents span.keycap {
+	-webkit-border-radius: 3px;
+	-khtml-border-radius: 3px;	
+	-moz-border-radius: 3px;
+	border-radius: 3px;
+	border-color: #c7c7c7;
+	border-style: solid;
+	border-width: 1px;
+	padding: 0px 2px 0px 2px;
+	background-color: #e8e8e8;
+	font-family: serif;
+	font-variant: small-caps;
+}
+
+
 /* Continue with the rest of the standard Doxygen stuff... */
 
 CAPTION { font-weight: bold }

docs/user/book.dox

@@ -7,8 +7,10 @@
   - \ref drivers
   - \ref interface | \link interface_intro \em Introduction \endlink
   - \ref locale | \link locale_intro \em Introduction \endlink
+  - \ref media | \link media_intro \em Introduction \endlink
   - \ref midi1
   - \ref midi2 | \link midi2_intro \em Introduction \endlink
+  - \ref storage | \link storage_intro \em Introduction \endlink
   - \ref support | \link support_intro \em Introduction \endlink
 
   \section notes General Notes and Information

docs/user/drivers/fs_interface.dox

@@ -24,49 +24,6 @@
 // TODO: These have been superseded by the B_STAT_* flags in <NodeMonitor.h>.
 // Move the documentation there!
 
-/*!
-	\enum write_stat_mask
-	\brief This mask is used in file_system_module_info::write_stat() to
-		determine which values need to be written.
-*/
-
-/*!
-	\var write_stat_mask::FS_WRITE_STAT_MODE
-	\brief The mode parameter should be updated.
-*/
-
-/*!
-	\var write_stat_mask::FS_WRITE_STAT_UID
-	\brief The UID field should be updated.
-*/
-
-/*!
-	\var write_stat_mask::FS_WRITE_STAT_GID
-	\brief The GID field should be updated.
-*/
-
-/*!
-	\var write_stat_mask::FS_WRITE_STAT_SIZE
-	\brief The size field should be updated. If the actual size is less than the
-		new provided file size, the file should be set to the new size and the
-		extra space should be filled with zeros.
-*/
-
-/*!
-	\var write_stat_mask::FS_WRITE_STAT_ATIME
-	\brief The access time should be updated.
-*/
-
-/*!
-	\var write_stat_mask::FS_WRITE_STAT_MTIME
-	\brief The 'last modified' field should be updated.
-*/
-
-/*!
-	\var write_stat_mask::FS_WRITE_STAT_CRTIME
-	\brief The 'creation time' should be updated.
-*/
-
 /*!
 	\def B_STAT_SIZE_INSECURE
 	\brief Flag for the fs_vnode_ops::write_stat hook indicating that the FS
@@ -249,46 +206,6 @@
 
 //! @{
 
-/*!
-	\fn bool (*file_system_module_info::supports_defragmenting)(partition_data
-		*partition, bool *whileMounted)
-	\brief Undocumented. TODO.
-*/
-
-/*!
-	\fn bool (*file_system_module_info::supports_repairing)(partition_data *partition,
-			bool checkOnly, bool *whileMounted)
-	\brief Undocumented. TODO.
-*/
-
-/*!
-	\fn bool (*file_system_module_info::supports_resizing)(partition_data *partition,
-			bool *whileMounted)
-	\brief Undocumented. TODO.
-*/
-
-/*!
-	\fn bool (*file_system_module_info::supports_moving)(partition_data *partition, bool *isNoOp)
-	\brief Undocumented. TODO.
-*/
-
-/*!
-	\fn bool (*file_system_module_info::supports_setting_content_name)(partition_data *partition,
-			bool *whileMounted)
-	\brief Undocumented. TODO.
-*/
-
-/*!
-	\fn bool (*file_system_module_info::supports_setting_content_parameters)(partition_data *partition,
-			bool *whileMounted)
-	\brief Undocumented. TODO.
-*/
-
-/*!
-	\fn bool (*file_system_module_info::supports_initializing)(partition_data *partition)
-	\brief Undocumented. TODO.
-*/
-
 /*!
 	\fn bool (*file_system_module_info::validate_resize)(partition_data *partition, off_t *size)
 	\brief Undocumented. TODO.
@@ -638,11 +555,11 @@
 	\param volume The volume object.
 	\param query The string that represents a query.
 	\param flags Any combination of none or more of these flags:
-		- \c #B_LIVE_QUERY The query is live. When a query is live, it is
+		- \c B_LIVE_QUERY The query is live. When a query is live, it is
 		  constantly updated using the \a port. The FS must invoke the functions
 		  notify_query_entry_created() and notify_query_entry_removed() whenever
 		  an entry starts respectively stops to match the query predicate.
-		- \c #B_QUERY_NON_INDEXED Normally at least one of the attributes used
+		- \c B_QUERY_NON_INDEXED Normally at least one of the attributes used
 		  in the query string should be indexed. If none is, this hook is
 		  allowed to fail, unless this flag is specified. Usually an
 		  implementation will simply add a wildcard match for any complete
@@ -1714,7 +1631,7 @@
 	\param vnode The node object.
 	\param cookie The cookie you associated with this attribute.
 	\param stat A pointer to the new stats you should write.
-	\param statMask One or more of the values of #write_stat_mask that tell you
+	\param statMask One or more of the values of write_stat_mask that tell you
 		which fields of \a stat are to be updated.
 	\return \c B_OK if everything went fine, another error code otherwise.
 */

docs/user/interface/Alert.dox

@@ -0,0 +1,389 @@
+/*
+ * Copyright 2011, Haiku inc.
+ * Distributed under the terms of the MIT Licence.
+ *
+ * Documentation by:
+ *  John Scipione <[email protected]>
+ * Corresponds to:
+ *  /trunk/headers/os/interface/Alert.h	 rev 42274
+ *  /trunk/src/kits/interface/Alert.cpp	 rev 42274
+ */
+
+
+/*!
+	\file Alert.h
+	\brief BAlert class definition and support enums.
+*/
+
+
+/*!
+	\enum alert_type
+	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.
+*/
+
+/*!
+	\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
+	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.
+*/
+
+/*!
+	\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
+	leftmost "Cancel" or "Delete" button.
+*/
+
+
+/*!
+	\class BAlert
+	\ingroup interface
+	\brief The BAlert class defines a modal alert dialog which displays a short
+		message and provides a set of labeled buttons that allow the user to
+		respond.
+
+	The alert can be configured with a set of one to three buttons. These
+	buttons are assigned indexes 0, 1, and 2 from right-to-left respectively
+	and are automatically positioned by the system. The user can either click
+	on one of the buttons or use a shortcut key to select a button.
+
+	The layout of the buttons can be configured by setting the #button_width
+	and #button_spacing properties in the BAlert constructor. The icon displayed
+	in the alert can also be configured by setting the #alert_type property. The
+	right-most button (index 0) is the default button which can be activated
+	by pushing the \key{Enter} key.
+
+	Below is an example of an unsaved changes alert dialog:
+
+	\image html BAlert_example.png
+
+	When the user responds by selecting one of the buttons the alert window is
+	removed from the screen. The index of the selected button is returned to
+	the calling application and the BAlert object is deleted.
+
+	The code used to create and display an alert dialog like the one shown
+	above is shown below:
+
+	\code
+BAlert* alert = new BAlert("Close and save dialog", "Save changes to...",
+	"Cancel", "Don't save", "Save", B_WIDTH_AS_USUAL, B_OFFSET_SPACING,
+	B_WARNING_ALERT);
+alert->SetShortcut(0, B_ESCAPE);
+int32 button_index = alert->Go();
+	\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
+	the left relative to the other buttons by setting the \c B_OFFSET_SPACING
+	flag.  The \c B_WARNING_ALERT flag displays the exclamation mark icon in
+	the dialog.
+
+	Any alert with a Cancel button should map the \key{Escape} key as shown in
+	the example above. You can setup additional shortcut keys for the buttons
+	with the SetShortcut() method.
+
+	The Go() method does the work of loading up and removing the alert
+	window and returns the index of the button that the user selected.
+*/
+
+
+/*!
+	\fn BAlert::BAlert(const char *title, const char *text,
+		const char *button1, const char *button2, const char *button3,
+		button_width width, alert_type type)
+	\brief Creates and initializes a BAlert dialog.
+
+	\param title The title of the window. Since the alert window doesn't have
+		   a title tab, the title is not actually displayed anywhere but is
+		   useful for debugging purposes.
+	\param text The text that is displayed at the top of the window.
+	\param button1 Button 1 label
+	\param button2 Button 2 label
+	\param button3 Button 3 label
+	\param width A constant that describes how the button should be sized.
+		Options are
+		\li \c B_WIDTH_AS_USUAL
+		\li \c B_WIDTH_FROM_WIDEST
+		\li \c B_WIDTH_FROM_LABEL
+
+		See button_width for details.
+	\param type Constant that determines which alert icon is displayed.
+		Options are
+		\li \c B_EMPTY_ALERT
+		\li \c B_INFO_ALERT
+		\li \c B_IDEA_ALERT
+		\li \c B_WARNING_ALERT
+		\li \c B_STOP_ALERT
+
+		See alert_type for details.
+*/
+
+/*!
+	\fn BAlert::BAlert(const char *title, const char *text, const char *button1,
+		const char *button2, const char *button3, button_width width,
+		button_spacing spacing, alert_type type)
+	\brief Creates and initializes a BAlert dialog.
+
+	You can also set the \a spacing with this constructor.
+
+	\param title The title of the window. Since the alert window doesn't have
+		   a title tab, the title is not actually displayed anywhere but is
+		   useful for debugging purposes.
+	\param text The text that is displayed at the top of the window.
+	\param button1 Button 1 label
+	\param button2 Button 2 label
+	\param button3 Button 3 label
+	\param width A constant that describes how the button should be sized.
+		Options are
+		\li \c B_WIDTH_AS_USUAL
+		\li \c B_WIDTH_FROM_WIDEST
+		\li \c B_WIDTH_FROM_LABEL
+
+		See button_width for details.
+	\param spacing Determines how the buttons are spaced. Options are
+		\li \c B_EVEN_SPACING
+		\li \c B_OFFSET_SPACING 
+
+		See button_spacing for details.
+	\param type Constant that determines which alert icon is displayed.
+		Options are
+		\li \c B_EMPTY_ALERT
+		\li \c B_INFO_ALERT
+		\li \c B_IDEA_ALERT
+		\li \c B_WARNING_ALERT
+		\li \c B_STOP_ALERT
+
+		See alert_type for details.
+*/
+
+/*!
+	\fn BAlert::BAlert(BMessage* data)
+	\brief Unarchives an alert from a BMessage.
+
+	\param data The archive.
+*/
+
+/*!
+	\fn BAlert::~BAlert()
+	\brief Destructor method.
+
+	Standard Destructor method to delete a BAlert.
+*/
+
+/*!
+	\fn BArchivable* BAlert::Instantiate(BMessage* data)
+	\brief Instantiates a BAlert from a BMessage.
+	\param data The message to instantiate the BAlert.
+	\returns a BArchivable object of the BAlert.
+*/
+
+/*!
+	\fn status_t BAlert::Archive(BMessage* data, bool deep) const
+	\brief Archives the BAlert into \a archive.
+
+	\param data The target archive which the BAlert \a data will go into.
+	\param deep Whether or not to recursively archive the BAlert's children.
+	\retval B_OK The archive operation was successful.
+	\retval B_BAD_VALUE The archive operation failed.
+*/
+
+/*!
+	\fn void BAlert::SetShortcut(int32 index, char key)
+	\brief Sets the shortcut character which is mapped to a button at the
+	specified \a index.
+
+	A button can only have one shortcut except for the rightmost button which,
+	in addition to the shortcut you set, is always mapped to \c B_ENTER.
+
+	If you create a "Cancel" button then you should set its shortcut to
+	\c B_ESCAPE.
+
+	\param index The \a index of the button to set the shortcut to.
+	\param key The shortcut character to set.
+*/
+
+/*!
+	\fn char BAlert::Shortcut(int32 index) const
+	\brief Gets the shortcut character which is mapped to a button at the 
+	specified \a index.
+
+	\param index The \a index of the button to get the shortcut of.
+
+	\return The shortcut character mapped to the button at the specified
+		\a index.
+*/
+
+/*!
+	\fn int32 BAlert::Go()
+	\brief Displays the alert window.
+
+	This version of Go() that does not include an invoker is
+	synchronous. Go() returns once the user has clicked a button and
+	the panel has been removed from the screen. The BAlert object is
+	deleted before the method returns.
+
+	If the BAlert is sent a \c B_QUIT_REQUESTED message while the alert
+	window is still on screen then Go() returns -1.
+
+	\returns The index of the button clicked.
+*/
+
+/*!
+	\fn status_t BAlert::Go(BInvoker* invoker)
+	\brief Displays the alert window from a specified \a invoker.
+
+	This version of Go() with an \a invoker is asynchronous. It returns
+	immediately with \c B_OK and the button \a index is set to the field
+	of the BMessage that is sent to the target of the \a invoker.
+
+	Go() deletes the BAlert object after the message is sent.
+
+	If you call Go() with a \c NULL invoker argument than the BMessage
+	is not sent.
+
+	If the BAlert is sent a \c B_QUIT_REQUESTED method while the alert
+	window is still on screen then the message is not sent.
+
+	\returns A status code.
+*/
+
+/*!
+	\fn void BAlert::MessageReceived(BMessage* msg)
+	\brief Initiates an action from a received message.
+
+	\param msg The message
+
+	\see BWindow::MessagedReceived()
+*/
+
+/*!
+	\fn void BAlert::FrameResized(float newWidth, float newHeight)
+	\brief Resizes the alert dialog.
+
+	\param newWidth The new alert dialog width.
+	\param newHeight The new alert dialog height.
+
+	\see BWindow::FrameResized()
+*/
+
+/*!
+	\fn BButton* BAlert::ButtonAt(int32 index) const
+	\brief Returns a pointer to the BButton at the specified \a index.
+
+	The \a index of the buttons begins at \c 0 and counts from left to right.
+	If a BButton does not exist for the specified \a index then \c NULL is
+	returned.
+
+	\param index The \a index of the desired button.
+
+	\return A pointer to the BButton at the specified \a index.
+*/
+
+/*!
+	\fn BTextView* BAlert::TextView() const
+	\brief Returns a TextView containing the text of the Alert.
+*/
+
+/*!
+	\fn BHandler* BAlert::ResolveSpecifier(BMessage* msg, int32 index,
+		BMessage* specifier, int32 form, const char* property)
+	\brief Resolves specifiers for properties.
+	\see BHandler::ResolveSpecifier()
+*/
+
+/*!
+	\fn status_t BAlert::GetSupportedSuites(BMessage* data)
+	\brief Reports the suites of messages and specifiers that derived classes
+		understand.
+	
+	\param data The message to report the suite of messages and specifiers.
+
+	\see BWindow::GetSupportedSuites()
+*/
+
+/*!
+	\fn void BAlert::DispatchMessage(BMessage* msg, BHandler* handler)
+	\brief Sends out a message.
+
+	\see BWindow::DispatchMessage()
+*/
+
+/*!
+	\fn void BAlert::Quit()
+	\brief Quits the window closing it.
+
+	\see BWindow::Quit()
+*/
+
+/*!
+	\fn bool BAlert::QuitRequested()
+	\brief Hook method that gets called with the window is closed.
+
+	\returns \c true if the window closes.
+
+	\see BWindow::QuitRequested()
+*/
+
+/*!
+	\fn BPoint BAlert::AlertPosition(float width, float height)
+	\brief Resizes the Alert window to the width and height specified and
+	return the Point of the top-left corner of the Alert window.
+
+	\param width The desired \a width of the alert window.
+	\param height The desired \a height of the alert window.
+
+	\returns The BPoint of the top-left corner of the Alert window.
+*/
+
+/*!
+	\fn status_t BAlert::Perform(perform_code code, void* _data)
+	\brief Performs an action give a perform_code and data
+
+	Currently the only perform code available is \c PERFORM_CODE_SET_LAYOUT.
+
+	\param code The perform code
+	\param _data A pointer to some data to perform on
+
+	\return A status code.
+
+	\see BWindow::Perform().
+*/

docs/user/interface/Bitmap.dox

@@ -0,0 +1,556 @@
+/*
+ * Copyright 2011, Haiku inc.
+ * Distributed under the terms of the MIT Licence.
+ *
+ * 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
+	\brief Defines the BBitmap class and global operators and functions for
+		handling bitmaps.
+*/
+
+
+/*!
+	\class BBitmap
+	\ingroup interface
+	\ingroup libbe
+	\brief Access and manipulate digital images commonly known as bitmaps.
+
+	A BBitmap is a rectangular map of pixel data. The BBitmap class allows you
+	to create a bitmap by specifying its pixel data and has operations for
+	altering and accessing the properties of bitmaps.
+
+	To create a BBitmap object use one of the constructor methods below. You
+	can determine if initialization was successful by calling the InitCheck()
+	method. You can determine if a BBitmap object is valid at any time by
+	calling the IsValid() method.
+
+	An example of creating a new 32x32 pixel BBitmap object and assigning the
+	icon of the current application looks like this:
+	\code
+BBitmap iconBitmap = new BBitmap(BRect(0, 0, 31, 31), B_RGBA32));
+appFileInfo.GetIcon(iconBitmap, B_LARGE_ICON);
+	\endcode
+
+	You can access the properties of a bitmap by calling the Bounds(),
+	Flags(), ColorSpace(), Area(), Bits(), BitsLength(), BytesPerRow(),
+	and GetOverlayRestrictions() methods.
+
+	To directly set the pixel data of a bitmap call the Bits() or SetBits()
+	methods or you can use the ImportBits() method to copy the bits from an
+	existing bitmap.
+
+	You can also draw into a bitmap by attaching a child BView to the bitmap.
+	To add and remove child BView&apos;s to a bitmap call the AddChild() and
+	RemoveChild() methods respectively. You can access the child views of a
+	bitmap by calling the CountChildren(), ChildAt(), and FindView() methods.
+
+	For off-screen bitmaps it is important to lock the bitmap before drawing
+	the pixels and then unlock the bitmap when you are done to prevent
+	flickering. To lock and unlock a bitmap call the LockBits() and UnLockBits()
+	methods respectively. To lock and unlock the off-screen window that a
+	bitmap resides in you should call the Lock() and UnLock() methods. To
+	determine is a bitmap is currently locked you can call the IsLocked()
+	method.
+*/
+
+
+/*!
+	\fn BBitmap::BBitmap(BRect bounds, uint32 flags, color_space colorSpace,
+		int32 bytesPerRow, screen_id screenID)
+	\brief Creates and initializes a BBitmap object.
+
+	\param bounds The bitmap dimensions.
+	\param flags Creation flags.
+	\param colorSpace The bitmap's color space.
+	\param bytesPerRow The number of bytes per row the bitmap should use.
+		   \c B_ANY_BYTES_PER_ROW to let the constructor choose an appropriate
+		   value.
+	\param screenID ???
+*/
+
+
+/*!
+	\fn BBitmap::BBitmap(BRect bounds, color_space colorSpace,
+		bool acceptsViews, bool needsContiguous)
+	\brief Creates and initializes a BBitmap object.
+
+	\param bounds The bitmap dimensions.
+	\param colorSpace The bitmap's color space.
+	\param acceptsViews \c true, if the bitmap shall accept BViews, i.e. if
+		   it shall be possible to attach BView to the bitmap and draw into
+		   it.
+	\param needsContiguous If \c true a physically contiguous chunk of memory
+		   will be allocated.
+*/
+
+
+/*!
+	\fn BBitmap::BBitmap(const BBitmap* source, bool acceptsViews,
+		bool needsContiguous)
+	\brief Creates a BBitmap object as a clone of another bitmap.
+
+	\param source The source bitmap.
+	\param acceptsViews \c true, if the bitmap shall accept BViews, i.e. if
+		   it shall be possible to attach BView to the bitmap and draw into
+		   it.
+	\param needsContiguous If \c true a physically contiguous chunk of memory
+		   will be allocated.
+*/
+
+
+/*!
+	\fn BBitmap::BBitmap(const BBitmap& source, uint32 flags)
+	\brief Creates a BBitmap object as a clone of another bitmap.
+
+	\param source The source bitmap.
+	\param flags Creation flags.
+*/
+
+
+/*!
+	\fn BBitmap::BBitmap(const BBitmap& source)
+	\brief Creates a BBitmap object as a clone of another bitmap.
+
+	\param source The source bitmap.
+*/
+
+
+/*!
+	\fn BBitmap::~BBitmap()
+	\brief Destructor Method
+
+	Frees all resources associated with this object.
+*/
+
+
+/*!
+	\name Archiving
+*/
+
+
+//! @{
+
+
+/*!
+	\fn BBitmap::BBitmap(BMessage* data)
+	\brief Unarchives a bitmap from a BMessage.
+
+	\param data The archive.
+*/
+
+
+/*!
+	\fn BArchivable* BBitmap::Instantiate(BMessage* data)
+	\brief Instantiates a BBitmap from an archive.
+
+	\param data The archive.
+	\return A bitmap reconstructed from the archive or \c NULL, if an error
+		occurred.
+*/
+
+
+/*!
+	\fn status_t BBitmap::Archive(BMessage* data, bool deep) const
+	\brief Archives the BBitmap object.
+
+	\param data The archive.
+	\param deep if \c true, child object will be archived as well.
+	\return \c B_OK, if everything went fine, an error code otherwise.
+*/
+
+
+//! @}
+
+
+/*!
+	\fn status_t BBitmap::InitCheck() const
+	\brief Gets the status of the constructor.
+
+	\returns B_OK if initialization succeeded, otherwise returns an
+		error status.
+*/
+
+
+/*!
+	\fn bool BBitmap::IsValid() const
+	\brief Determines whether or not the BBitmap object is valid.
+
+	\return \c true, if the object is properly initialized, \c false otherwise.
+*/
+
+
+/*!
+	\name Locking
+*/
+
+
+//! @{
+
+
+/*!
+	\fn status_t BBitmap::LockBits(uint32* state)
+	\brief Locks the bitmap bits so that they cannot be relocated.
+
+	This is currently only used for overlay bitmaps; whenever you
+	need to access their Bits() you must lock them first.
+	On resolution change overlay bitmaps can be relocated in memory;
+	using this call prevents you from accessing an invalid pointer
+	and clobbering memory that doesn't belong you.
+
+	\param state Unused
+	\returns \c B_OK on success or an error status code.
+*/
+
+
+/*!
+	\fn void BBitmap::UnlockBits()
+	\brief Unlocks the bitmap's buffer.
+
+	Counterpart to BBitmap::LockBits().
+*/
+
+
+/*!
+	\fn bool BBitmap::Lock()
+	\brief Locks the off-screen window that belongs to the bitmap.
+
+	The bitmap must accept views, if locking should work.
+
+	\returns \c true, if the lock was acquired successfully.
+*/
+
+
+/*!
+	\fn void BBitmap::Unlock()
+	\brief Unlocks the off-screen window that belongs to the bitmap.
+
+	The bitmap must accept views, if locking should work.
+*/
+
+
+/*!
+	\fn bool BBitmap::IsLocked() const
+	\brief Determines whether or not the bitmap's off-screen window is locked.
+
+	The bitmap must accept views, if locking should work.
+
+	\return \c true, if the caller owns a lock , \c false otherwise.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Accessors
+*/
+
+
+//! @{
+
+
+/*!
+	\fn area_id BBitmap::Area() const
+	\brief Gets the ID of the area the bitmap data reside in.
+
+	\return The ID of the area the bitmap data reside in.
+*/
+
+
+/*!
+	\fn void* BBitmap::Bits() const
+	\brief Gets the pointer to the bitmap data.
+
+	\return The pointer to the bitmap data.
+*/
+
+
+/*!
+	\fn int32 BBitmap::BitsLength() const
+	\brief Gets the length of the bitmap data.
+
+	\return The length of the bitmap data as an int32.
+*/
+
+
+/*!
+	\fn int32 BBitmap::BytesPerRow() const
+	\brief Gets the number of bytes used to store a row of bitmap data.
+
+	\return The number of bytes used to store a row of bitmap data.
+*/
+
+
+/*!
+	\fn color_space BBitmap::ColorSpace() const
+	\brief Gets the bitmap's color space.
+
+	\return The bitmap's color space.
+*/
+
+
+/*!
+	\fn BRect BBitmap::Bounds() const
+	\brief Gets a BRect the size of the bitmap's dimensions.
+
+	\return A BRect the size of the bitmap's dimensions.
+*/
+
+
+/*!
+	\fn uint32 BBitmap::Flags() const
+	\brief Accesses the bitmap's creation flags.
+
+	This method informs about which flags have been used to create the
+	bitmap. It would for example tell you wether this is an overlay
+	bitmap. If bitmap creation succeeded, all flags are fulfilled.
+
+	\return The bitmap's creation flags.
+*/
+
+
+/*!
+	\fn status_t BBitmap::GetOverlayRestrictions(overlay_restrictions*
+		restrictions) const
+	\brief Gets the overlay_restrictions structure for this bitmap.
+
+	\note This function is not part of the BeOS R5 API.
+
+	\param restrictions The overlay restrictions flag
+
+	\retval B_OK The overlay restriction structure was found.
+	\retval B_BAD_TYPE The overlay restriction structure for the bitmap could
+		not be found.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Setters
+*/
+
+
+//! @{
+
+
+/*!
+	\fn void BBitmap::SetBits(const void* data, int32 length, int32 offset,
+		color_space colorSpace)
+	\brief Assigns data to the bitmap.
+
+	Data are directly written into the bitmap's data buffer, being converted
+	beforehand, if necessary. Some conversions do not work intuitively:
+	- \c B_RGB32: The source buffer is supposed to contain \c B_RGB24_BIG
+	  data without padding at the end of the rows.
+	- \c B_RGB32: The source buffer is supposed to contain \c B_CMAP8
+	  data without padding at the end of the rows.
+	- other color spaces: The source buffer is supposed to contain data
+	  according to the specified color space being padded to int32 row-wise.
+
+	The currently supported source/target color spaces are
+	<code>B_RGB{32,24,16,15}[_BIG]</code>, \c B_CMAP8 and
+	<code>B_GRAY{8,1}</code>.
+
+	\note Since this methods is a bit strange to use, Haiku has introduced
+		the ImportBits() method which is the recommended replacement.
+
+	\param data The data to be copied.
+	\param length The length in bytes of the data to be copied.
+	\param offset The offset (in bytes) relative to beginning of the bitmap
+		   data specifying the position at which the source data shall be
+		   written.
+	\param colorSpace Color space of the source data.
+*/
+
+
+/*!
+	\fn status_t BBitmap::ImportBits(const void* data, int32 length, int32 bpr,
+		int32 offset, color_space colorSpace)
+	\brief Assigns data to the bitmap.
+
+	Data are directly written into the bitmap's data buffer, being converted
+	beforehand, if necessary. Unlike for SetBits(), the meaning of
+	\a colorSpace is exactly the expected one here, i.e. the source buffer
+	is supposed to contain data of that color space. \a bpr specifies how
+	many bytes the source contains per row. \c B_ANY_BYTES_PER_ROW can be
+	supplied, if standard padding to int32 is used.
+
+	The currently supported source/target color spaces are
+	<code>B_RGB{32,24,16,15}[_BIG]</code>, \c B_CMAP8 and
+	<code>B_GRAY{8,1}</code>.
+
+	\note This function is not part of the BeOS R5 API.
+
+	\param data The data to be copied.
+	\param length The length in bytes of the data to be copied.
+	\param bpr The number of bytes per row in the source data.
+	\param offset The offset (in bytes) relative to beginning of the bitmap
+		   data specifying the position at which the source data shall be
+		   written.
+	\param colorSpace Color space of the source data.
+
+	\retval B_OK The bits were imported into the bitmap.
+	\retval B_BAD_VALUE \c NULL \a data, invalid \a bpr or \a offset, or
+	  unsupported \a colorSpace.
+*/
+
+
+/*!
+	\fn status_t BBitmap::ImportBits(const void* data, int32 length,
+		int32 bpr, color_space colorSpace, BPoint from, BPoint to,
+		int32 width, int32 height)
+	\brief Assigns data to the bitmap.
+
+	Allows for a BPoint offset in the source and in the bitmap. The region
+	of the source at \a from extending \a width and \a height is assigned
+	(and converted if necessary) to the bitmap at \a to.
+
+	The currently supported source/target color spaces are
+	<code>B_RGB{32,24,16,15}[_BIG]</code>, \c B_CMAP8 and
+	<code>B_GRAY{8,1}</code>.
+
+	\note This function is not part of the BeOS R5 API.
+
+	\param data The data to be copied.
+	\param length The length in bytes of the data to be copied.
+	\param bpr The number of bytes per row in the source data.
+	\param colorSpace Color space of the source data.
+	\param from The offset in the source where reading should begin.
+	\param to The offset in the bitmap where the source should be written.
+	\param width The width (in pixels) to be imported.
+	\param height The height (in pixels) to be imported.
+
+	\retval B_OK The bits were imported into the bitmap.
+	\retval B_BAD_VALUE: \c NULL \a data, invalid \a bpr, unsupported
+		\a colorSpace or invalid \a width or \a height.
+*/
+
+
+/*!
+	\fn status_t BBitmap::ImportBits(const BBitmap* bitmap)
+	\brief Assigns another bitmap's data to this bitmap.
+
+	The supplied bitmap must have the exactly same dimensions as this bitmap.
+	Its data is converted to the color space of this bitmap.
+
+	The currently supported source/target color spaces are
+	<code>B_RGB{32,24,16,15}[_BIG]</code>, \c B_CMAP8 and
+	<code>B_GRAY{8,1}</code>.
+
+	\note This function is not part of the BeOS R5 API.
+
+	\param bitmap The source bitmap.
+
+	\retval B_OK The bits were imported into the bitmap.
+	\retval B_BAD_VALUE \c NULL \a bitmap, or \a bitmap has other dimensions,
+		or the conversion from or to one of the color spaces is not supported.
+*/
+
+
+/*!
+	\fn status_t BBitmap::ImportBits(const BBitmap* bitmap, BPoint from,
+		BPoint to,int32 width, int32 height)
+	\brief Assigns data to the bitmap.
+
+	Allows for a BPoint offset in the source and in the bitmap. The region
+	of the source at \a from extending \a width and \a height is assigned
+	(and converted if necessary) to the bitmap at \a to. The source bitmap is
+	clipped to the bitmap and they don't need to have the same dimensions.
+
+	The currently supported source/target color spaces are
+	<code>B_RGB{32,24,16,15}[_BIG]</code>, \c B_CMAP8 and
+	<code>B_GRAY{8,1}</code>.
+
+	\note This function is not part of the BeOS R5 API.
+
+	\param bitmap The source bitmap.
+	\param from The offset in the source where reading should begin.
+	\param to The offset in the bitmap where the source should be written.
+	\param width The width (in pixels) to be imported.
+	\param height The height (in pixels) to be imported.
+
+	\retval B_OK The bits were imported into the bitmap.
+	\retval B_BAD_VALUE \c NULL \a bitmap, the conversion from or to one of
+	  	the color spaces is not supported, or invalid \a width or \a height.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Child View Methods
+*/
+
+
+//! @{
+
+
+/*!
+	\fn void BBitmap::AddChild(BView* view)
+	\brief Adds a BView to the bitmap's view hierarchy.
+
+	The bitmap must accept views and the supplied view must not be child of
+	another parent.
+
+	\param view The view to be added.
+*/
+
+
+/*!
+	\fn bool BBitmap::RemoveChild(BView* view)
+	\brief Removes a BView from the bitmap's view hierarchy.
+
+	\param view The view to be removed.
+*/
+
+
+/*!
+	\fn int32 BBitmap::CountChildren() const
+	\brief Gets the number of BViews currently belonging to the bitmap.
+
+	\returns The number of BViews currently belonging to the bitmap.
+*/
+
+
+/*!
+	\fn BView* BBitmap::ChildAt(int32 index) const
+	\brief Gets the BView at a certain index in the bitmap's list of views.
+
+	\param index The index of the BView to be returned.
+	\returns The BView at index \a index or \c NULL if the index is out of
+		range.
+*/
+
+
+/*!
+	\fn BView* BBitmap::FindView(const char* viewName) const
+	\brief Accesses a bitmap's child BView with a the name \a viewName.
+
+	\param viewName The name of the BView to be returned.
+	\returns The BView with the name \a name or \c NULL if the bitmap doesn't
+		know a view with that name.
+*/
+
+
+/*!
+	\fn BView* BBitmap::FindView(BPoint point) const
+	\brief Accesses a bitmap's BView at a certain location.
+
+	\param point The location.
+	\returns The BView with located at \a point or \c NULL if the bitmap
+		doesn't know a view at this location.
+*/
+
+
+//! @}

docs/user/interface/Box.dox

@@ -3,166 +3,253 @@
  * Distributed under the terms of the MIT Licence.
  *
  * Documentation by:
- *  Clark Gaeble
+ *		Clark Gaeble
- *  Adrien Destugues <[email protected]>
+ *		Adrien Destugues <[email protected]>
+ *		John Scipione <[email protected]>
  * Corresponds to:
- *  /trunk/headers/os/interface/Box.h  rev 39685
+ *		/trunk/headers/os/interface/Box.h	 rev 42274
- *  /trunk/src/kits/interface/Box.cpp  rev 39685
+ *		/trunk/src/kits/interface/Box.cpp	 rev 42274
+
 
 /*!
-\file Box.h
+	\file Box.h
-\brief Defines the BBox class
+	\brief Defines the BBox class
 */
 
-/*! \class BBox
+
+/*!
+	\class BBox
 	\ingroup interface
-	\brief Class just drawing a square box with a label in a window.
+	\brief The BBox class is used to draw a square box in a window with an
-	
+	optional label to group related subviews.
-	A Box represents a square on the interface with dimensions, an optional
-	name, and no interactivity.
 
-	This would be used to visually group elements together.
+	A BBox is an organizational interface element used to group related views 
+	together visually. A basic BBox looks like this:
+
+	\image html B_FANCY_BORDER.png
+
+	A box's label can either be text or it can be another control such
+	as a checkbox or dropdown box. See SetLabel() for more details on setting
+	the label on a BBox.
 */
 
-/*! \fn BBox::BBox(BRect frame, const char *name = NULL, uint32 resizingMode = B_FOLLOW_LEFT | B_FOLLOW_TOP, uint32 flags = B_WILL_DRAW | B_FRAME_EVENTS | B_NAVIGABLE_JUMP, border_style border = B_FANCY_BORDER)
-	\brief Constructs a Box from a set of dimensions.
 
-	This is the only constructor that can be used if the box is to be inserted
+/*!
-	in a window that doesn't use the layout system.
+	\fn BBox::BBox(BRect frame, const char *name = NULL,
+		uint32 resizingMode = B_FOLLOW_LEFT | B_FOLLOW_TOP,
+		uint32 flags = B_WILL_DRAW | B_FRAME_EVENTS | B_NAVIGABLE_JUMP,
+		border_style border = B_FANCY_BORDER)
+	\brief Constructs a BBox from a set of dimensions.
 
-	\param frame        The bounds of the box.
+	\note This is the only constructor that can be used if the BBox is to be
-	\param name         The name of the box.
+		inserted in a window that doesn't use the layout system.
-	\param resizingMode Defines the behavior of the box as the parent view
+
+	\param frame The bounds of the BBox.
+	\param name The name of the BBox.
+	\param resizingMode Defines the behavior of the BBox as the parent view
 		resizes.
-	\param flags        Behavior flags for the box. See BView page for more
+	\param flags Behavior flags for the BBox. See BView for details.
-		info.
+	\param border The border_style of the BBox.
-	\param border       Sets the initial style of the border. See SetBorder for
-		more details.
 */
 
 
-/*! \fn BBox::BBox(const char* name, uint32 flags = B_WILL_DRAW | B_FRAME_EVENTS | B_NAVIGABLE_JUMP, border_style border = B_FANCY_BORDER, BView* child = NULL)
+/*!
-	\brief Constructs a named Box, with dimensions defined automatically by the
+	\fn BBox::BBox(const char* name,
+		uint32 flags = B_WILL_DRAW | B_FRAME_EVENTS | B_NAVIGABLE_JUMP,
+		border_style border = B_FANCY_BORDER, BView* child = NULL)
+	\brief Constructs a named BBox with dimensions defined automatically by the
 		Layout Kit.
 
-	\param name   The name of the box.
+	\param name The name of the BBox.
-	\param flags  Behavior flags for the box.
+	\param flags Behavior flags for the BBox. See BView for details.
-	\param border Defines the initial border style.
+	\param border The border_style of the BBox.
-	\param child  Adds an initial child to the box. See: Layout Kit
+	\param child Adds an initial child to the BBox. See the Layout Kit for
+		details.
 */
 
 
-/*! \fn BBox::BBox(border_style border, BView* child)
+/*!
-	\brief Constructs an anonymous Box, with a defined border style and a child.
+	\fn BBox::BBox(border_style border, BView* child)
+	\brief Constructs an anonymous BBox, with a defined border style and
+		a child.
 
-	There can only be a single child view in the box. This view can, however,
+	There can only be a single child view in the BBox. This view can, however,
-	act as a nesting container if you need more things to show inside the box.
+	act as a nesting container if you need more things to show inside the BBox.
-
-	\param border The initial border style of the box.
-	\param child  The child of the Box.
 */
 
 
-/*! \fn BBox::BBox(BMessage* archive)
+/*!
-	\brief For archive restoration, allows a box to be constructed from an
+	\fn BBox::BBox(BMessage* archive)
-		archive message.
+	\brief For archive restoration, allows a BBox to be constructed from an
+		\a archive message.
 
-	You don't usually call this directly, if you want to build a BBox from a
+	This method is usually not called directly. If you want to build a BBox
-	message, prefer calling Instantiate, which can properly handle errors.
+	from a message then you should call Instantiate() which can handle errors
+	properly.
 
-	If the archive is a deep one, the box will also unarchive all of its
+	If the \a archive is a deep one, the BBox will also unarchive all
-	children recursively.
+	of its children recursively.
 
-	\param archive  The archive to restore from.
+	\param archive The \a archive to restore from.
 */
 
 
-/*! \fn static BArchivable*	BBox::Instantiate(BMessage* archive)
+/*!
-	\brief Creates a new BBox from an archive.
+	\fn BBox::~BBox()
+	\brief Destructor method.
 
-	If the message is a valid box, an instance of BBox (created from the
+	Calling the destructor will also free the memory used by the box's label
-	archive) will be returned. Otherwise, this function will return NULL.
+	if it has one.
 */
 
 
-/*! \fn virtual	status_t BBox::Archive(BMessage* archive, bool deep = true) const;
+/*!
-	\brief Archives the box into archive.
+	\fn static BArchivable*	BBox::Instantiate(BMessage* archive)
+	\brief Creates a new BBox from an \a archive.
 
-	\param   archive The target archive which the box data will go into.
+	If the message is a valid BBox then an instance of BBox created from the
-	\param   deep    Whether or not to recursively archive the children.
+	passed in \a archive will be returned. Otherwise this method will
-	\returns B_OK if the archive was successful.
+	return \c NULL.
+
+	\param archive The \a archive message.
+
+	\returns An instance of BBox if the \a archive is valid or \c NULL.
 */
 
 
-/*! \fn virtual	void BBox::SetBorder(border_style border)
+/*!
+	\fn virtual	status_t BBox::Archive(BMessage* archive,
+		bool deep = true) const;
+	\brief Archives the BBox into \a archive.
+
+	\param archive The target \a archive which the BBox data will go
+		into.
+	\param deep Whether or not to recursively archive the children.
+	\returns A status flag indicating if the archive operation was successful.
+	
+	\retval B_OK The archive operation was successful.
+	\retval B_BAD_VALUE The archive operation failed.
+*/
+
+
+/*!
+	\fn virtual	void BBox::SetBorder(border_style border)
 	\brief Sets the border style.
 
-	Possible values are B_PLAIN_BORDER (a single 1-pixel line border),
+	Possible values are \c B_PLAIN_BORDER (a single 1-pixel line border),
-	B_FANCY_BORDER (the default, slightly beveled look), and B_NO_BORDER, which
+	\c B_FANCY_BORDER (the default, beveled look), and \c B_NO_BORDER, which
-	is used to make an invisible box.
+	is used to make an invisible box. See border_style for more details.
 */
 
 
-/*! \fn border_style BBox::Border() const
+/*!
-	\brief Gets the border style.
+	\fn border_style BBox::Border() const
+	\brief Gets the current border_style of a BBox.
+
+	\returns The border_style flag that is currently set to the BBox.
 */
 
 
-/*! \fn float BBox::TopBorderOffset()
+/*!
-	\brief Gets the distance from the very top of the Box to the top border
+	\fn float BBox::TopBorderOffset()
-		line, in pixels.
+	\brief Gets the distance from the very top of the BBox to the top border
+		line in pixels as a \c float.
+
+	\warning This method is not part of the BeOS R5 API and is not yet
+		finalized.
 
 	The distance may vary depending on the text or view used as label, and the
-	font settings. The border is drawn center aligned with the label.
+	font settings. The border is drawn center aligned with the label. You can
+	use this value to line up two boxes visually if one has a label and the
+	other does not.
 
-	You can use this value to line up two boxes visually, if one has a label and
+	\returns The distance offset of the BBox as a \c float.
-	the other has not.
 */
 
 
-/*! \fn BRect BBox::InnerFrame()
+/*!
-	\brief Returns the rectangle just inside the border.
+	\fn BRect BBox::InnerFrame()
+	\brief Gets the rectangle just inside the border of the BBox as a BRect.
+
+	\warning This method is not part of the BeOS R5 API and is not yet
+		finalized.
+
+	\returns A BRect of the dimensions of the box's inside border.
 */
 
 
-/*! \fn void BBox::SetLabel(const char* string)
+/*!
-	\brief Sets the label's text.
+	\fn void BBox::SetLabel(const char* string)
+	\brief Sets the box's label text.
 
-	This text is shown as the box title on screen, so the user can identify the
+	Below is an example of a BBox with a simple text label:
-	purpose of it.
+
+	\image html BBox_example.png
+
+	The code to create a BBox with a text label looks like this:
+
+	\code
+fIconBox = new BBox("Icon Box");
+fIconBox->SetLabel("Icon");
+	\endcode
+
+	\param string The label text string to set as the box's title.
 */
 
 
-/*! \fn status_t BBox::SetLabel(BView* viewLabel)
+/*!
+	\fn status_t BBox::SetLabel(BView* viewLabel)
 	\brief Sets the label from a pre-existing BView.
 
-	You can use any type of BView for this, such as a BPopupMenu.
+	This version of SetLabel() allows building a BBox with a control as a
-	This version of SetLabel is much more powerful than
+	label widget. You can pass in any type of BView derived control for this
-	SetLabel(const char* string). It allows building a box which contents can
+	such as a BPopupMenu or BCheckBox.
-	be changed depending on the label widget.
+
+	An example of a BBox with a BCheckBox control attached is shown below:
+
+	\image html BBox_with_checkbox.png
+
+	The code to create such a BBox looks like this:
+
+	\code
+fVirtualMemoryEnabledCheckBox = new BCheckBox("Virtual memory check box",
+	"Enable virtual memory", new BMessage(kVirtualMemoryEnabled));
+
+BBox* fVirtualMemoryBox = new BBox("Virtual memory box");
+fVirtualMemoryBox->SetLabel(fVirtualMemoryEnabledCheckBox);
+	\endcode
+
+	\param viewLabel A BView.
+	\returns \c B_OK
 */
 
 
-/*! \fn const char*	BBox::Label() const
+/*!
+	\fn const char*	BBox::Label() const
 	\brief Gets the label's text.
 
 	This only works if the label was set as text. If you set another view as the
 	label, you have to get its text by other means, likely starting with
 	LabelView.
+
+	\returns The label text of the BBox as a <tt>const char*</tt> if the BBox
+		has a text label or \c NULL otherwise.
 */
 
 
-/*! \fn BView*	BBox::LabelView() const
+/*!
+	\fn BView*	BBox::LabelView() const
 	\brief Gets the BView representing the label.
 */
 
 
-/*! \fn virtual	void BBox::Draw(BRect updateRect)
+/*!
-	\brief Draws onto the parent window the part of the box that intersects
+	\fn virtual	void BBox::Draw(BRect updateRect)
+	\brief Draws onto the parent window the part of the BBox that intersects
 		the dirty area.
 
-	This is an hook function called by the interface kit. You don't have to call
+	This is an hook method called by the interface kit. You don't have to call
-	it yourself. If you need to force redrawing of (part of) the box, consider
+	it yourself. If you need to force redrawing of (part of) the BBox, consider
 	using Invalidate instead.
 
 	\param updateRect The area that needs to be redrawn. Note the box may draw
@@ -170,83 +257,95 @@
 */
 
 
-/*! \fn virtual	void BBox::AttachedToWindow()
+/*!
-	\brief Hook called when the box is attached to a window.
+	\fn virtual	void BBox::AttachedToWindow()
+	\brief Hook method called when the BBox is attached to a window.
 
-	This function sets the box background color to the parent's one.
+	This method sets the box's background color to the background of the
+	parent view.
 
-	If you are using the layout system, the box is also resized depending
+	If you are using the layout system, the BBox is also resized according to
-	on the layout of the parent view.
+	the layout of the parent view.
 */
 
 
-/*! \fn virtual void BBox::FrameResized(float width, float height)
+/*!
-	\brief Called when the box needs to change its size.
+	\fn virtual void BBox::FrameResized(float width, float height)
+	\brief Called when the BBox needs to change its size.
 
-	This function may be called either because the window in which the box is
+	This method may be called either because the window in which the BBox is
 	was resized, or because the window layout was otherwise altered.
 
-	It recomputes the layouting of the box (including label and contents) and
+	It recomputes the layout of the BBox (including label and contents) and
-	makes it redraw itself as needed.
+	makes it redraw as necessary.
 */
 
 
-/*! \fn 	virtual void BBox::ResizeToPreferred()
+/*!
-	\brief Resizes the box to its preferred dimensions.
+	\fn virtual void BBox::ResizeToPreferred()
+	\brief Resizes the BBox to its preferred dimensions.
 
 	This only works in the non-layout mode, as it forces the resizing.
 */
 
 
-/*!	\fn virtual void BBox::GetPreferredSize(float* _width, float* _height)
+/*!
-	\brief Gets the dimensions the box would prefer to be.
+	\fn virtual void BBox::GetPreferredSize(float* _width, float* _height)
+	\brief Gets the dimensions that the BBox would prefer to be.
 
 	The size is computed from the children sizes, unless it was explicitly set
-	for the box (which canbe done only in layouted mode).
+	for the BBox (which can be done only if the BBox is configured to
+	use the Layout Kit).
 
-	\note Either one of the parameters may be set to NULL if you only want to
+	\note Either the \a _width or \a _height parameter may be set to \c NULL
-		get the other one.
+		if you only want to get the other one.
 
-	\param _width  An output parameter. The width of the preferred size is
+	\param[out] _width The width of the preferred size is placed in here.
-		placed in here.
+	\param[out] _height The height of the preferred size is placed in here.
-	\param _height An output parameter. The height of the preferred size is
-		placed in here.
 */
 
 
-/*! \fn virtual	BSize BBox::MinSize()
+/*!
-	\brief Gets the minimum possible size of the Box.
+	\fn virtual	BSize BBox::MinSize()
+	\brief Gets the minimum possible size of the BBox.
 
-	Drawing the box at this size ensures the label and the child view are
+	Drawing the BBox at this size ensures the label and the child view are
 	visible. Going smaller means something may get invisible on screen for lack
 	of space.
 */
 
 
-/*!	\fn virtual	BSize BBox::MaxSize()
+/*!
-	\brief Gets the maximum possible size of the Box.
+	\fn virtual	BSize BBox::MaxSize()
+	\brief Gets the maximum possible size of the BBox.
 
 	The maximum size depends on the child view's one.
+
+	\returns A BSize of the maximum possible size of the BBox.
 */
 
 
-/*! \fn virtual	BSize BBox::PreferredSize()
+/*!
+	\fn virtual	BSize BBox::PreferredSize()
 	\brief Returns the box's preferred size.
 
 	This is the same as GetPreferredSize, but using the more convenient BSize
 	struct.
+
+	\returns A BSize of the minimum possible size of the BBox.
 */
 
 
-/*! \fn virtual	void BBox::DoLayout()
+/*!
-	\brief Lays out the box. Moves everything to its appropriate position.
+	\fn virtual	void BBox::DoLayout()
+	\brief Lays out the BBox. Moves everything into its appropriate position.
 
-	This only works if the box uses the layout system, ie., was created with
+	This only works if the BBox uses the layout system from the Layout Kit,
-	one of the BRect-less constructors.
+	i.e. it was created with one of the BRect-less constructors.
 
-	Once the size of the box is known, from layouting of the parent views, this
+	Once the size of the BBox is known, from layouting of the parent views,
-	function is called so the box can adjust the position and size of the label,
+	this method is called so the BBox can adjust the position and size of the
-	eventually truncating the text if there is not enough space. The exact
+	label, eventually truncating the text if there is not enough space. The
-	border positions are also computed, then the child view is also layouted if
+	exact border positions are also computed, then the child view is also
-	its size constraints changed.
+	layouted if its size constraints changed.
 */

docs/user/interface/Button.dox

@@ -0,0 +1,456 @@
+/*
+ * Copyright 2011, Haiku inc.
+ * Distributed under the terms of the MIT Licence.
+ *
+ * Documentation by:
+ *  John Scipione <[email protected]>
+ * Corresponds to:
+ *  /trunk/headers/os/interface/Button.h
+ *  /trunk/src/kits/interface/Button.cpp
+
+
+/*!
+	\file Button.h
+	\brief Describes the BButton class.
+*/
+
+
+/*!
+	\class BButton Button.h
+	\ingroup interface
+	\brief A BButton is a labeled on-screen button.
+
+	A BButton control is used to initiate an action. An action is activated
+	by clicking on the button with the mouse or by a keyboard button.
+	If the BButton is the default button for the active window then you can
+	activate it by pushing the <span class="keycap">Enter</span> key.
+
+	\image html BButton_example.png
+
+	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
+	is \c 0 (\c B_CONTROL_OFF).
+
+	BButton inherits from the BControl class.
+*/
+
+
+/*!
+	\fn BButton::BButton(BRect frame, const char* name, const char* label,
+		BMessage* message, uint32 resizingMode, uint32 flags)
+	\brief Creates and initializes a BButton control.
+
+	\note A BButton created with a constructor that includes a frame
+	parameter does \b not utilize the Layout Kit to position and size the
+	control.
+
+	BControl initializes the button's label and assigns it a message that 
+	identifies the action that should be carried out when the button is
+	pressed. When the button is attached to a window it is resizes to the
+	height of the button's frame rectangle to fit the button's border and
+	label in the button's font.
+
+	The \a frame, \a name, \a resizingMode, and \a flags parameters are
+	passed up the inheritance chain to the BView class.
+
+	\param frame The frame rectangle that the button is draw into.
+	\param name The name of the button
+	\param label The button label text
+	\param message The BButtons's action message
+	\param resizingMode Mask sets the parameters by which the BButton can be
+		resized. It should be set to one option for vertical resizing combined
+		with one option for horizontal resizing.
+		\n\n Horizontal resizing options are
+			\li \c B_FOLLOW_LEFT
+			\li \c B_FOLLOW_RIGHT
+			\li \c B_FOLLOW_LEFT_RIGHT
+			\li \c B_FOLLOW_H_CENTER
+
+		Vertical resizing options are
+			\li \c B_FOLLOW_TOP
+			\li \c B_FOLLOW_BOTTOM
+			\li \c B_FOLLOW_TOP_BOTTOM
+			\li \c B_FOLLOW_V_CENTER
+
+		There are two other possibilities
+			\li \c B_FOLLOW_ALL_SIDES
+			\li \c B_FOLLOW_NONE
+
+		See BView for more information on resizing options.
+	\param flags The flags mask sets what notifications the BButton can receive.
+			\n\n Any combination of the following options is allowed
+			\li \c B_WILL_DRAW
+			\li \c B_PULSE_NEEDED
+			\li \c B_FRAME_EVENTS
+			\li \c B_FULL_UPDATE_ON_RESIZE
+			\li \c B_NAVIAGBLE
+			\li \c B_NAVIAGBLE_JUMP
+			\li \c B_SUBPIXEL_PRECISE
+
+		See BView for more information on \a flags.
+*/
+
+
+/*!
+	\fn BButton::BButton(const char* name, const char* label, BMessage* message,
+		uint32 flags)
+	\brief Creates and initializes a BButton control.
+
+	BControl initializes the button's label and assigns it a message that 
+	identifies the action that should be carried out when the button is
+	pressed. When the button is attached to a window it is resizes to the
+	height of the button's frame rectange to fit the button's border and
+	label in the button's font.
+	
+	\param name The \a name of the button
+	\param label The button's \a label text
+	\param message The button's action \a message
+	\param flags The \a flags mask sets what notifications the button can
+		receive. Any combination of the following options is allowed:
+			\li \c B_WILL_DRAW
+			\li \c B_PULSE_NEEDED
+			\li \c B_FRAME_EVENTS
+			\li \c B_FULL_UPDATE_ON_RESIZE
+			\li \c B_NAVIAGBLE
+			\li \c B_NAVIAGBLE_JUMP
+			\li \c B_SUBPIXEL_PRECISE
+
+			See BView for more information on \a flags.
+*/
+
+
+/*!
+	\fn BButton::BButton(const char* label, BMessage* message)
+	\brief Creates and initializes a BButton control.
+
+	Creates the button with the specified \a label. The action carried out
+	by the button is specified by the \a message.
+
+	\param label The button's \a label text
+	\param message The buttons action \a message
+*/
+
+
+/*!
+	\fn BButton::~BButton()
+	\brief Destructor method.
+
+	Standard Destructor.
+*/
+
+
+/*! \fn BButton::BButton(BMessage* archive)
+	\brief Creates a new BButton from an \a archive.
+
+	If the message is a valid button then an instance of BButton created
+	from the passed in \a archive will be returned. Otherwise this method
+	will return \c NULL.
+
+	\returns An instance of BButton if the \a archive is valid or \c NULL.
+*/
+
+
+/*!
+	\fn BArchivable* BButton::Instantiate(BMessage* archive)
+	\brief Instantiates a BButton from a BMessage.
+
+	\param archive The \c archive message to instantiate the BButton.
+
+	\returns a BArchivable object of the BButton.
+*/
+
+
+/*!
+	\fn status_t BButton::Archive(BMessage* archive, bool deep) const
+	\brief Archives the BButton into \a archive.
+
+	\param archive The target \a archive which the BButton data will
+		go into.
+	\param deep Whether or not to recursively archive the BButton's children.
+
+	\retval B_OK The archive operation was successful.
+	\retval B_BAD_VALUE The archive operation failed.
+*/
+
+
+/*!
+	\fn void BButton::Draw(BRect updateRect)
+	\brief Draws the button and sets its label.
+
+	\param updateRect The BRect which the button is drawn into.
+*/
+
+
+/*!
+	\fn void BButton::MouseDown(BPoint point)
+	\brief Hook method to respond to a MouseDown event.
+
+	\param point The point on the screen that the mouse pointer is located at.
+*/
+
+
+/*!
+	\fn void BButton::AttachedToWindow()
+	\brief Hook method that is called when the BButton view is attached
+	to the window.
+*/
+
+
+/*!
+	\fn void BButton::KeyDown(const char *bytes, int32 numBytes)
+	\brief Hook method that is called when a keyboard key is pushed down.
+		to the window.
+	
+	\param bytes The key pressed.
+	\param numBytes The number of keys pressed.
+*/
+
+
+/*!
+	\fn void BButton::MakeDefault(bool flag)
+	\brief Make the BButton the default button i.e. it will be activated
+		when the user pushes the \key{Enter} key.
+	
+	\param flag Pass in \c B_SUPPORTS_LAYOUT if the BButton is positioned
+		by the Layout Kit.
+*/
+
+
+/*!
+	\fn void BButton::SetLabel(const char *string)
+	\brief Sets the BButton's label.
+	
+	\param string The string to set the label to.
+*/
+
+
+/*!
+	\fn bool BButton::IsDefault() const
+	\brief Returns whether or not the BButton is the default button or not, i.e.
+	it responds to the \key{Enter} key.
+	
+	\retval true The button is the default button.
+	\retval false The button is \b not the default button.
+*/
+
+
+/*!
+	\fn void BButton::MessageReceived(BMessage *message)
+	\brief Hook method that is called when a message is received by the BButton.
+
+	\param message The message received.
+*/
+
+
+/*!
+	\fn void BButton::WindowActivated(bool active)
+	\brief Sets the window that the BButton is attached to as activated or not.
+
+	\param active if \c true the window is activated, if \c false the window is
+		deactivated.
+*/
+
+
+/*!
+	\fn void BButton::MouseMoved(BPoint point, uint32 transit,
+		const BMessage *message)
+	\brief Hook method that is called when the mouse is moved.
+
+	\param point The point on the screen that the mouse pointer is located at.
+	\param transit ???
+	\param message The message that is received when the mouse is moved.
+*/
+
+
+/*!
+	\fn void BButton::MouseUp(BPoint point)
+	\brief Hook method that is called when a mouse button is unpressed.
+
+	\param point The point on the screen that the mouse pointer is located at.
+*/
+
+
+/*!
+	\fn void BButton::DetachedFromWindow()
+	\brief Detaches the BButton from the window.
+
+	\see BControl::DetachedFromWindow()
+*/
+
+
+/*!
+	\fn void BButton::SetValue(int32 value)
+	\brief Sets the value of the BButton.
+
+	\note This method can be overridden in order to take a different action
+	when the value changes.
+
+	\param value The value to set to the BButton to. Options include:
+		\li \c 0 (\c B_CONTROL_OFF)
+		\li \c 1 (\c B_CONTROL_ON)
+
+	\see BControl::SetValue()
+*/
+
+
+/*!
+	\fn void BButton::GetPreferredSize(float *_width, float *_height)
+	\brief Gets the dimensions that the BButton would prefer to be.
+
+	The size is computed from the children sizes, unless it was explicitly set
+	for the BButton (which can be done only if the BButton is configured to
+	use the Layout Kit).
+
+	\note Either the \a _width or \a _height parameter may be set to \c NULL
+		if you only want to get the other one.
+
+	\param[out] _width  The width of the preferred size is placed in here.
+	\param[out] _height The height of the preferred size is placed in here.
+*/
+
+
+/*!
+	\fn void BButton::ResizeToPreferred()
+	\brief Resizes the BButton to its preferred size.
+
+	\see BControl::ResizeToPreferred()
+*/
+
+
+/*!
+	\fn status_t BButton::Invoke(BMessage *message)
+	\brief The BButton is invoked from a message.
+
+	This method is used to post a message when the button is clicked or
+	activated by a keyboard button. You can set the object that will
+	handle the message by calling a BControl::SetTarget() from a
+	BInvoker inherited control. A model for the message is set by the
+	BButton constructor or by the BControl::SetMessage() method
+	inherited from BInvoker.
+
+	\returns B_OK If the BButton was invoked, otherwise an error
+		\a status_t flag is returned.
+
+	\see BControl::Invoke()
+*/
+
+
+/*!
+	\fn void BButton::FrameMoved(BPoint newLocation)
+	\brief Move the frame of the BButton.
+
+	\param newLocation The location on the screen that the BButton
+		is moved to.
+
+	\see BControl::FrameMoved();
+*/
+
+
+/*!
+	\fn void BButton::FrameResized(float width, float height)
+	\brief Resize the BButton.
+
+	\param width the new \a width of the BButton
+	\param height the new \a height of the BButton
+
+	\see BControl::FrameResized();
+*/
+
+
+/*!
+	\fn void BButton::MakeFocus(bool focused)
+	\brief Focus or unfocus the BButton.
+
+	\param focused If \c true focus the BButton, otherwise unfocus the BButton.
+
+	\see BControl::MakeFocus()
+*/
+
+
+/*!
+	\fn void BButton::AllAttached()
+	\brief Hook method that is called when the BButton is attached.
+
+	\see BControl::AllAttached()
+*/
+
+
+/*!
+	\fn void BButton::AllDetached()
+	\brief Hook method that is called when the BButton is deattached.
+
+	\see BControl::AllDetached()
+*/
+
+
+/*!
+	\fn BHandler* BButton::ResolveSpecifier(BMessage *message, int32 index,
+		BMessage *specifier, int32 what, property)
+	\brief Resolves specifiers for properties.
+	\see BHandler::ResolveSpecifier()
+*/
+
+
+/*!
+	\fn status_t BButton::GetSupportedSuites(BMessage *message)
+	\brief Reports the suites of messages and specifiers that derived classes
+		understand.
+
+	\param message The message to report the suite of messages and specifiers.
+
+	\see BWindow::GetSupportedSuites()
+*/
+
+
+/*!
+	\fn status_t BButton::Perform(perform_code code, void* _data)
+	\brief Perform an action on the BButton.
+
+	\param code The \a perform_code. One of the following:
+		\li \c PERFORM_CODE_MIN_SIZE
+		\li \c PERFORM_CODE_MAX_SIZE
+		\li \c PERFORM_CODE_PREFERRED_SIZE
+		\li \c PERFORM_CODE_LAYOUT_ALIGNMENT
+		\li \c PERFORM_CODE_HAS_HEIGHT_FOR_WIDTH
+		\li \c PERFORM_CODE_GET_HEIGHT_FOR_WIDTH
+		\li \c PERFORM_CODE_SET_LAYOUT
+		\li \c PERFORM_CODE_INVALIDATE_LAYOUT
+		\li \c PERFORM_CODE_DO_LAYOUT
+	\param _data Data to use to act on.
+
+	\returns \c B_OK if the action was successful or an error code if not.
+*/
+
+
+/*!
+	\fn void BButton::InvalidateLayout(bool descendants)
+	\brief Redraws the BButton.
+
+	\param descendants Redraw subviews as well.
+*/
+
+
+/*!
+	\fn BSize BButton::MinSize()
+	\brief Returns the minimum size of the BButton.
+
+	\returns The minimum BButton size as a BSize
+*/
+
+
+/*!
+	\fn BSize BButton::MaxSize()
+	\brief Returns the maximum size of the BButton.
+
+	\returns The maximum BButton size as a BSize
+*/
+
+
+/*!
+	\fn BSize BButton::PreferredSize()
+	\brief Returns the preferred size of the BButton.
+
+	\returns The preferred BButton size as a BSize
+*/
+

docs/user/interface/GridLayout.dox

@@ -1,3 +1,21 @@
+/*
+ * Copyright 2010, Haiku, Inc. All Rights Reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Documentation by:
+ *   Alex Wilson <[email protected]>
+ * Corresponds to:
+ *   /trunk/headers/os/interface/GridLayout.h  rev 38207
+ *   /trunk/src/kits/interface/GridLayout.cpp  rev 38207
+ */
+
+
+/*!
+	\file GridLayout.h
+	Provides the BGridLayout class.
+*/
+
+
 /*!
 	\class BGridLayout
 	\ingroup interface
@@ -18,150 +36,199 @@
 
 /*!
 	\fn BGridLayout::BGridLayout(float horizontal = 0.0f, float vertical = 0.0f)
-	\brief Create a BGridLayout with \c horizontal space between columns and
+	\brief Create a BGridLayout with \a horizontal space between columns and
-		\c vertical space between rows.
+		\a vertical space between rows.
 */
 
 
 /*!
 	\fn BGridLayout::BGridLayout(BMessage* from)
 	\brief Archive constructor.
+
+	\param from The message to build the BGridLayout from.
+*/
+
+
+/*!
+	\fn BGridLayout::~BGridLayout()
+	\brief Destructor method.
+
+	Standard Destructor.
 */
 
 
 /*!
 	\fn int32 BGridLayout::CountColumns() const
 	\brief Returns the number of active columns in this layout.
+
+	\returns The number of active columns in the layout.
 */
 
 
 /*!
 	\fn int32 BGridLayout::CountRows() const
 	\brief Returns the number of active rows in this layout.
+
+	\returns the number of active rows in the layout.
 */
 
 
 /*!
 	\fn float BGridLayout::HorizontalSpacing() const
 	\brief Returns the spacing between columns for this layout.
+
+	\returns The spacing between columns for the layout.
 */
 
 
 /*!
 	\fn float BGridLayout::VerticalSpacing() const
 	\brief Returns the spacing between rows for this layout.
+
+	\returns The spacing between rows for the layout.
 */
 
 
 /*!
 	\fn void BGridLayout::SetHorizontalSpacing(float spacing);
 	\brief Set the spacing between columns for this layout.
+
+	\param spacing The number of pixels of spacing to set.
 */
 
 
 /*!
 	\fn void BGridLayout::SetVerticalSpacing(float spacing)
 	\brief Set the spacing between rows for this layout.
+
+	\param spacing The number of pixels of spacing to set.
 */
 
 
 /*!
 	\fn	void BGridLayout::SetSpacing(float horizontal, float vertical)
 	\brief Set the spacing between columns and rows for this layout.
+
+	\param horizontal The number of \a horizontal pixels of spacing to set.
+	\param vertical The number of \a vertical pixels of spacing to set.
 */
 
 
 /*!
 	\fn float BGridLayout::ColumnWeight(int32 column) const
-	\brief Returns the weight for \c column.
+	\brief Returns the weight for the specified \a column.
+
+	\returns The \a column weight as a float.
 */
 
 
 /*!
 	\fn void BGridLayout::SetColumnWeight(int32 column, float weight)
-	\brief Set the weight for \c column to \c weight.
+	\brief Set the weight for \a column to \a weight.
+
+	\param column The column to set.
+	\param weight The weight to set.
 */
 
 
 /*!
 	\fn float BGridLayout::MinColumnWidth(int32 column) const
-	\brief Returns the minimum width for \c column.
+	\brief Returns the minimum width for \a column.
+
+	\param column The column to get the minimum width of.
+
+	\returns The minimum width for \a column as a float.
 */
 
 
 /*!
 	\fn void BGridLayout::SetMinColumnWidth(int32 column, float width)
-	\brief Sets the minimum width for \c column to \c width.
+	\brief Sets the minimum width for \a column to \a width.
+
+	\param column The \a column to set the minimum width of.
+	\param width The \a width to set.
 */
 
 
 /*!
 	\fn float BGridLayout::MaxColumnWidth(int32 column) const
-	\brief Returns the maximum width for \c column.
+	\brief Returns the maximum width for \a column.
+
+	\param column The column to get the maximum width of.
+
+	\returns The maximum width for \a column as a float.
 */
 
 
 /*!
 	\fn void BGridLayout::SetMaxColumnWidth(int32 column, float width)
-	\brief Sets the maximum width for \c column to \c width.
+	\brief Sets the maximum width for \a column to \a width.
+
+	\param column The column to set the maximum width of.
+	\param width The \a width to set.
 */
 
 
 /*!
 	\fn float BGridLayout::RowWeight(int32 row) const
-	\brief Returns the weight for \c row.
+	\brief Returns the weight of the specified \a row.
+
+	\returns The weight of the \a row.
 */
 
 
 /*!
 	\fn void BGridLayout::SetRowWeight(int32 row, float weight)
-	\brief Set the weight for \c row to \c weight.
+	\brief Set the weight for \a row to \a weight.
+
+	\param row The \a row number.
+	\param weight The \a 
 */
 
 
 /*!
 	\fn float BGridLayout::MinRowHeight(int32 row) const
-	\brief Returns the minimum height for \c row.
+	\brief Returns the minimum height for \a row.
 */
 
 
 /*!
 	\fn void BGridLayout::SetMinRowHeight(int32 row, float height)
-	\brief Sets the minimum height for \c row to \c width.
+	\brief Sets the minimum height for \a row to \a width.
 */
 
 
 /*!
 	\fn float BGridLayout::MaxRowHeight(int32 row) const
-	\brief Returns the maximum height for \c row.
+	\brief Returns the maximum height for \a row.
 */
 
 
 /*!
 	\fn void BGridLayout::SetMaxRowHeight(int32 row, float height)
-	\brief Sets the maximum height for \c row to \c width.
+	\brief Sets the maximum height for \a row to \a width.
 */
 
 
 /*!
 	\fn BLayoutItem* BGridLayout::AddView(BView* child)
-	\brief Adds \c child to this layout in the first empty cell available, or
+	\brief Adds \a child to this layout in the first empty cell available, or
 		in a new column in the first row if there are no emtpy cells.
 */
 
 
 /*!
 	\fn BLayoutItem* BGridLayout::AddView(int32 index, BView* child);
-	\copybrief BGridLayout::AddView(BView*)
+	\brief BGridLayout::AddView(BView*)
 */
 
 
 /*!
 	\fn BLayoutItem* BGridLayout::AddView(BView* child, int32 column, int32 row,
 			int32 columnCount = 1, int32 rowCount = 1);
-	\brief Adds \c child to this layout at \c column and \c row. \c child may
+	\brief Adds \a child to this layout at \a column and \a row. \a child may
-		also occupy additional cells if \c columnCount or \c rowCount are
+		also occupy additional cells if \a columnCount or \a rowCount are
-		greater than 1.
+		greater than \c 1.
 
 	Fails and returns NULL if the requested area is occupied, or if internal
 	memory allocations fail.
@@ -170,24 +237,24 @@
 
 /*!
 	\fn BLayoutItem* BGridLayout::AddItem(BLayoutItem* item)
-	\brief Adds \c item to this layout in the first empty cell available, or
+	\brief Adds \a item to this layout in the first empty cell available, or
 		in a new column in the first row if there are no emtpy cells.
 */
 
 
 /*!
 	\fn BLayoutItem* BGridLayout::AddItem(int32 index, BLayoutItem* item);
-	\copybrief BGridLayout::AddItem(BLayoutItem*)
+	\brief BGridLayout::AddItem(BLayoutItem*)
 */
 
 
 /*!
 	\fn BLayoutItem* BGridLayout::AddItem(BLayoutItem* item, int32 column,
 		int32 row, int32 columnCount = 1, int32 rowCount = 1);
-	\brief Adds \c item to this layout at \c column and \c row. \c item may
+	\brief Adds \a item to this layout at \a column and \a row. \a item may
-		also occupy additional cells if \c columnCount or \c rowCount are
+		also occupy additional cells if \a columnCount or \a rowCount are
 		greater than 1.
 
-	Fails and returns NULL if the requested area is occupied, or if internal
+	Fails and returns \c NULL if the requested area is occupied, or if internal
 	memory allocations fail.
 */

docs/user/interface/GroupLayout.dox

@@ -1,3 +1,20 @@
+/*
+ * Copyright 2010, Haiku, Inc. All Rights Reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Documentation by:
+ *   Alex Wilson <[email protected]>
+ * Corresponds to:
+ *   /trunk/headers/os/interface/GroupLayout.h  rev 38207
+ *   /trunk/src/kits/interface/GroupLayout.cpp  rev 38207
+ */
+
+
+/*!	\file GroupLayout.h
+	Describes the BGroupLayout class
+*/
+
+
 /*! \class BGroupLayout
 	\ingroup interface
 	\ingroup layout
@@ -29,118 +46,111 @@
 */
 
 
-/*!
+/*!	\fn BGroupLayout::BGroupLayout(enum orientation orientation, float spacing)
-	\fn BGroupLayout::BGroupLayout(enum orientation, float spacing)
 	\brief Creates a new BGroupLayout.
 
-	\param orientation The orientation of this BGroupLayout.
+	\param orientation The #orientation of this BGroupLayout.
 	\param spacing The spacing between BLayoutItems in this BGroupLayout.
 */
 
 
-/*!
+/*! \fn BGroupLayout::~BGroupLayout()
-	\fn BGroupLayout::BGroupLayout(BMessage* from)
+	\brief Destructor method.
-	\brief Archive constructor.
+
+	Standard Destructor.
 */
 
 
-/*!
+/*!	\fn BGroupLayout::BGroupLayout(BMessage* from)
-	\fn float BGroupLayout::Spacing() const
+	\brief Archive constructor.
+
+	\param from The message to construct the BGroupLayout from.
+*/
+
+
+/*!	\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.
-	\brief Get the orientation of this BGroupLayout.
 */
 
 
-/*!
+/*!	\fn void BGroupLayout::SetOrientation(enum orientation orientation)
-	\fn void BGroupLayout::SetOrientation(enum orientation)
+	\brief Set the #orientation of this BGroupLayout.
-	\brief Set the orientation of this BGroupLayout.
+	\param orientation The new #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.
-	\brief Get the weight of the item at \c 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.
-	\brief Set the weight of the item at \c 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, \c child will be on the right, in a horizontal
+		BGroupLayout, \a child will be on the right, in a horizontal
-		BGroupLayout, \c child will be at the bottom.
+		BGroupLayout, \a child will be at the bottom.
 
-	\c child will have a weight of 1.0f.
+	\a child will have a weight of \c 1.0f.
 */
 
 
-/*!
+/*!	\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.
-	\brief Adds \c child to this layout at \c index.
 
-	\c child will have a weight of 1.0f.
+	\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
-	\brief Adds \c child to the end of this layout with a weight of
+		\a weight.
-		\c weight.
 */ 
 
 
-/*!	
+/*!	\fn BLayoutItem* BGroupLayout::AddView(int32 index, BView* child, 
-	\fn BLayoutItem* BGroupLayout::AddView(int32 index, BView* child,
 		float weight)
-	\brief Adds \c child this layout at \c index with a weight of
+	\brief Adds \a child this layout at \a index with a weight of
-		\c weight.
+		\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, \c item will be on the right, in a horizontal
+		BGroupLayout, \a item will be on the right, in a horizontal
-		BGroupLayout, \c item will be at the bottom.
+		BGroupLayout, \a item will be at the bottom.
 
-	\c item will have a weight of 1.0f.
+	\a item will have a weight of \c 1.0f.
 */
 
 
-/*!
+/*!	\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.
-	\brief Adds \c item to this layout at \c index.
 
-	\c item will have a weight of 1.0f.
+	\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
-	\brief Adds \c item to the end of this layout with a weight of
+		\a weight.
-		\c 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
-	\brief Adds \c item this layout at \c index with a weight of
+		\a weight.
-		\c weight.
 */

docs/user/interface/InterfaceDefs.dox

@@ -0,0 +1,65 @@
+/*
+ * Copyright 2001-2011, Haiku, Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ */
+
+/*!	\file InterfaceDefs.h
+	\brief Defines standard interface definitions for controls.
+*/
+
+/*!	\enum border_style
+	Collection of flags that determine the border style drawn around a BBox.
+*/
+
+/*! \var border_style B_PLAIN_BORDER
+
+	\image html B_PLAIN_BORDER.png
+
+	The right and bottom sides of the box are darker than the top and
+	left sides to produce a shadow effect and make the box look like it
+	is raised slightly above the surrounding surface.
+*/
+
+/*! \var border_style B_FANCY_BORDER
+
+	\image html B_FANCY_BORDER.png
+
+	The border is a bevelled to give it a 3D effect. The border is uniform
+	in appearance on all four sides. This is the default appearance.
+*/
+
+/*! \var border_style B_NO_BORDER
+	No border.
+*/
+
+/*!	\enum orientation
+Orientation flag sets the layout to either horizontal or vertical
+	alignment.
+*/
+
+/*!	\var orientation B_HORIZONTAL
+	Horizontal alignment
+*/
+
+/*! \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

@@ -3,7 +3,7 @@
  * Distributed under the terms of the MIT License.
  *
  * Documentation by:
- *  Alex Wilson <[email protected]>
+ *   Alex Wilson <[email protected]>
  * Corresponds to:
  *   /trunk/headers/os/interface/Layout.h  rev 38207
  *   /trunk/src/kits/interface/Layout.cpp  rev 38207
@@ -11,21 +11,22 @@
 
 
 /*!
-\file Layout.h
+	\file Layout.h
-\brief Defines the BLayout class.
+	\brief Defines the BLayout class.
 */
 
 
-/*! \class BLayout
+/*!
+	\class BLayout
 	\ingroup interface
 	\ingroup layout
 	\ingroup libbe
 	\brief The BLayout class provides an interface, and some basic
-		implementation to manage the positioning and sizing of BLayoutItems.
+		implementation to manage the positioning and sizing of BLayoutItem s.
 
-	BLayouts can be attached to a BView, managing the BLayoutItems and BViews
+	BLayouts can be attached to a BView, managing the BLayoutItem&apos;s and
-	that reside in that view, or can be nested within another BLayout as a
+	BView&apos;s that reside in that view, or can be nested within another
-	BLayoutItem.
+	BLayout as a BLayoutItem.
 
 	Before adding a BLayoutItem to a BLayout, that layout must have a target
 	view. When a BLayout is attached directly to a BView via BView::SetLayout()
@@ -34,7 +35,7 @@
 	target of the layout it's nested in, if it does not have a target already.
 	You can retrieve the target view for a layout with the TargetView() method.
 	When adding a BLayoutItem to a BLayout, the item's view (as returned by
-	BLayoutItem::View()) is added to the layout's target view.
+	BLayoutItem::View()) is added to the BLayout&apos;s target view.
 
 \code
 BView* topView = new BGroupView();
@@ -64,97 +65,107 @@ topLayout->AddItem(nestedLayoutWithView);
 	assume that it will break some time in the future.
 */
 
-								
+
-/*! \fn BLayout::BLayout()
+/*!
+	\fn BLayout::BLayout()
 	\brief Default constructor.
 
-	After this constructor has finished, this BLayout holds no BLayoutItems and
+	After this constructor has finished, this BLayout holds no
-	does not have a target BView.
+	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.
 */
 
 
-/*! \fn BLayout::BLayout(BMessage* archive)
+/*!
+	\fn BLayout::BLayout(BMessage* archive)
 	\brief Archive constructor.
+
+	\param archive The archive message.
 */
 
 
-/*! \fn BLayout::~BLayout()
+/*!
-	\brief Destructor, deletes all BLayoutItems that this layout manages,
+	\fn BLayout::~BLayout()
-		and detaches from this BLayout's owner view if there is one.
+	\brief Destructor, deletes all BLayoutItem&apos;s that this layout manages,
+		and detaches from this BLayout&apos;s owner view if there is one.
 
-	Each BLayoutItem's BView (as returned by BLayoutItem::View()) is also
+	Each BLayoutItem&apos;s BView (as returned by BLayoutItem::View()) is also
 	removed from their parent.
 
-	\note Because nested BLayouts are treated as BLayoutItems, any layouts
+	\note Because nested BLayout&apos;s are treated as BLayoutItem&apos;s,
-	nested in this BLayout will be deleted.
+	any layouts nested in this BLayout will be deleted.
 */
 
 
 /*!
 	\name BView targeting and attachment information.
-
-	@{
 */
 
 
-/*! \fn BView* BLayout::Owner() const
+//! @{
+
+
+/*!
+	\fn BView* BLayout::Owner() const
 	\brief Returns the Owner of this layout, i.e. the view this layout manages.
 */
 
 
-/*! \fn BView* BLayout::TargetView() const
+/*!
+	\fn BView* BLayout::TargetView() const
 	\brief Returns the target view of this layout.
 
-	The target view of a layout becomes the parent of any BViews in this layout,
+	The target view of a layout becomes the parent of any BView&apos;s in this
-	as well as the BViews returned by BLayoutItem::View() for each BLayoutItem
+	layout, as well as the BView&apos;s returned by BLayoutItem::View() for
-	in this layout.
+	each BLayoutItem in this layout.
 */
 
 
-/*! \fn BView* BLayout::View()
-	\brief Returns the same BView* as BLayout::Owner(), this method is inherited
-		 from BLayoutItem.
-*/
-
-
-//@}
-
-
 /*!
-	\name Adding, removing, counting and accessing BViews and BLayoutItems in \
+	\fn BView* BLayout::View()
-		this BLayout.
+	\brief Returns the same BView* as BLayout::Owner(), this method is
-
+		inherited from BLayoutItem.
-	@{
 */
 
 
+//! @}
+
+
+/*!
+	\name Adding, removing, counting and accessing BLayout children
+*/
+
+
+//! @{
+
+
 /*!
 	\fn BLayoutItem* BLayout::AddView(BView* child)
 	\brief Creates a BLayoutItem to represent a BView, and adds that item to
 		this layout.
 		
-	\a child is added to this layout's target view.
+	\a child is added to this BLayout&apos;s target view.
 	
-	\returns The BLayoutItem created to represent \a child is, or NULL if there
+	\returns The BLayoutItem created to represent \a child is, or \c NULL if
-		was an error.
+		there was an error.
 
 	\param child The BView to be added to this BLayout. 
 */
 
 
-/*! \fn	BLayoutItem* BLayout::AddView(int32 index, BView* child)
+/*!
+	\fn	BLayoutItem* BLayout::AddView(int32 index, BView* child)
 	\brief Creates a BLayoutItem to represent \a child, and adds that item at
-		\a index to	this layout. \a child is added to this layout's target view.
+		\a index to	this layout. \a child is added to this BLayout&apos;s target view.
 */
 
 
 /*!
 	\fn bool BLayout::AddItem(BLayoutItem* item)
 	\brief Adds a BLayoutItem to this layout, and adds the BView it represents
-		to this layout's target view.
+		to this BLayout&apos;s target view.
 
 	\param item The BLayoutItem to be added.
 	\retval true success
@@ -165,7 +176,7 @@ topLayout->AddItem(nestedLayoutWithView);
 /*!
 	\fn bool BLayout::AddItem(int32 index, BLayoutItem* item)
 	\brief Adds \a item to this layout, and adds the BView \a item represents
-		to this layout's target view.
+		to this BLayout&apos;s target view.
 
 	\param item The BLayoutItem to be added.
 	\param index The index at which to add \c item.
@@ -181,8 +192,8 @@ topLayout->AddItem(nestedLayoutWithView);
 
 /*!
 	\fn bool BLayout::RemoveView(BView* child)
-	\brief Removes and deletes all BLayoutItems representing a BView from this
+	\brief Removes and deletes all BLayoutItem representing a BView from
-		layout.
+		this layout.
 
 	\param child The BView to be removed.
 
@@ -193,10 +204,10 @@ topLayout->AddItem(nestedLayoutWithView);
 
 /*!
 	\fn	bool BLayout::RemoveItem(BLayoutItem* item)
-	\brief Removes a BLayoutITem from this layout, and also removes the view 
+	\brief Removes a BLayoutItem from this layout, and also removes the view 
-		it represents from this layout's target view.
+		it represents from this BLayout&apos;s target view.
 
-	\param item The BLayoutitem to be removed
+	\param item The BLayoutItem to be removed
 	
 	\warning \a item is not deleted, you must delete it manually, or add it	to
 		another BLayout.
@@ -206,7 +217,8 @@ topLayout->AddItem(nestedLayoutWithView);
 */
 
 
-/*! \fn BLayoutItem* BLayout::RemoveItem(int32 index)
+/*!
+	\fn BLayoutItem* BLayout::RemoveItem(int32 index)
 	\brief Remove the BLayoutItem at \a index.
 
 	\see RemoveItem(BLayoutItem*)
@@ -224,7 +236,7 @@ topLayout->AddItem(nestedLayoutWithView);
 
 /*!
 	\fn int32 BLayout::CountItems() const
-	\brief Get the number of BLayoutItems in this layout.
+	\brief Get the number of BLayoutItem s in this layout.
 */
 
 
@@ -248,26 +260,28 @@ topLayout->AddItem(nestedLayoutWithView);
 */
 
 
-//@}
+//! @}
 
 
 /*!
 	\name Subclass helpers.
 	\brief These methods are meant to ease the development of BLayout
 		subclasses.
-
-	@{
 */
 
 
-/*! \fn bool BLayout::AncestorsVisible()
+//! @{
+
+
+/*!
+	\fn bool BLayout::AncestorsVisible()
 	\brief Get the visibility of the ancestors of this layout.
 
 	If a BLayout is connected to a BView, this will always return \c true.
 	If a BLayout is nested in another layout (it was passed to AddItem()), then
-	this will reflect the visibility of this layout's parent layout. If any
+	this will reflect the visibility of this BLayout&apos;s parent layout. If
-	layout is hidden (by BLayout::SetVisible()) between this layout and its
+	any layout is hidden (by BLayout::SetVisible()) between this layout and its
-	target view's layout, then this method will return \c false.
+	target BView&apos;s layout, then this method will return \c false.
 */
 
 
@@ -276,8 +290,8 @@ topLayout->AddItem(nestedLayoutWithView);
 	\brief Returns the on-screen area this layout has received to lay out its
 		items in.
 
-	The return value is in the coordinate space of this layout's target view.
+	The return value is in the coordinate space of this BLayout&apos;s target
-	If this BLayout is attached directly to a BView, then
+	view. If this BLayout is attached directly to a BView, then
 	<tt> LayoutArea().LeftTop() == B_ORIGIN </tt>.
 */
 
@@ -287,27 +301,34 @@ topLayout->AddItem(nestedLayoutWithView);
 	\brief Method to be called by derived classes in their SetVisible()
 		implementation. Calls AncestorVisibilityChanged() on the items in this
 		BLayout.
+
+	\param show \c true to show, \c false to hide.
 */
 
 
-//@}
+//! @}
 
 
 /*!
 	\name Methods triggering or related to laying out this BLayout.
-
-//@{
 */
 
 
-/*!	\fn void BLayout::Relayout(bool immediate = false)
+//! @{
+
+
+/*!
+	\fn void BLayout::Relayout(bool immediate = false)
 	\brief Request this BLayout to reposition and resize its items as required.
 
 	If \a immediate is \c false, and there is already a request to have the
 	window this layout resides in re-laid-out, then the layout will happen at
 	that time. If \a immediate is \c true, and there is no such pending
-	request, nor is this layout's parent layout in the process of laying out
+	request, nor is this BLayout&apos;s parent layout in the process of laying
-	its items, then this BLayout will now layout its items.
+	out its items, then this BLayout will now layout its items.
+
+	\param immediate Whether or not to Relayout immediately or wait for pending
+		requests first.
 */
 
 
@@ -315,10 +336,12 @@ topLayout->AddItem(nestedLayoutWithView);
 	\fn void BLayout::LayoutItems(bool force = false)
 	\brief If there is no layout currently ongoing, and \a force is \c false,
 		creates a new BLayoutContext and calls the DerivedLayoutItems() method
-		of this BLayout and any BLayouts nested in this BLayout.
+		of this BLayout and any BLayout s nested in this BLayout.
 	
 	If 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).
+
+	\param force Force the LayoutItems.
 */
 
 
@@ -329,16 +352,17 @@ topLayout->AddItem(nestedLayoutWithView);
 */
 
 
-//@}
+//! @}
 
 
 /*!
 	\name Invalidation and state mutators and accessors.
-
-	@{
 */
 
 
+//! @{
+
+
 /*!
 	\fn void BLayout::RequireLayout()
 	\brief Flag this layout as stale, i.e. any cached data may still be valid,
@@ -352,7 +376,7 @@ topLayout->AddItem(nestedLayoutWithView);
 		to positioning and sizing of its items.
 
 	Invalidating a BLayout also invalidates the view it is connected to
-	(if there is one) and the BLayout this layout (or this layout's view)
+	(if there is one) and the BLayout this layout (or this BLayout&apos;s view)
 	resides in.
 
 	This method should be called whenever the layout becomes invalid. This might
@@ -379,7 +403,8 @@ topLayout->AddItem(nestedLayoutWithView);
 */
 
 
-/*! \fn void BLayout::DisableLayoutInvalidation()
+/*!
+	\fn void BLayout::DisableLayoutInvalidation()
 	\brief Disable layout invalidation notifications, i.e. calls to
 		this object's InvalidateLayout() method.
 */
@@ -393,18 +418,19 @@ topLayout->AddItem(nestedLayoutWithView);
 */
 
 
-//@}
+//! @}
 
 
 /*!
 	\name Archiving methods
 	\brief These methods relate to the archiving or unarchiving of this object
-		and the BLayoutItems it contains
+		and the BLayoutItem&apos;s it contains
-
-	@{
 */
 
-	
+
+//! @{
+
+
 /*!
 	\fn status_t BLayout::Archive(BMessage* archive, bool deep = true) const
 	\brief Archives this layout into \a archive. If deep is true, also archives
@@ -414,8 +440,8 @@ topLayout->AddItem(nestedLayoutWithView);
 
 /*!
 	\fn status_t BLayout::AllUnarchived(const BMessage* from)
-	\brief Unarchives the BLayoutItems for this layout, calling ItemUnarchived()
+	\brief Unarchives the BLayoutItem&apos;s for this layout, calling
-		for each one.
+		ItemUnarchived() for each one.
 */
 
 
@@ -442,16 +468,17 @@ topLayout->AddItem(nestedLayoutWithView);
 */
 
 
-//@}
+//! @}
 
 
 /*!
 	\name BLayout Hook methods
-
-	@{
 */
 
 
+//! @{
+
+
 /*!
 	\fn bool BLayout::ItemAdded(BLayoutItem* item, int32 atIndex)
 	\brief Hook method called when \a item is added to this layout.
@@ -490,23 +517,23 @@ topLayout->AddItem(nestedLayoutWithView);
 	\fn void BLayout::OwnerChanged(BView* was)
 	\brief Hook method called when this layout is attached to a BView.
 
-	\param was The previous owner of this BLayout, for new BLayouts, this will
+	\param was The previous owner of this BLayout, for new BLayout s, this
-	be NULL.
+		will be \c NULL.
 */
 
 
 /*!
 	\fn void BLayout::AttachedToLayout()
-	\brief Hook method inherited from BLayoutItem, classes derived from BLayout
+	\brief Hook method inherited from BLayoutItem, classes derived from
-		must include the BLayout version of this method in their
+		BLayout must include the BLayout version of this method in their
 		implementation.
 */
 
 
 /*!
 	\fn void BLayout::DetachedFromLayout(BLayout* layout)
-	\brief Hook method inherited from BLayoutItem, classes derived from BLayout
+	\brief Hook method inherited from BLayoutItem, classes derived from
-		must include the BLayout version of this method in their
+		BLayout must include the BLayout version of this method in their
 		implementation.
 
 	\param layout The BLayout that this BLayout was detached from.
@@ -515,11 +542,10 @@ topLayout->AddItem(nestedLayoutWithView);
 
 /*!
 	\fn void BLayout::AncestorVisibilityChanged(bool shown)
-	\brief Hook method inherited from BLayoutItem, classes derived from BLayout
+	\brief Hook method inherited from BLayoutItem, classes derived from
-		must include the BLayout version of this method in their
+		BLayout must include the BLayout version of this method in their
 		implementation.
 */
 
 
-//@}
+//! @}
-

docs/user/interface/LayoutBuilder.Group.dox

@@ -1,3 +1,23 @@
+/*
+ * Copyright 2011, Haiku, Inc. All Rights Reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		John Scipione, [email protected]
+ *		Ingo Weinhold, [email protected]
+ * 
+ * Corresponds to:
+ *		/trunk/headers/os/interface/GroupLayoutBuilder.h	 rev 42274
+ *		/trunk/src/kits/interface/GroupLayoutBuilder.cpp	 rev 42274
+ */
+
+
+/*!
+	\file GroupLayoutBuilder.h
+	\brief Provides the BLayoutBuilder::Group<> class.
+*/
+
+
 /*!
 	\class BLayoutBuilder::Group<>
 	\ingroup interface
@@ -32,14 +52,16 @@
 
 /*!
 	\name Constructors
-
-	@{
 */
 
 
+//! @{
+
+
 /*!
-	\fn BLayoutBuilder::Group<ParentBuilder>::Group(BWindow* window,
+	\fn BLayoutBuilder::Group<ParentBuilder>::Group(BWindow *window,
-		enum orientation, float spacing)
+		enum orientation orientation=B_HORIZONTAL,
+		float spacing=B_USE_DEFAULT_SPACING)
 	\brief Creates a new BGroupLayout, and attaches it to a BWindow.
 
 	\note The top BView* in \a window has its ViewColor set to
@@ -71,8 +93,9 @@
 
 
 /*!
-	\fn template <ParentBuilder> BLayoutBuilder::Group<ParentBuilder>::Group(
+	\fn BLayoutBuilder::Group<ParentBuilder>::Group(
-		enum orientation, float spacing)
+		enum orientation orientation=B_HORIZONTAL,
+		float spacing=B_USE_DEFAULT_SPACING)
 	\brief Creates a new BGroupView and targets it.
 
 	Methods called on this builder will be directed to the new BGroupView's
@@ -83,15 +106,16 @@
 */
 
 
-//@}
+//! @}
 
 
 /*!
 	\name Adding BViews and BLayoutItems
-
-	@{
 */
 
+
+//! @{
+
 /*!
 	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::Add(BView* view)
 	\brief Add a BView to the BGroupLayout this builder represents.
@@ -133,7 +157,7 @@
 */
 
 
-//@}
+//! @}
 
 
 /*!
@@ -142,14 +166,16 @@
 	BLayoutBuilder::Base subclass representing the newly added object. These
 	methods push a new builder on top of the stack, you will not be using
 	\c this builder again until you call End().
-
-	@{
 */
 
 
+//! @{
+
+
 /*!
 	\fn GroupBuilder BLayoutBuilder::Group<ParentBuilder>::AddGroup(
-		enum orientation, float spacing, float weight)
+		enum orientation orientation, float spacing=B_USE_DEFAULT_SPACING,
+		float weight=1.0f)
 	\brief Construct and add a viewless BGroupLayout, then return a GroupBuilder
 		representing the newly added layout.
 
@@ -157,6 +183,7 @@
 	\param spacing The spacing to use for the new BGroupLayout.
 	\param weight The weight for the new BGroupLayout in the BGroupLayout this
 		builder represents.
+
 	\returns A GroupBuilder representing the newly created BGroupLayout.
 */
 
@@ -233,7 +260,8 @@
 
 /*!
 	\fn SplitBuilder BLayoutBuilder::Group<ParentBuilder>::AddSplit(
-		enum orientation, float spacing, float weight)
+		enum orientation orientation, float spacing=B_USE_DEFAULT_SPACING,
+		float weight=1.0f)
 
 	\brief Create and add a new BSplitView with a weight of \c weight, then
 		return a SplitBuilder representing the new BSplitView.
@@ -258,17 +286,18 @@
 */
 
 
-//@}
+//! @}
 
 
 /*!
 	\name Adding BSpaceLayoutItems
 	Some convenience methods for adding special BSpaceLayoutItems.
-
-	@{
 */
 
 
+//! @{
+
+
 /*!
 	\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::AddGlue(
 		float weight = 1.0f)
@@ -305,11 +334,12 @@
 
 /*!
 	\name Accessors
-
-	@{
 */
 
 
+//! @{
+
+
 /*!
 	\fn BGroupLayout* BLayoutBuilder::Group<ParentBuilder>::Layout() const
 	\brief Get the BGroupLayout this builder represents.

docs/user/interface/LayoutBuilder.dox

@@ -1,5 +1,13 @@
-/*!
+/*
-	\class BLayoutBuilder::Base<>
+ * Copyright 2010, Haiku, Inc. All Rights Reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Documentation by:
+ *   Alex Wilson <[email protected]>
+ */
+
+
+/*!	\class BLayoutBuilder::Base<>
 	\ingroup interface
 	\ingroup layout
 	\brief Base for all other layout builders in the BLayoutBuilder namespace.

docs/user/interface/LayoutItem.dox

@@ -1,3 +1,21 @@
+/*
+ * Copyright 2010, Haiku, Inc. All Rights Reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Documentation by:
+ *   Alex Wilson <[email protected]>
+ * Corresponds to:
+ *   /trunk/headers/os/interface/LayoutItem.h  rev 38207
+ *   /trunk/src/kits/interface/LayoutItem.cpp  rev 38207
+ */
+
+
+/*!
+	\file LayoutItem.h
+	Describes the BLayoutItem class
+*/
+
+
 /*!
 	\class BLayoutItem
 	\ingroup interface
@@ -20,7 +38,7 @@
 	\fn BLayoutItem::BLayoutItem(BMessage* archive)
 	\brief Archive constructor.
 
-	Creates a Bunarchiver for \a archive and calls its Finish() method.
+	Creates a BLayoutItem from the \a archive message.
 */
 
 
@@ -31,10 +49,21 @@
 
 
 /*!
-	\name Reporting size and alignment constraints to a BLayout
+	\fn BLayout::~BLayout()
-	@{
+	\brief Destructor method.
+
+	Standard Destructor.
 */
 
+
+/*!
+	\name Reporting size and alignment constraints to a BLayout
+*/
+
+
+//! @{
+
+
 /*!
 	\fn BSize BLayoutItem::MinSize() = 0
 	\brief Returns the minimum desirable size for this item.
@@ -67,7 +96,7 @@
 
 /*!
 	\fn bool BLayoutItem::HasHeightForWidth()
-	\brief Returns whether or not this BLayoutItem's height constraints are
+	\brief Returns whether or not this BLayoutItem&apos;s height constraints are
 		dependent on its width.
 	
 	\note By default, this method returns \c false.
@@ -77,18 +106,18 @@
 /*!
 	\fn void BLayoutItem::GetHeightForWidth(float width, float* min,
 		float* max, float* preferred)
-	\brief Get this BLayoutItem's height constraints for a given \a width.
+	\brief Get this BLayoutItem&apos;s height constraints for a given \a width.
 
 	If a BLayoutItem does not have height for width constraints
 	(HasHeightForWidth() returns \c false) it does not need to implement this
 	method.
 
-	\note It is prudent to compare \a min, \a max, \a preferred to NULL before
+	\note It is prudent to compare \a min, \a max, \a preferred to \c NULL
-	dereferencing them.
+	before dereferencing them.
 */
 
 
-//@}
+//! @}
 
 
 /*!
@@ -100,11 +129,12 @@
 	in when reporting these constraints. It is recommended that all subclasses
 	do this as well, the BAbstractLayoutItem class provides any easy way to
 	include this behaviour in your class.
-
-	@{
 */
 
 
+//! @{
+
+
 /*!
 	\fn void BLayoutItem::SetExplicitMinSize(BSize size) = 0
 	\brief Set this item's explicit min size, to be used in MinSize().
@@ -130,7 +160,7 @@
 */
 
 
-//@}
+//! @}
 
 
 /*!
@@ -138,11 +168,12 @@
 
 	These methods take into account only the local visibility of this
 	item, not the visibility of its ancestors. \n
-
-	@{
 */
 
 
+//! @{
+
+
 /*!
 	\fn bool BLayoutItem::IsVisible() = 0
 	\brief Return the current local visibility of this item. If an item is not
@@ -160,17 +191,17 @@
 */
 
 
-//@}
+//! @}
 
 
 /*!
-	\name Getting and setting the current on-screen positioning of \
+	\name Getting and setting the current on-screen positioning of a BLayoutItem.
-		a BLayoutItem.
-
-	@{
 */
 
 
+//! @{
+
+
 /*!
 	\fn void BLayoutItem::AlignInFrame(BRect frame)
 	\brief Position this BLayoutItem within \a frame, given the value returned
@@ -191,21 +222,21 @@
 	\fn void BLayoutItem::SetFrame(BRect frame) = 0
 	\brief Set the bounding frame of this item.
 
-	\a frame is in the coordinate system of the target view of the 
+	\a frame is in the coordinate system of the target view of the BLayout
-	BLayout this item belongs to.
+		that this item belongs to.
 */
 
 
-//@}
+//! @}
 
 
 /*!
 	\fn BView* BLayoutItem::View()
-	\brief Return the BView this item is representing, or NULL if it does not
+	\brief Return the BView this item is representing, or \c NULL if it does not
 		represent any view.
 
 	When a BLayoutItem is added to a BLayout, this method is called, and the
-	returned BView will be added to the BLayout's target view.
+	returned BView will be added to the BLayout&apos;s target view.
 */
 
 
@@ -216,11 +247,12 @@
 	BLayout. In some implementations they may be handled directly by this
 	BLayoutItem, but many implementations will forward these events to
 	another object.
-
-	@{
 */
 
 
+//! @{
+
+
 /*!
 	\fn void BLayoutItem::InvalidateLayout(bool children = false)
 	\brief Invalidate the layout of this item, or the object it represents.
@@ -237,18 +269,19 @@
 */
 
 
-//@}
+//! @}
 
 
 /*!
 	\name Utility methods for BLayout subclasses
 	\brief Utility methods for the BLayout class to attach and retrieve
 		arbitrary data for a BLayoutItem.
-
-	@{
 */
 
 
+//! @{
+
+
 /*!
 	\fn void* BLayoutItem::LayoutData() const
 	\brief Retrieve arbitrary data attached to this BLayoutItem.
@@ -265,15 +298,17 @@
 */
 
 
-//@}
+//! @}
 
 
-/*! \name Hook methods
+/*!
-
+	\name Hook methods
-	@{
 */
 
 
+//! @{
+
+
 /*!
 	\fn void BLayoutItem::AttachedToLayout()
 	\brief Hook called when this object is attached to a BLayout (via
@@ -288,16 +323,17 @@
 	\fn void BLayoutItem::DetachedFromLayout(BLayout* layout)
 	\brief Hook called when this object is attached to a BLayout (via
 		BLayout::RemoveItem())
-	\param layout The BLayout you were previously attached to.
 
 	\warning You should not use this hook to reattach \c this to \a BLayout,
 		doing so will cause undefined behaviour (probably a crash).
+
+	\param layout The BLayout you were previously attached to.
 */
 
 
 /*!
 	\fn void BLayoutItem::AncestorVisibilityChanged(bool shown)
-	\brief Hook called when this BLayoutItem's ancestors change visibility,
+	\brief Hook called when this BLayoutItem&apos;s ancestors change visibility,
 		effectively hiding or showing this item.
 
 	Implementations of this method should alter the onscreen visibility of this
@@ -306,7 +342,9 @@
 
 	\note This method should not effect the value returned by this object's
 		IsVisible() method.
+
+	\param shown \c true to show, \c false to hide.
 */
 
 
-//@}
+//! @}

docs/user/interface/TwoDimensionalLayout.dox

@@ -1,3 +1,21 @@
+/*
+ * Copyright 2010, Haiku, Inc. All Rights Reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Documentation by:
+ *   Alex Wilson <[email protected]>
+ * Corresponds to:
+ *   /trunk/headers/os/interface/TwoDimensionalLayout.h  rev 38207
+ *   /trunk/src/kits/interface/TwoDimensionalLayout.cpp  rev 38207
+ */
+
+
+/*!
+	\file TwoDimensionalLayout.h
+	\brief Defines the BTwoDimensionalLayout class.
+*/
+
+
 /*!
 	\class BTwoDimensionalLayout
 	\ingroup interface
@@ -8,9 +26,9 @@
 
 	This class manages all the tricky work of actually positioning/resizing
 	items, as well as calculating size constraints and providing extra features,
-	such as spacing/insets and alignment of multiple BTwoDimensionalLayouts.
+	such as spacing/insets and alignment of multiple
-	Derived classes need only implement a few hook methods to get a working
+	BTwoDimensionalLayout&apos;s. Derived classes need only implement a few hook
-	layout.
+	methods to get a working layout.
 
 	\warning This class is not yet finalized, if you use it in your software
 	assume that it will break some time in the future.
@@ -35,23 +53,23 @@
 
 /*!
 	\fn void BTwoDimensionalLayout::AlignLayoutWith(
-		BTwoDimensionalLayout* other, enum orientation)
+		BTwoDimensionalLayout* other, enum orientation orientation)
-	\brief Align the BLayoutItems in two BTwoDimensionalLayouts with each other
+	\brief Align the BLayoutItem&apos;s in the specified \a orientation within
-		within a certain orientation.
+		two or more BTwoDimensionalLayout&apos;s.
 
-	When two (or more) BTwoDimensionalLayouts are aligned within a certain
+	When two (or more) BTwoDimensionalLayout&apos;s are aligned within a
-	orientation, then the BLayoutItems within those BTwoDimensionalLayouts will
+	certain \a orientation, then the BLayoutItem&apos;s within those
-	have identical widths or heights (depending on how the
+	BTwoDimensionalLayout&apos;s will have identical widths or heights
-	BTwoDimensionalLayouts are aligned).
+	(depending on how the BTwoDimensionalLayout&apos;s are aligned.)
 
-	If you align two BGroupLayouts horizontally, for example, then the
+	If you align two BGroupLayout&apos;s horizontally for example, then the
-	BLayoutItems at index 0 in both BGroupLayouts will be given the same
+	BLayoutItem at index 0 in both BGroupLayout&apos;s will be given the same
-	horizontal area. The same is true for the BLayoutItems at index 1, 2, etc..
+	horizontal area. The same is true for the BLayoutItem at index 1,
-	Not all BTwoDimensionalLayouts have to have an item at each index for the
+	2, etc. Not all BTwoDimensionalLayout&apos;s have to have an item at each
-	alignment to proceed.
+	index for the alignment to proceed.
 
 	\param other The BTwoDimensionalLayout to be aligned with.
-	\param orientation The orientation on which to be aligned.
+	\param orientation The \a orientation on which to be aligned.
 */
 
 
@@ -61,7 +79,7 @@
 	\brief Set the insets for this BTwoDimensionalLayout (in pixels).
 
 	Set the spacing around the edges of this BTwoDimensionalLayout. If you
-	pass B_USE_DEFAULT_SPACING for a certain parameter, that parameter will
+	pass \c B_USE_DEFAULT_SPACING for a certain parameter, that parameter will
 	be replaced with the value returned by BControlLook::DefaultItemSpacing().
 
 	\see BTwoDimensionalLayout::GetInsets();
@@ -71,9 +89,9 @@
 /*!
 	\fn void BTwoDimensionalLayout::GetInsets(float* left, float* top,
 		float* right, float* bottom) const
-	\brief Get the insets for this BTwoDimensionalLayout (in pixels).
+	\brief Get the insets for the BTwoDimensionalLayout (in pixels).
 
-	Passing NULL for any paramater is not an error, such parameters will
+	Passing \c NULL for any parameter is not an error, those parameters will
 	be ignored.
 
 	\see BTwoDimensionalLayout::SetInsets();
@@ -85,16 +103,17 @@
 
 	These methods are called automatically as needed during layout, and
 	provide the BTwoDimensionalLayout class with the necessary information
-	to properly layout the BLayoutItems in this BTwoDimensionalLayout.
+	to properly layout the BLayoutItem in this BTwoDimensionalLayout.
-
-	@{
 */
 
 
+//! @{
+
+
 /*!
-	\fn void BTwoDimensionalLayout::PrepareItems(enum orientation)
+	\fn void BTwoDimensionalLayout::PrepareItems(enum orientation orientation)
-	\brief Prepare the BLayoutItems in this BTwoDimensionalLayout subclass
+	\brief Prepare the BLayoutItem in this BTwoDimensionalLayout subclass
-		for layout within a certain orientation.
+		for layout within a certain \a orientation.
 
 	This is a good place to update cache information that will be used in
 	other hook methods, for example.
@@ -104,7 +123,7 @@
 /*!
 	\fn bool BTwoDimensionalLayout::HasMultiColumnItems()
 	\brief Tests whether or not this BTwoDimensionalLayout contains any
-		BLayoutItems spanning more than one column.
+		BLayoutItem&apos;s spanning more than one column.
 
 	The BTwoDimensionalLayout implementation returns false.
 */
@@ -113,7 +132,7 @@
 /*!
 	\fn bool BTwoDimensionalLayout::HasMultiRowItems()
 	\brief Tests whether or not this BTwoDimensionalLayout contains any
-		BLayoutItems spanning more than one row.
+		BLayoutItem&apos;s spanning more than one row.
 
 	The BTwoDimensionalLayout implementation returns false.
 */
@@ -121,33 +140,37 @@
 
 /*!
 	\fn int32 BTwoDimensionalLayout::InternalCountColumns()
-	\brief Return the number of columns in this BTwoDimensionalLayout.
+	\brief Get the number of columns in the BTwoDimensionalLayout.
+
+	\returns The number of columns in the BTwoDimensionalLayout.
 */
 
 
 /*!
 	\fn int32 BTwoDimensionalLayout::InternalCountRows()
-	\brief Return the number of rows in this BTwoDimensionalLayout.
+	\brief Get the number of rows in the BTwoDimensionalLayout.
+
+	\returns The number of rows in the BTwoDimensionalLayout.
 */
 
 
 /*!
-	\fn void BTwoDimensionalLayout::GetColumnRowConstraints(enum orientation,
+	\fn void BTwoDimensionalLayout::GetColumnRowConstraints(enum orientation 
-		int32 index, ColumnRowConstraints* constraints)
+		orientation, int32 index, ColumnRowConstraints* constraints)
 	\brief Fill in the ColumnRowConstraints for a certain column or row in
-		this BTwoDimensionalLayout.
+		the BTwoDimensionalLayout.
 
 	This method is used to communicate the size constraints and weight for
-	a given row/column in this BTwoDimensionalLayout.
+	a given row/column in the BTwoDimensionalLayout.
 */
 
 
 /*!
 	\fn void BTwoDimensionalLayout::GetItemDimensions(BLayoutItem* item,
 		Dimensions* dimensions)
-	\brief Tell the base class what column and row a BLayoutItem is in, as
+	\brief Tell the base class what column and row a BLayoutItem is in as
 		well as how many columns and rows it covers.
 */
 
 
-//@}
+//! @}

docs/user/locale/Catalog.dox

@@ -1,221 +1,248 @@
-/*!
+/*
-\class BCatalog
+ * Copyright 2011, Haiku, Inc. All Rights Reserved.
-\ingroup locale
+ * Distributed under the terms of the MIT License.
-\brief Class handling string localization.
+ *
+ * Authors:
+ *		Axel Dörfler, [email protected]
+ *		John Scipione, [email protected]
+ *		Oliver Tappe, [email protected]
+ * 
+ * Corresponds to:
+ *		/trunk/headers/os/locale/Catalog.h	 rev 42274
+ *		/trunk/src/kits/locale/Catalog.cpp	 rev 42274
+ */
 
-BCatalog is the class that allows you to perform string localization. This means
-you give it a string in english, and it automatically returns the translation of
-this string in the user's specified language, if available.
-
-Most of the time, you don't have to deal with BCatalog directly. You use the
-translation macros instead. However, there are some cases where you will have to
-use catalogs directly. These include :
-	\li Tools for managing catalogs : if you want to add, remove or edit
-entries in a catalog, you need to do it using the BCatalog class.
-	\li Accessing catalogs other than your own : the macros only grant you
-access to the catalog linked with your application. To access other catalogs
-(for example if you create a script interpreter and want to localize the
-scripts), you will have to open a catalog associated with your script.
-
-\section macros Using the macros
-You don't have to do much in your program to handle catalogs. You must first
-set the B_TRANSLATE_CONTEXT define to a string that identifies which part of the
-application the strings you will translate are in. This allows the translators
-to keep track of the strings in the catalog more easily, and find where they are
-visible in the application. then, all you have to do, is enclose any string you
-want to make translatable in the B_TRANSLATE() macro. This macro has two uses,
-it will allow your text to be replaced at run-time by the proper localized one,
-but it will also allow to build the base catalog, the one that you will send to
-the translator team, from your sourcecode.
-
-\section chaining Chaining of catalogs
-The catalogs you get from the locale kit are designed to use a fallback system
-so that the user get strings in the language he's the most fluent with,
-depending on what catalogs are available.
-
-For example, if the user sets his language preferences as french(France),
-spanish, english, when an application loads a catalog, the following rules are
-used :
-	\li Try to load a french(France) catalog. If it is found, this catalog
-		will automatically include strings from the generic french catalog.
-	\li Try to load a generic french catalog.
-	\li Try to load a generic spanish catalog.
-	\li Try to load a generic english catalog.
-	\li If all of them failed, use the strings that are in the source code.
-
-Note that french(France) will failback to french, but then directly to the
-language in the source code. This avoids mixing 3 or more languages in the same
-application if the catalogs are incomplete and avoids confusion.
-
-*/
 
 /*!
-\fn BCatalog::BCatalog(const char* signature, const char* language = NULL, uint32 fingerprint = 0)
+	\file Catalog.h
-\brief Construct a catalog for the given application.
+	\brief Provides the BCatalog class.
-
-This constructor builds a catalog for the application with the given mime
-signature. In Haiku, the mime signature is used as a way to uniquely identify a
-catalog and match it with the corresponding application.
-
-If you don't specify a language, the system default list will be used.
-The language is passed here as a 2 letter ISO code.
-
-The fingerprint is a way to check that the catalog that will be loaded matches
-the current version of the application. A catalog made for a different version
-of the application can be loaded if you set the fingerprint to 0. This is
-usually not a problem, it only means that some strings may not be translated
-properly. But if you want to provide different versions of your application, it
-may be useful to separate their catalogs.
-
-\param signature Mime-signature of the application for which to load a catalog.
-\param language The language of the catalog to load. If NULL, the user settings
-will be used.
-\param fingerprint The fingerprint version-info for the catalog to load. If 0,
-the fingerprint will not be checked,and any version of the catalog will be
-loaded.
-*/
-
-/*!
-\fn const char* BCatalog::GetString(const char* string, const char* context = NULL, const char* comment = NULL)
-\brief Get a string from the catalog.
-
-This method access the data of the catalog and reeturns you the translated
-version of the string. You must pass it the context where the string is, as
-the same string may appear somewhere else and need a differnet translation.
-The comment is optional. It is meant as an help to translators, when the string
-alone is not helpful enough or there are special things to note. The comment is
-also used as a way to uniquely identify a string, so if two identical strings
-share the same context, it is still possible to provide different translations.
-
-\returns The translated string, or the one passed as a parameter if no
-translation was found.
-\param string The string to translate.
-\param context The context where the string is located.
-\param comment Supplementary comment for translators.
-*/
-
-/*!
-\fn const char* BCatalog::GetString(uint32 id)
-\brief Get a string by id from the catalog.
-
-The id based version of this method is slightly faster, as it doesn't have to
-compute the hash from the 3 parameters. However, it will fail if there is an
-hash collision, so you should still fallback to the first one in case of
-problems. Also note that the hash value may be different from one catalog to
-another, depending on the file format they are stored in, so you shouldn't rely
-on this method unless you are sure you can keep all the catalog files under
-control.
-
-\returns The translated string if found, or an empty string.
-\param id The identifier of the string.
-*/
-
-/*!
-\fn const char* BCatalog::GetStringNoAutoCollate(const char* string, const char* context = NULL, const char* comment = NULL)
-\fn const char* GetStringNoAutoCollate(uint32 id)
-\brief Get a string from the catalog, without registering it for collectcatkeys.
-
-This function does exactly the same thing as GetString, except it will not be
-parsed by the collectcatkeys tool. This allows you, for example, to translate a
-string constant that you declared at another place, without getting a warning
-message from collectcatkeys.
-
-\returns The translated string, or the one passed as a parameter if no
-translation was found.
-\param string The string to translate.
-\param context The context where the string is located.
-\param comment Supplementary comment for translators.
 */
 
 
 /*!
-\fn status_t BCatalog::GetData(const char* name, BMessage* msg)
+	\class BCatalog
-\brief Get custom data from the catalog.
+	\ingroup locale
+	\brief Class handling string localization.
 
-This function allows you to localize something else than raw text. This may
+	BCatalog is the class that allows you to perform string localization. This
-include pictures, sounds, videos, or anything else. Note there is no support for
+	means you give it a string in english, and it automatically returns the
-generatinga catalog with such data inside, and the current format may not
+	translation of this string in the user's specified language, if available.
-support it. If you need to localize data that is not text, it is advised to
-handle it by yourself.
 
-\returns An error code.
+	Most of the time, you don't have to deal with BCatalog directly. You use
-\param name The name of the data to retrieve.
+	the translation macros instead. However, there are some cases where you
-\param msg The BMessage to fill in with the data.
+	will have to use catalogs directly. These include :
+		\li Tools for managing catalogs : if you want to add, remove or edit
+			entries in a catalog, you need to do it using the BCatalog class.
+		\li Accessing catalogs other than your own : the macros only grant you
+			access to the catalog linked with your application. To access
+			other catalogs (for example if you create a script interpreter and
+			want to localize the scripts), you will have to open a catalog
+			associated with your script.
+
+	\section macros Using the macros
+	You don't have to do much in your program to handle catalogs. You must
+	first set the B_TRANSLATE_CONTEXT define to a string that identifies which
+	part of the application the strings you will translate are in. This allows
+	the translators to keep track of the strings in the catalog more easily,
+	and find where they are visible in the application. then, all you have to
+	do, is enclose any string you want to make translatable in the
+	B_TRANSLATE() macro. This macro has two uses, it will allow your text to
+	be replaced at run-time by the proper localized one, but it will also
+	allow to build the base catalog, the one that you will send to the
+	translator team, from your sourcecode.
+
+	\section chaining Chaining of catalogs
+	The catalogs you get from the locale kit are designed to use a fallback
+	system so that the user get strings in the language he's the most fluent
+	with, depending on what catalogs are available.
+
+	For example, if the user sets his language preferences as french(France),
+	spanish, english, when an application loads a catalog, the following rules
+	are used :
+		\li Try to load a french(France) catalog. If it is found, this catalog
+			will automatically include strings from the generic french catalog.
+		\li Try to load a generic french catalog.
+		\li Try to load a generic spanish catalog.
+		\li Try to load a generic english catalog.
+		\li If all of them failed, use the strings that are in the source code.
+
+	Note that french(France) will failback to french, but then directly to the
+	language in the source code. This avoids mixing 3 or more languages in the
+	same application if the catalogs are incomplete and avoids confusion.
 */
 
+
 /*!
-\fn status_t BCatalog::GetData(uint32 id, BMessage* msg)
+	\fn BCatalog::BCatalog(const char* signature, const char* language = NULL,
-\brief Get custom data from the catalog.
+		uint32 fingerprint = 0)
+	\brief Construct a catalog for the given application.
 
-As for GetString, the id-based version may be subject to hash-collisions, but is
+	This constructor builds a catalog for the application with the given mime
-faster.
+	signature. In Haiku, the mime signature is used as a way to uniquely
+	identify a catalog and match it with the corresponding application.
 
-Note the current catalog format doesn't allow storing custom data in catalogs,
+	If you don't specify a language, the system default list will be used.
-so the only way to use this function is providing your own catalog add-on for
+	The language is passed here as a 2 letter ISO code.
-storing the data.
+
+	The fingerprint is a way to check that the catalog that will be loaded
+	matches the current version of the application. A catalog made for a
+	different version of the application can be loaded if you set the
+	fingerprint to \c 0. This is usually not a problem, it only means that
+	some strings may not be translated properly. But if you want to provide
+	different versions of your application, it may be useful to separate their
+	catalogs.
+
+	\param signature Mime-signature of the application for which to load a
+		catalog.
+	\param language The language of the catalog to load. If NULL, the user
+		settings will be used.
+	\param fingerprint The fingerprint version-info for the catalog to load.
+		If \c 0, the fingerprint will not be checked,and any version of the
+		catalog will be loaded.
 */
 
+
 /*!
-\fn status_t BCatalog::GetSignature(BString* sig)
+	\fn const char* BCatalog::GetString(const char* string,
-\brief Get the catalog mime-signature.
+		const char* context = NULL, const char* comment = NULL)
+	\brief Get a string from the catalog.
 
-This function fills the sig string with the mime-signature associated to the
+	This method access the data of the catalog and reeturns you the translated
-catalog.
+	version of the string. You must pass it the context where the string is, as
+	the same string may appear somewhere else and need a differnet translation.
+	The comment is optional. It is meant as an help to translators, when the
+	string alone is not helpful enough or there are special things to note.
+	The comment is also used as a way to uniquely identify a string, so if two
+	identical strings share the same context, it is still possible to provide
+	different translations.
 
-\param sig The string where to copy the signature.
+	\param string The string to translate.
-\returns An error code.
+	\param context The context where the string is located.
+	\param comment Supplementary comment for translators.
+
+	\returns The translated string, or the one passed as a parameter if no
+		translation was found.
 */
 
+
 /*!
-\fn status_t BCatalog::GetLanguage(BString* lang)
+	\fn const char* BCatalog::GetString(uint32 id)
-\brief Get the catalog language.
+	\brief Get a string by id from the catalog.
 
-This function fills the lang string with the language name for the catalog.
+	The id based version of this method is slightly faster, as it doesn't
+	have to compute the hash from the 3 parameters. However, it will fail
+	if there is an hash collision, so you should still fallback to the first
+	one in case of problems. Also note that the hash value may be different
+	from one catalog to another, depending on the file format they are stored
+	in, so you shouldn't rely on this method unless you are sure you can keep
+	all the catalog files under control.
 
-\param sig The string where to copy the language.
+	\param id The identifier of the string.
-\returns An error code.
+	\returns The translated string if found, or an empty string.
 */
 
+
 /*!
-\fn status_t BCatalog::GetFingerprint(uint32* fp)
+	\fn status_t BCatalog::GetData(const char* name, BMessage* msg)
-\brief Get the catalog fingerprint.
+	\brief Get custom data from the catalog.
 
-This function setsfp to the fingerprint of the catalog. This allows you to check
+	This function allows you to localize something else than raw text. This
-which version of the sourcecode this catalog was generated from.
+	may include pictures, sounds, videos, or anything else. Note there is no
+	support for generating a catalog with such data inside, and the current
+	format may not support it. If you need to localize data that is not text,
+	it is advised to handle it by yourself.
 
-\returns An error code.
+	\param name The name of the data to retrieve.
-\param fp The integer to set to the fingerprint value.
+	\param msg The BMessage to fill in with the data.
+
+	\returns An error code.
 */
 
+
 /*!
-\fn status_t BCatalog::SetCatalog(const char* signature, uint32 fingerprint)
+	\fn status_t BCatalog::GetData(uint32 id, BMessage* msg)
-\brief Reload the string data.
+	\brief Get custom data from the catalog.
 
-This function reloads the data for the given signature and fingerprint.
+	As for GetString, the id-based version may be subject to hash-collisions,
+	but is faster.
 
-\returns An error code.
+	Note the current catalog format doesn't allow storing custom data in
-\param signature The signature of the catalog youwant to load
+	catalogs, so the only way to use this function is providing your own
-\param fingerprint The fingerprint of the catalog you want to load.
+	catalog add-on for storing the data.
 */
 
+
 /*!
-\fn status_t BCatalog::InitCheck() const
+	\fn status_t BCatalog::GetSignature(BString* sig)
-\brief Check if the catalog is in an useable state.
+	\brief Get the catalog mime-signature.
 
-This function returns B_OK if the catalog is initialized properly.
+	This function fills the sig string with the mime-signature associated to the
+	catalog.
+
+	\param sig The string where to copy the signature.
+
+	\returns An error code.
 */
 
+
 /*!
-\fn int32 BCatalog::CountItems()
+	\fn status_t BCatalog::GetLanguage(BString* lang)
-\brief Returns the number of items in the catalog.
+	\brief Get the catalog language.
 
-This function returns the number of strings in the catalog.
+	This function fills the lang string with the language name for the catalog.
+
+	\param lang The string where to copy the language.
+
+	\returns An error code.
 */
 
+
 /*!
-\fn BCatalogaddOn* BCatalog::CatalogAddOn()
+	\fn status_t BCatalog::GetFingerprint(uint32* fp)
-\brief Returns the internal storage for this catalog.
+	\brief Get the catalog fingerprint.
 
-This function returns the internal storage class used by this catalog.
+	This function setsfp to the fingerprint of the catalog. This allows you
-You should not have to use it.
+	to check which version of the sourcecode this catalog was generated from.
+
+	\param fp The integer to set to the fingerprint value.
+
+	\returns An error code.
+*/
+
+
+/*!
+	\fn status_t BCatalog::SetCatalog(const char* signature, uint32 fingerprint)
+	\brief Reload the string data.
+
+	This function reloads the data for the given signature and fingerprint.
+
+	\param signature The signature of the catalog youwant to load
+	\param fingerprint The fingerprint of the catalog you want to load.
+
+	\returns An error code.
+*/
+
+
+/*!
+	\fn status_t BCatalog::InitCheck() const
+	\brief Check if the catalog is in an useable state.
+
+	\returns \c B_OK if the catalog is initialized properly.
+*/
+
+
+/*!
+	\fn int32 BCatalog::CountItems()
+	\brief Returns the number of items in the catalog.
+
+	\returns the number of strings in the catalog.
+*/
+
+
+/*!
+	\fn BCatalogaddOn* BCatalog::CatalogAddOn()
+	\brief Returns the internal storage for this catalog.
+
+	\returns the internal storage class used by this catalog. You should
+	not have to use it.
 */

docs/user/locale/Collator.dox

@@ -1,154 +1,225 @@
+/*
+ * Copyright 2011, Haiku, Inc. All Rights Reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		Axel Dörfler, [email protected]
+ *		Adrien Destugues <[email protected]>
+ *		John Scipione, [email protected]
+ *
+ * Corresponds to:
+ *		/trunk/headers/os/locale/Collator.h	 rev 42274
+ *		/trunk/src/kits/locale/Collator.cpp	 rev 42274
+ */
+
+
 /*!
-\class BCollator
+	\file Collator.h
-\ingroup locale
+	\brief Provides the BCollator class.
-\brief Class for handling collation of string
+*/
 
-BCatalog is designed to handle collations (sorting) of strings.
-The collation is done using a set of rules that changes from a country to another.
-For example, in spanish, 'ch' is consiidered as a letter and is sorted between 'c' and 'd'.
-This class is alsoable to perform natural sorting, so that '2' is sorted before '10',
-which is not the case when you do a simple ASCII sort.
 
-\warning This class is not multithread-safe, as Compare() and GetKey() change
+/*!
-the ICUCollator (the strength). So if you want to use a BCollator from
+	\class BCollator
-more than one thread, you need to protect it with a lock.
+	\ingroup locale
+	\brief Class for handling collation of string
 
+	BCatalog is designed to handle collations (sorting) of strings.
+	The collation is done using a set of rules that changes from a country
+	to another.  For example, in spanish, 'ch' is consiidered as a letter
+	and is sorted between 'c' and 'd'. This class is alsoable to perform
+	natural sorting, so that '2' is sorted before '10', which is not the
+	case when you do a simple ASCII sort.
+
+	\warning This class is not multithread-safe, as Compare() and GetKey()
+	change the ICUCollator (the strength). So if you want to use a
+	BCollator from more than one thread, you need to protect it with a lock.
 */
 
 /*!
-\fn BCollator::BCollator()
+	\fn BCollator::BCollator()
-\brief Construct a collator for the default locale.
+	\brief Construct a collator for the default locale.
+
+	Empty contructor.
 */
 
 /*!
-\fn BCollator::BCollator(const char* locale, int8 strength = B_COLLATE_PRIMARY, bool ignorePunctiation = false)
+	\fn BCollator::BCollator(const char* locale,
-\brief Construct a collator for the given locale.
+		int8 strength = B_COLLATE_PRIMARY, bool ignorePunctuation = false)
+	\brief Construct a collator for the given locale.
 
-This constructor loads the data for the given locale. You can also adjust the strength and
+	This constructor loads the data for the given locale. You can also
-tell if the collator should take punctuation into account when sorting.
+	adjust the strength and tell if the collator should take punctuation
+	into account when sorting.
+
+	\param locale The \a locale.
+	\param strength The collator class provide four level of strength. These
+		define the handling of various things.
+		\li \c B_COLLATE_PRIMARY doesn't differentiate e from é,
+		\li \c B_COLLATE_SECONDARY takes letter accents into account,
+		\li \c B_COLLATE_TERTIARY is case sensitive,
+		\li \c B_COLLATE_QUATERNARY is very strict. Most of the time you
+			shouldn't need to go that far.
+	\param ignorePunctuation Ignore punctuation in the Collator when sorting.
 */
 
 /*!
-\fn BCollator::BCollator(BMessage* archive)
+	\fn BCollator::BCollator(BMessage* archive)
-\brief Unarchive a collator.
+	\brief Unarchive a collator from a message.
+
+	\param archive The message to unarchive the BCollator from.
 */
 
 /*!
-\fn BCollator::BCollator(const BCollator& other)
+	\fn BCollator::BCollator(const BCollator& other)
-\brief Copy constructor.
+	\brief Copy constructor.
+
+	Constructs a BCollator by making a copy of another BCollator.
+
+	\param other The BCollator to copy from.
 */
 
 /*!
-\fn BCollator::~Bcollator()
+	\fn BCollator::~BCollator()
-\brief Destructor.
+	\brief Destructor.
+
+	Standard destructor method.
 */
 
 /*!
-\fn Bcollator& BCollator::operator=(const BColltr& other)
+	\fn Bcollator& BCollator::operator=(const BCollator& other)
-\brief Assignment operator.
+	\brief Assignment operator.
+
+	\param other the BCollator to assign from.
 */
 
 /*!
-\fn void BCollator::SetDefaultStrength(int8 strength)
+	\fn void BCollator::SetDefaultStrength(int8 strength)
-\brief Set the strength of the collator.
+	\brief Set the strength of the collator.
 
-The collator class provide four level of strength. These define the handling of
+	Note that the \a strength can also be given on a case-by-case basis
-various things.
+	when calling other methods.
-\item B_COLLATE_PRIMARY doesn't differenciate e from é,
-\item B_COLLATE_SECONDARY takes them into account,
-\item B_COLLATE_TERTIARY is case sensitive,
-\item B_COLLATE_QUATERNARY is very strict. Most of the time you shouldn't need
-to go that far.
 
-Note the strength can also be given on a case-by-case basis when calling other
+	\param strength The collator class provide four level of strength.
-methods.
+	These define the handling of various things.
-
+	 \li \c B_COLLATE_PRIMARY doesn't differentiate e from é,
-\param strength The strength the catalog should use as default.
+	 \li \c B_COLLATE_SECONDARY takes letter accents into account,
+	 \li \c B_COLLATE_TERTIARY is case sensitive,
+	 \li \c B_COLLATE_QUATERNARY is very strict. Most of the time you
+		 shouldn't need to go that far.
 */
 
 /*!
-\fn int8 BCollator::DefaultStrength() const
+	\fn int8 BCollator::DefaultStrength() const
-\brief Returns the current strength of this catalog.
+	\brief Get the current strength of this catalog.
+
+	\returns the current strength of this catalog.
 */
 
 /*!
-\fn void BCollator::SetIgnorePunctuation(bool ignore)
+	\fn void BCollator::SetIgnorePunctuation(bool ignore)
-\brief Enable or disable punctuation handling
+	\brief Enable or disable punctuation handling
 
-This function enables or disables the handling of punctuations.
+	This function enables or disables the handling of punctuations.
 
-\param ignore Boolean telling if the punctuation should be ignored.
+	\param ignore Boolean telling if the punctuation should be ignored.
 */
 
 /*!
-\fn bool BCollator::IgnorePunctuation() const
+	\fn bool BCollator::IgnorePunctuation() const
-\brief Return the behaviour ofthe collator regarding punctuation.
+	\brief Gets the behavior of the collator regarding punctuation.
 
-This function returns true if the collator will take punctuation into account
+	This function returns \c true if the collator will take punctuation into
-when sorting.
+	account when sorting.
 */
 
 /*!
-\fn satus_t BCollator::GetSortKey(const char* string, BString* key, int8 strength) const
+	\fn satus_t BCollator::GetSortKey(const char* string, BString* key,
-\brief Compute the sortkey of a string
+		int8 strength) const
+	\brief Compute the sortkey of a string.
 
-A sortkey is a modified version of the string that you can use for faster
+	A sortkey is a modified version of the string that you can use for faster
-comparison with other sortkeys, using strcmp or a similar ASCII comparison. If
+	comparison with other sortkeys, using strcmp or a similar ASCII comparison.
-you need to compare a string with other ones a lot of times, storing the sortkey
+	If you need to compare a string with other ones a lot of times, storing
-will allow you to do the comparisons faster.
+	the sortkey will allow you to do the comparisons faster.
 
-\param string String from which to compute the sortkey.
+	\param string String from which to compute the sortkey.
-\param key The resulting sortkey.
+	\param key The resulting sortkey.
-\param strength The strength to use for computing the sortkey.
+	\param strength The \a strength to use for computing the sortkey.
 
-\returns B_OK if everything went well.
+	\returns B_OK if everything went well.
 */
 
 /*!
-\fn int BCollator::Compare(const char* s1, const char* s2, int8 strength) const
+	\fn int BCollator::Compare(const char* s1, const char* s2,
-\brief Compare two strings.
+		int8 strength) const
+	\brief Compare two strings.
 
-This function returns the difference betweens the two strings, in a way similar
+	Returns the difference betweens the two strings similar to strcmp().
-to strcmp.
 
-\param s1,s2 The strings to compare.
+	\param s1 The first string to compare.
-\returns The comparison value. 0 if the strings are equal, negative if s1<s2,
+	\param s2 The second string to compare.
-positive if s1>s2.
+	\param strength The \a strength to use for comparing the strings.
+
+	\retval 0 if the strings are equal.
+	\retval <0 if s1 is less than s2.
+	\retval >0 if s1 is greater than s2.
 */
 
 /*!
-\fn bool BCollator::Equal(const char* s1, const char* s2, int8 strength) const
+	\fn bool BCollator::Equal(const char* s1, const char* s2,
-\brief Checks two strings for equality.
+		int8 strength) const
+	\brief Checks two strings for equality.
 
-Compares two strings for equality. Note that different strings may end up being
+	Compares two strings for equality. Note that different strings may end
-equal, for example if the differences are only in case and punctuation,
+	up being equal, for example if the differences are only in case and
-depending on the strenght used. Quaterary strength will make this function
+	punctuation, depending on the strength used. Quaterary strength will
-return true only if the strings are byte-for-byte identical.
+	make this function return true only if the strings are byte-for-byte
+	identical.
 
-\returns True if the two strings are identical.
+	\param s1 The first string to compare.
+	\param s2 The second string to compare.
+	\param strength The \a strength to use for comparing the strings.
+
+	\returns \c true if the strings are identical, otherwise \c false.
 */
 
 /*!
-\fn bool BCollator::Greater(cosnt char* s1, const char* s2, int8 strength) const)
+	\fn bool BCollator::Greater(cosnt char* s1, const char* s2,
-\brief Tell if a string is greater than another.
+		int8 strength) const
+	\brief Determine if a string is greater than another.
 
-\returns True if s1 is greater (not equal) than s2.
+	\note !Greater(s1, s2) does the same thing as Greater(s2, s1)
 
-\note !Greater(s1, s2) does the same thing as Greater(s2, s1)
+	\param s1 The first string to compare.
+	\param s2 The second string to compare.
+	\param strength The \a strength to use for comparing the strings.
+
+	\returns \c true if s1 is greater than, but not equal to, s2.
 */
 
 /*!
-\fn bool BCollator::GreaterOrEqual(cosnt char* s1, const char* s2, int8 strength) const)
+	\fn bool BCollator::GreaterOrEqual(cosnt char* s1, const char* s2,
-\brief Tell if a string is greater than another.
+		int8 strength) const
+	\brief Tell if a string is greater than another.
 
-\returns True if s1 is greater or equal to s2.
+	\param s1 The first string to compare.
+	\param s2 The second string to compare.
+	\param strength The \a strength to use for comparing the strings.
+
+	\returns \c true if s1 is greater or equal than s2.
 */
 
 /*!
-\fn static BArchivable* BCollator::Instanciate(BMessage* archive)
+	\fn static BArchivable* BCollator::Instantiate(BMessage* archive)
-\brief Unarchive the collator
+	\brief Unarchive the collator
 
-Thif function allows you to restore a collator that you previously archived. It
+	This function allows you to restore a collator that you previously
-is faster to do that than to buid a collator and set it up by hand every time
+	archived. It is faster to do that than to buid a collator and set
-you need it with the same settings.
+	it up by hand every time you need it with the same settings.
+
+	\param archive The message to restore the collator from.
+
+	\returns A BArchivable object containing the BCollator or \c NULL.
 */
+

docs/user/locale/Country.dox

@@ -1,70 +1,91 @@
-/*!
+/*
-\class BCountry
+ * Copyright 2011, Haiku, Inc. All Rights Reserved.
-\ingroup locale
+ * Distributed under the terms of the MIT License.
-\brief Class representing a country
+ *
+ * Authors:
+ *		Axel Dörfler, [email protected].
+ *		Adrien Destugues, [email protected].
+ *		John Scipione, [email protected]
+ * 
+ * Corresponds to:
+ *		/trunk/headers/os/locale/Country.h	 rev 42274
+ *		/trunk/src/kits/locale/Country.cpp	 rev 42274
+ */
 
-BCountry provides all the information about a particular country.
-This includes the country flag (as an HVIF icon), the localized name of the
-country, and the iso country code.
-
-Date, timeand numer formatting also depends to some extent of the language,
-so they are done in the BLocale classinstead.
 
+/*!	\file Country.h
+	\brief BCountry class definition.
 */
 
-/*!
-\fn BCountry::BCountry(const char* languageCode, const char* countryCode)
-\brief Constructor.
 
-Construct a BCountry from a language and a country code.
+/*!	\class BCountry
+	\ingroup locale
+	\brief Class representing a country
 
+	BCountry provides all the information about a particular country.
+	This includes the country flag (as an HVIF icon), the localized name
+	of the country, and the ISO country code.
+
+	Date, time, and numer formatting also depends to some extent on the
+	language used, so they are found in the BLocale class instead.
 */
 
-/*!
-\fn bool BCountry::GetName(BString& name) const
-\brief Get the name of the country
-
-Fills in the name parameter with the name of the country, in the user's locale.
-*/
 
 /*!
-\fn const char* BCountry::Code() const
+	\fn BCountry::BCountry(const char* countryCode)
-\brief Returns the country code.
+	\brief Initialize a BCountry from a country code.
+
+	\param countryCode The country code to initialize from.
 */
 
+
 /*!
-\fn status_t BCountry::GetIcon(BBitmap* result) const;
+	\fn BCountry::BCountry(const BCountry& other)
-\brief Render the country's flag to the given BBitmap
+	\brief Initialize a BCountry from another BCountry object.
 
-This function renders the Country's flag to the given BBitmap. The bitmap
+	\param other The BCountry object to initialize from.
-should already be set to the pixel format and size you want to use.
-
-The flag is stored in HVIF format and can be rendered atany size and color depth.
-
-\param result The BBitmap to drag the flag to.
-\returns B_OK if the drawing was successful.
 */
 
+
 /*!
-\fn const char* BCountry::GetLocalizedString(uint32 id) const;
+	\fn BCountry& BCountry::operator=(const BCountry& other)
-\brief Get one of the default localized strings for this country.
-
-The strings include monetary symbols and other similar things.
-
 */
 
+
 /*!
-\fn int8 BCountry::Measurement() const
+	\fn BCountry::~BCountry()
-\brief Returrns the measurement used in this country.
+	\brief Destructor method.
-
-\returns B_METRIC for the metric system, or B_US for the USA's system.
 */
 
+
 /*!
-\fn int BCountry::GetTimeZones(BList& timezones) const
+	\fn bool BCountry::GetName(BString& name) const
-\brief Returns all the timeaones used in this country.
+	\brief Get the name of the country.
 
-The count may vary from 0 for countries where there is no data, to twelve, for Russia.
+	Fills in the name parameter with the name of the country in the 
-
+	language set by the user's locale.
-\returns The number of timezones that were added to the list.
+*/
+
+
+/*!
+	\fn const char* BCountry::Code() const
+	\brief Gets the ISO country code for the country.
+
+	\returns The ISO country code for the country.
+*/
+
+
+/*!
+	\fn status_t BCountry::GetIcon(BBitmap* result) const;
+	\brief Render the country's flag to the given BBitmap.
+
+	This function renders the country's flag to the given BBitmap. The bitmap
+	should already be set to the pixel format and size you want to use.
+
+	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.
+
+	\returns \c B_OK if the drawing was successful.
 */

docs/user/locale/Locale.dox

@@ -1,154 +1,517 @@
-/*!
+/*
-\class BLocale
+ * Copyright 2011, Haiku, Inc. All Rights Reserved.
-\ingroup locale
+ * Distributed under the terms of the MIT License.
-\brief Class for representing a locale and its settings.
+ *
+ * Authors:
+ *		Axel Dörfler, [email protected].
+ *		John Scipione, [email protected]
+ *		Oliver Tappe, [email protected].
+ * 
+ * Corresponds to:
+ *		/trunk/headers/os/locale/Locale.h	 rev 42274
+ *		/trunk/src/kits/locale/Locale.cpp	 rev 42274
+ */
 
-A locale is defined by the combination of a country and a language. Using these
-two informations, it is possible to determine the format to use for date, time,
-and number formatting. The BLocale class also provide collators, which allows
-you to sort a list of strings properly depending on a set of rules about
-accented chars and other special cases that vary over the different locales.
-
-BLocale is also the class to use when you want to perform formatting or parsing
-of dates, times, and numbers, in the natural language of the user.
-
-*/
 
 /*!
-\fn const BCollator* BLocale::Collator() const
+	\file Locale.h
-\brief Returns the collator associated to this locale.
+	\brief Provides the BLocale class.
-
-Returns the collator in use for this locale, allowing you to use it to sort a
-set of strings.
-
 */
 
+
+/*!	\class BLocale
+	\ingroup locale
+	\brief Class for representing a locale and its settings.
+
+	A locale is defined by the combination of a country and a language.
+	Using these two informations, it is possible to determine the format
+	to use for date, time, and number formatting. The BLocale class also
+	provide collators, which allows you to sort a list of strings properly
+	depending on a set of rules about accented chars and other special
+	cases that vary over the different locales.
+
+	BLocale is also the class to use when you want to perform formatting
+	or parsing of dates, times, and numbers, in the natural language of
+	the user.
+*/
+
+
 /*!
-\fn const BCountry* BLocale::Country() const
+	\fn BLocale::BLocale(const BLanguage* language,
-\brief Returns the country associated to this locale.
+		const BFormattingConventions* conventions)
-
+	\brief Initializes a BLocale object corresponding to the passed in
-A locale is defined by the combination of a country and a language. This
+		\a language and \a conventions.
-method gets the country part of this information, so you can access the
-data that is not language-dependant (such as the country flag).
-
 */
 
+
 /*!
-\fn const BLanguage* BLocale::Language() const
+	\fn BLocale::BLocale(const BLocale& other)
-\brief Returns the language associated to this locale.
+	\brief Initializes a BLocale object.
-
 */
 
+
 /*!
-\fn const char* BLocale::Code() const
+	status_t BLocale::GetCollator(BCollator* collator) const
-\brief Returns the locale code.
+	\brief Gets the collator associated to this locale.
 
-This function returns the locale name (such as en_US for united states english).
+	Returns the collator in use for this locale, allowing you to use it
+	to sort a set of strings.
 */
 
+
 /*!
-\fn bool BLocale::GetName(BString& name) const
+	\fn BLocale& BLocale::operator=(const BLocale& other)
-\brief Get the name of the locale.
-
-This function fills the name string with the localized name of this locale.
-For example, if the locale us en_US and the user language is french, this function will return "anglais (Etats-Unis)".
 */
 
+
 /*!
-\fn void BLocale::SetCountry(const BCountry& newCountry)
+	\fn BLocale::~BLocale()
-\brief Set the country for this locale.
+	\brief Destructor method.
 */
 
+
 /*!
-\fn void BLocale::SetCollator(const BCollator& newCollator)
+	\fn status_t BLocale::GetCollator(BCollator* collator) const
-\brief Set the collator for this locale.
+	\brief Sets \a collator object to the default collator for the BLocale.
+
+	\param collator A pointer to a BCollator object to fill out.
+
+	\returns A status code.
+	\retval B_OK Everything went well.
+	\retval B_BAD_VALUE \c NULL \a collator object passed in.
+	\retval B_ERROR Unable to lock the BLocale. 
 */
 
+
 /*!
-\fn void BLocale::SetLanguage(const char* languageCode)
+	\fn status_t BLocale::GetLanguage(BLanguage* language) const
-\brief Set the language for this locale.
+	\brief Sets \a language object to the default language for the BLocale.
+
+	\param language A pointer to a BLanguage object to fill out.
+
+	\returns A status code.
+	\retval B_OK Everything went well.
+	\retval B_BAD_VALUE \c NULL \a language object passed in.
+	\retval B_ERROR Unable to lock the BLocale. 
 */
 
+
 /*!
-\fn status_t BLocale::FormatDate(char* string, size_t maxSize, time_t time, bool longFormat)
+	\fn status_t BLocale::GetFormattingConventions(
-\brief Format a date.
+		BFormattingConventions* conventions) const
+	\brief Sets \a conventions object to the default formatting conventions
+		for the BLocale.
 
-Fills in the string with a formatted date. The longFormat parameter allows you
+	\param conventions A pointer to a BFormattingConventions object to fill out.
-to select the short or the full format.
 
-\param string The string buffer to fill with the formated date.
+	\returns A status code.
-\param maxSize The size of the buffer.
+	\retval B_OK Everything went well.
-\param time The time (in seconds since epoch) to format
+	\retval B_BAD_VALUE \c NULL \a conventions object passed in.
-\param longFormat If true, uses the long format (with day name, full month name). If false, use the short format, 08/12/2010 or similar.
+	\retval B_ERROR Unable to lock the BLocale.
 */
 
+
 /*!
-\fn status_t BLocale::FormatDate(BString* string, time_t time, bool longFormat)
+	\fn const char* BLocale::GetString(uint32 id) const
-\brief Formats a date to a BString.
+	\brief Gets the language string for the locale.
+
+	\param id The locale \a id to get the language of.
+
+	\internal Assumes a certain order of the string bases.
+
+	\returns a blank string in the case of an error or the string "UTF-8"
+		if there is \a id is set to \a B_CODESET.
 */
 
+
 /*!
-\fn status_t BLocale::FormatDate(BString* string, int*& fieldPositions, int& fieldCount, time_t time, bool longFormat)
+	\fn void BLocale::SetFormattingConventions(
-\brief Format a date and get information about the different fields.
+		const BFormattingConventions& conventions)
+	\brief Sets the formatting convention for this locale.
 
-This works the same way as the other FormatDatz methods, but also gives you the
+	\param conventions The formatting convention to set.
-offset of the beginning of each field in the date. This is useful if you need to
-split the date in different parts for an user-modifiable area (see the Time
-preflet for an example).
-
-To identify the content of each field, you can use GetDateFields.
-
-This function allocates the fieldPositions arrays, you have to free it when you
-are finished with it.
-
-\sa GetDateFields
 */
 
+
 /*!
-\fn status_t BLocale::GetDateFields(BDateElement*& fields, int& fieldCount, bool longFormat) const
+	\fn void BLocale::SetCollator(const BCollator& newCollator)
-\brief Get the type of each field in this date format
+	\brief Set the collator for this locale.
-
-This function is most often used in combination with FormatDate. FormatDate
-gives you the offset of each field in a formated string, anf GetDateFields gives
-you the type of the field at a given offset. With these informations, you can
-handle the formatted date string as a list of fields that you can split and
-alter at will.
 
+	\param newCollator The collator to set.
 */
 
+
 /*!
-\fn status_t BLocale::GetDateFormat(BString& format, bool longFormat) const
+	\fn void BLocale::SetLanguage(const BLanguage& newLanguage)
-\brief Get the date format string
+	\brief Set the language for this locale.
 
-This function returns the string used internally to represent a date format.
+	\param newLanguage The code of the language to set to locale to.
 */
 
+
 /*!
-\fn status_t BLocale::SetDateFormat(const char* formatString, bool longFormat)
+	\fn ssize_t BLocale::FormatDate(char* string, size_t maxSize, time_t time,
-\brief Set the date format for this locale
+		BDateFormatStyle style) const
+	\brief Fills in \a string with a formatted date up to \a maxSize bytes for
+		the given \a time and \a style for the locale.
 
-Thisfunction allows you to define your own date format for specific purposes.
+	\param string The string buffer to fill with the formatted date.
+	\param maxSize The size of the buffer.
+	\param time The time (in seconds since epoch) to format
+	\param style Specify the long format (with day name, full
+		month name) or the short format, 08/12/2010 or similar.
+
+	\returns The number of bytes written during the date formatting.
+	\retval B_ERROR Unable to lock the BLocale.
+	\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
+	\retval B_BAD_VALUE CheckedArrayByteSink overflowed.
+
+	\sa BLocale::FormatDateTime(char* target, size_t maxSize,
+		time_t time, BDateFormatStyle dateStyle,
+		BTimeFormatStyle timeStyle) const
+	\sa BLocale::FormatTime(char* string, size_t maxSize, time_t time,
+		BTimeFormatStyle style) const
 */
 
+
 /*!
-\fn int BLocale::StartOfWeek() const
+	\fn status_t BLocale::FormatDate(BString *string, time_t time,
-\brief Returns the day used as start of week in this locale.
+		BDateFormatStyle style, const BTimeZone* timeZone) const
+	\brief Fills in \a string with a formatted date for the given
+		\a time, \a style, and \a timeZone for the locale.
 
+	\param string The string buffer to fill with the formatted date.
+	\param time The time (in seconds since epoch) to format
+	\param style Specify the long format (with day name, full
+		month name) or the short format, 08/12/2010 or similar.
+	\param timeZone The time zone.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_ERROR Unable to lock the BLocale.
+	\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
+
+	\sa BLocale::FormatDateTime(BString* target, time_t time,
+		BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle,
+		const BTimeZone* timeZone) const
+	\sa status_t BLocale::FormatTime(BString* string, time_t time,
+		BTimeFormatStyle style, const BTimeZone* timeZone) const
 */
 
+
 /*!
-\fn int BLocale::StringCompare(const char* s1, const char* s2) const
+	\fn status_t BLocale::FormatDate(BString* string, int*& fieldPositions,
-\fn int BLocale::StringCompare(const BString* s1, const BString* s2) const
+		int& fieldCount, time_t time, BDateFormatStyle style) const
-\brief Compares two strings using the locale's collator
+	\brief Fills in \a string with a formatted date for the given
+		\a time and \a style for the locale.
 
-These methods are short-hands to Collator()->StringCompare.
+	\param string The string buffer to fill with the formatted date.
+	\param fieldPositions ???
+	\param fieldCount ???
+	\param time The time (in seconds since epoch) to format
+	\param style Specify the long format (with day name, full
+		month name) or the short format, 08/12/2010 or similar.
 
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_ERROR Unable to lock the BLocale or an error formatting the date.
+	\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
+
+	\sa BLocale::FormatTime(BString* string, int*& fieldPositions,
+		int& fieldCount, time_t time, BTimeFormatStyle style) const
 */
 
+
 /*!
-\fn void BLocale::GetSortKey(const char* string, BString* key) const
+	\fn status_t BLocale::GetDateFields(BDateElement*& fields, int& fieldCount,
-\brief Computes the sort key of a string
+		BDateFormatStyle style) const
+	\brief Get the type of each field in the date format of the locale.
 
-This method is a short-hand to Collator()->GetSortKey.
+	This function is most often used in combination with FormatDate().
+	FormatDate() gives you the offset of each field in a formatted string,
+	and GetDateFields() gives you the type of the field at a given offset.
+	With these informations, you can handle the formatted date string as
+	a list of fields that you can split and alter at will.
 
+	\param fields Pointer to the fields object.
+	\param fieldCount The number of fields.
+	\param style Specify the long format (with day name, full
+		month name) or the short format, 08/12/2010 or similar.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_ERROR Unable to lock the BLocale or an error getting the date
+		fields.
+	\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
+
+	\sa BLocale::GetTimeFields(BDateElement*& fields, int& fieldCount,
+		BTimeFormatStyle style) const
+*/
+
+
+/*!
+	\fn int BLocale::StartOfWeek() const
+	\brief Returns the number of the day used as start of week in this locale.
+
+	\returns a flag that indicates the day of the week that the week starts or
+		B_ERROR if there was an error.
+	\retval B_ERROR Unable to lock the BLocale.
+	\retval B_WEEK_START_SUNDAY If the beginning of the week starts on Sunday.
+	\retval B_WEEK_START_MONDAY If the beginning of the week starts on Monday.
+*/
+
+
+/*!
+	\fn ssize_t BLocale::FormatDateTime(char* target, size_t maxSize,
+		time_t time, BDateFormatStyle dateStyle,
+		BTimeFormatStyle timeStyle) const
+	\brief Fills in \a string with a formatted datetime up to \a maxSize bytes
+		for the given \a time and \a style for the locale.
+
+	\param target The string buffer to fill with the formatted datetime.
+	\param maxSize The size of the buffer.
+	\param time The time (in seconds since epoch) to format
+	\param dateStyle Specify the long format or the short format of the date.
+	\param timeStyle Specify the long format or the short format of the time.
+
+	\returns The number of bytes written during the datetime formatting.
+	\retval B_ERROR Unable to lock the BLocale.
+	\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
+	\retval B_BAD_VALUE CheckedArrayByteSink overflowed.
+
+	\sa BLocale::FormatDate(char* string, size_t maxSize, time_t time,
+		BDateFormatStyle style) const
+	\sa BLocale::FormatTime(char* string, size_t maxSize, time_t time,
+		BTimeFormatStyle style) const
+*/
+
+
+/*!
+	\fn status_t BLocale::FormatDateTime(BString* target, time_t time,
+		BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle,
+		const BTimeZone* timeZone) const
+	\brief Fills in \a string with a formatted datetime for the given
+		\a time, \a timeStyle, and \a timeZone for the locale.
+
+	\param target The string buffer to fill with the formatted date.
+	\param time The time (in seconds since epoch) to format
+	\param dateStyle Specify the long format or the short format of the date.
+	\param timeStyle Specify the long format or the short format of the time.
+	\param timeZone The time zone.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_ERROR Unable to lock the BLocale.
+	\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
+
+	\sa BLocale::FormatDate(BString *string, time_t time,
+		BDateFormatStyle style, const BTimeZone* timeZone) const
+	\sa status_t BLocale::FormatTime(BString* string, time_t time,
+		BTimeFormatStyle style, const BTimeZone* timeZone) const
+*/
+
+
+/*!
+	\fn ssize_t BLocale::FormatTime(char* string, size_t maxSize, time_t time,
+		BTimeFormatStyle style) const
+	\brief Fills in \a string with a formatted date up to \a maxSize bytes for
+		the given \a time and \a style for the locale.
+
+	\param string The string buffer to fill with the formatted time.
+	\param maxSize The size of the buffer.
+	\param time The time (in seconds since epoch) to format
+	\param style Specify the long format or the short format.
+
+	\returns The number of bytes written during the time formatting.
+	\retval B_ERROR Unable to lock the BLocale.
+	\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
+	\retval B_BAD_VALUE CheckedArrayByteSink overflowed.
+
+	\sa BLocale::FormatDate(char* string, size_t maxSize, time_t time,
+		BDateFormatStyle style) const
+	\sa BLocale::FormatDateTime(char* target, size_t maxSize,
+		time_t time, BDateFormatStyle dateStyle,
+		BTimeFormatStyle timeStyle) const
+*/
+
+
+/*!
+	\fn status_t BLocale::FormatTime(BString* string, time_t time,
+		BTimeFormatStyle style, const BTimeZone* timeZone) const
+	\brief Fills in \a string with a formatted time for the given
+		\a time, \a style, and \a timeZone for the locale.
+
+	\param string The string buffer to fill with the formatted date.
+	\param time The time (in seconds since epoch) to format
+	\param style Specify the long format or the short format.
+	\param timeZone The time zone.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_ERROR Unable to lock the BLocale.
+	\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
+
+	\sa BLocale::FormatDate(BString *string, time_t time,
+		BDateFormatStyle style, const BTimeZone* timeZone) const
+	\sa BLocale::FormatDateTime(BString* target, time_t time,
+		BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle,
+		const BTimeZone* timeZone) const
+*/
+
+
+/*!
+	\fn status_t BLocale::FormatTime(BString* string, int*& fieldPositions,
+		int& fieldCount, time_t time, BTimeFormatStyle style) const
+	\brief Fills in \a string with a formatted time for the given
+		\a time and \a style for the locale.
+
+	\param string The string buffer to fill with the formatted time.
+	\param fieldPositions ???
+	\param fieldCount ???
+	\param time The time (in seconds since epoch) to format.
+	\param style Specify the long format or the short format.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_ERROR Unable to lock the BLocale or an error formatting the time.
+	\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
+
+	\sa BLocale::FormatDate(BString* string, int*& fieldPositions,
+		int& fieldCount, time_t time, BDateFormatStyle style) const
+*/
+
+
+/*!
+	\fn status_t BLocale::GetTimeFields(BDateElement*& fields, int& fieldCount,
+		BTimeFormatStyle style) const
+	\brief Get the type of each field in the time format of the locale.
+
+	This function is most often used in combination with FormatTime().
+	FormatTime() gives you the offset of each field in a formatted string,
+	and GetTimeFields() gives you the type of the field at a given offset.
+	With these informations, you can handle the formatted date string as
+	a list of fields that you can split and alter at will.
+
+	\param fields Pointer to the fields object.
+	\param fieldCount The number of fields.
+	\param style Specify the long format or the short format.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_ERROR Unable to lock the BLocale or an error getting the time
+		fields.
+	\retval B_NO_MEMORY Ran out of memory while creating the DateFormat object.
+
+	\sa BLocale::GetDateFields(BDateElement*& fields, int& fieldCount,
+		BDateFormatStyle style) const
+*/
+
+
+/*!
+	\fn ssize_t BLocale::FormatNumber(char* string, size_t maxSize,
+		double value) const
+	\brief Format the \c double \a value as a string and put the result
+		into \a string up to \a maxSize bytes in the current locale.
+
+	\param string The string to put the formatted number into.
+	\param maxSize The maximum of bytes to copy into \a string.
+	\param value The number that you want to get a formatted version of.
+
+	\returns The length of the string created or an error status code in
+	 	the case of an error.
+
+	\sa BLocale::FormatNumber(char* string, size_t maxSize,
+		int32 value) const
+	\sa ssize_t BLocale::FormatMonetary(char* string, size_t maxSize,
+		double value) const
+*/
+
+
+/*!
+	\fn status_t BLocale::FormatNumber(BString* string, double value) const
+	\brief \brief Format the \c double \a value as a string and put the result
+		into \a string in the current locale.
+
+	\param string The string to put the formatted number into.
+	\param value The number that you want to get a formatted version of.
+
+	\returns The length of the string created or an error status code in
+	 	the case of an error.
+
+	\sa BLocale::FormatNumber(BString* string, int32 value) const
+	\sa BLocale::FormatMonetary(BString* string, double value) const
+*/
+
+
+/*!
+	\fn ssize_t BLocale::FormatNumber(char* string, size_t maxSize,
+		int32 value) const
+	\brief Format the \c int32 \a value as a string and put the result
+		into \a string up to \a maxSize bytes in the current locale.
+
+	\param string The string to put the formatted number into.
+	\param maxSize The maximum of bytes to copy into \a string.
+	\param value The number that you want to get a formatted version of.
+
+	\returns The length of the string created or an error status code in
+	 	the case of an error.
+
+	\sa BLocale::FormatNumber(char* string, size_t maxSize,
+		double value) const
+	\sa BLocale::FormatMonetary(char* string, size_t maxSize,
+		double value) const
+*/
+
+
+/*!
+	\fn status_t BLocale::FormatNumber(BString* string, int32 value) const
+	\brief \brief Format the \c int32 \a value as a string and put the result
+		into \a string in the current locale.
+
+	\param string The string to put the formatted number into.
+	\param value The number that you want to get a formatted version of.
+
+	\returns The length of the string created or an error status code in
+	 	the case of an error.
+
+	\sa BLocale::FormatNumber(BString* string, double value) const
+	\sa BLocale::FormatMonetary(BString* string, double value) const
+*/
+
+
+/*!
+	\fn ssize_t BLocale::FormatMonetary(char* string, size_t maxSize,
+		double value) const
+	\brief Format the \c double \a value as a monetary string and put the
+		result into \a string up to \a maxSize bytes in the current locale.
+
+	\param string The string to put the monetary formatted number into.
+	\param maxSize The maximum of bytes to copy into \a string.
+	\param value The number that you want to get a monetary formatted version
+		of.
+
+	\returns The length of the string created or an error status code in
+	 	the case of an error.
+
+	\sa BLocale::FormatNumber(char* string, size_t maxSize,
+		double value) const
+	\sa BLocale::FormatNumber(char* string, size_t maxSize,
+		int32 value) const
+*/
+
+
+/*!
+	\fn status_t BLocale::FormatMonetary(BString* string, double value) const
+	\brief \brief Format the \c double \a value as a monetary string and put
+		the result into \a string in the current locale.
+
+	\param string The string to put the monetary formatted number into.
+	\param value The number that you want to get a monetary formatted version
+		of.
+
+	\returns The length of the string created or an error status code in
+	 	the case of an error.
+
+	\sa BLocale::FormatNumber(BString* string, double value) const
+	\sa BLocale::FormatNumber(BString* string, int32 value) const
 */

docs/user/locale/LocaleRoster.dox

@@ -1,92 +1,214 @@
-/*!
+/*
-\class BLocaleRoster
+ * Copyright 2003-2010, Haiku. All rights reserved.
-\ingroup locale
+ * Distributed under the terms of the MIT License.
-\brief Main class for accessing the locale kit data
+ *
+ * Authors:
+ *		Axel Dörfler, [email protected]
+ *		John Scipione, [email protected]
+ *		Oliver Tappe, [email protected]
+ *
+ * Corresponds to:
+ *		/trunk/headers/os/locale/LocaleRoster.h	 rev 42274
+ *		/trunk/src/kits/locale/LocaleRoster.cpp	 rev 42274
+ */
 
-The Locale Roster is the central part of the locale kit.
-It is a global object (be_locale_roster) storing all the useful locale
-data. Other classes from the Locale Kit can be constructed on their own,
-but only the Locale Roster allows you to do so while taking account of
-the user's locale settings.
-*/
 
 /*!
-\fn status_t BLocaleRoster::GetDefaultCollator(BCollator* collator) const
+	\class BLocaleRoster
-\brief Get the default collator.
+	\ingroup locale
+	\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
+	classes from the Locale Kit can be constructed on their own, but only the
+	Locale Roster allows you to do so while taking account of the user's locale
+	settings.
 */
 
+
 /*!
-\fn status_t BLocaleRoster::GetDefaultLocale(BLocale* locale) const
+	\fn BLocaleRoster::BLocaleRoster()
-\brief Get the default locale.
+	\brief Constructor. Does nothing.
 */
 
+
 /*!
-\fn status_t BLocaleRoster::GetDefaultCountry(BCountry* country) const
+	\fn BLocaleRoster::~BLocaleRoster()
-\brief Get the default country.
+	\brief Destructor. Does nothing.
 */
 
+
 /*!
-\fn status_t BLocaleRoster::GetDefaultLanguage(BLanguage* language) const
+	\fn BLocaleRoster* BLocaleRoster::Default()
-\brief Get the default language.
+	\brief Returns default BLocalRoster.
 */
 
+
 /*!
-\fn status_t BLocaleRoster::GetDefaultTimeZone(BTimeZone* timezone) const
+	\fn status_t BLocaleRoster::Refresh()
-\brief Get the default timezone.
+	\brief Refreshes the BLocalRoster.
 */
 
+
 /*!
-\fn status_t BLocaleRoster::GetLanguage(const char* languagecode, BLanguage** _language) const
+	\fn status_t BLocaleRoster::GetDefaultTimeZone(BTimeZone* timezone) const
-\brief Instanciate a language from its code.
+	\brief Get the default timezone.
 */
 
+
 /*!
-\fn status_t BLocaleRoster::GetAvailableLanguages(BMessage* message) const
+	\fn status_t BLocaleRoster::GetLanguage(const char* languagecode,
-\brief List the available languages
+		BLanguage** _language) const
-
+	\brief Instantiate a language from its code.
-This function fills the passed BMessage with one or more 'language' string
-fields, containing the language(s) ID(s).
-
 */
 
+
 /*!
-\fn status_t BLocaleRoster::GetAvailableCountries(BMessage* message) const
+	\fn status_t BLocaleRoster::GetPreferredLanguages(BMessage* message) const
-\brief List the available countries
+	\brief Return the list of user preferred languages.
-
-This function filles the passed BMessage with one or more 'country' string
-fields, containing the (ISO-639) code of each country.
 
+	This function fills in the given message with one or more language string
+	fields. They constitute the ordered list of user-selected languages to use
+	for string translation.
 */
 
+
 /*!
-\fn status_t BLocaleRoster::GetInstalledCatalogs(BMessage* message, const char* sigPattern = NULL, const char* langPattern = NULL, int32 fingerprint = 0) const
+	\fn status_t BLocaleRoster::GetAvailableLanguages(BMessage* message) const
-\brief Get the available locales and catalogs
+	\brief Fills \c message with 'language'-fields containing the language
-
+		ID(s) of all available languages.
-This function fills the passed BMessage with one or more 'locale' string
-fields, containing the locale names.
-
-The optional parameters can be used to filter the list and only get the
-locales for which a catalog is available for the given app (sigPattern, fingerprint),
-or the locales with a given language.
 */
 
+
 /*!
-\fn BCatalog* BLocaleRoster::GetCatalog()
+	\fn status_t BLocaleRoster::GetAvailableCountries(BMessage* message) const
-\brief Get the current image catalog.
+	\brief Fills in the passed in \a message with one or more 'country'
-
+		string fields, containing the (ISO-639) code of each country.
-This function returns the catalog for the calling image (application, add-on, or shared
-library). Note that it doesn't allow to specify a fingerprint. The language will be
-selected from the user preferences.
-
-\returns The catalog, if it was loaded successfully.
-\warning This function needs the image to be lined with liblocalestub.a
 */
 
+
 /*!
-\fn status_t BLocaleRoster::GetPreferredLanguages(BMessage* message) const
+	\fn status_t BLocaleRoster::GetAvailableTimeZones(BMessage* timeZones) const
-\brief Return the list of user preferred languages.
+	\brief Fills in the passed in \a timeZones message with all time zone
+		strings for the locale.
 
-This function fills in the given message with one or more language string
+	\returns A status code.
-fields. They constitute the ordered list of user-selected languages to use for
+	\retval B_OK Everything went well.
-string translation.
+	\retval B_BAD_VALUE A \c NULL \a timeZones message was passed in.
+	\retval B_ERROR An error occurred trying to retrieve the localized time zone
+		strings.
+*/
+
+
+/*!
+	\fn status_t BLocaleRoster::GetAvailableTimeZonesForCountry(
+		BMessage* timeZones, const char* countryCode) const
+	\brief Fills in the passed in \a timeZones message with one or more
+		time zone strings containing the time zones for the
+		country specified by \a countryCode for the locale.
+
+	\returns A status code.
+	\retval B_OK Everything went well.
+	\retval B_BAD_VALUE A \c NULL \a timeZones message was passed in.
+	\retval B_ERROR An error occurred trying to retrieve the localized time
+		zones most likely due to an invalid \a countryCode.
+*/
+
+
+/*!
+	\fn status_t BLocaleRoster::GetFlagIconForCountry(BBitmap* flagIcon,
+		const char* countryCode)
+	\brief Sets \a flagIcon to the flag for the passed in \a countryCode.
+
+	\returns A status code.
+	\retval B_OK Everything went well.
+	\retval B_BAD_VALUE A \c NULL or invalid \a countryCode was passed in.
+	\retval B_ERROR Error locking the default RosterData.
+	\retval B_NAME_NOT_FOUND The flag could not be found for the
+		\a countryCode.
+*/
+
+
+/*!
+	\fn status_t BLocaleRoster::GetFlagIconForLanguage(BBitmap* flagIcon,
+		const char* languageCode)
+	\brief Sets \a flagIcon to the flag for the passed in \a languageCode.
+
+	If a flag could not be located for the passed in \a languageCode then
+	GetFlagIconForLanguage() attempts to locate the default country's flag for
+	the \a languageCode instead. The default country flag for a language is
+	usually set to the country of the languages origin such as Germany for
+	German or Spain for Spanish.
+
+	\returns A status code.
+	\retval B_OK Everything went well.
+	\retval B_BAD_VALUE A \c NULL or invalid \a languageCode was passed in.
+	\retval B_ERROR Error locking the default RosterData.
+	\retval B_NAME_NOT_FOUND The flag could not be found for the
+		default country's flag for the \a languageCode.
+*/
+
+
+/*!
+	\fn status_t BLocaleRoster::GetAvailableCatalogs(BMessage* languageList,
+		const char* sigPattern,	const char* langPattern,
+		int32 fingerprint) const
+	\brief Get the available locales and catalogs.
+
+	Fills the passed \a languageList message with one or more 'locale' string
+	fields containing the locale names.
+
+	The optional parameters can be used to filter the list and only get the
+	locales for which a catalog is available for the given app (sigPattern,
+	fingerprint), or the locales with a given language.
+
+	\returns A status code.
+	\retval B_OK Everything went well.
+	\retval B_BAD_VALUE A \c NULL \a languageList message was passed in.
+	\retval B_ERROR Error locking the default RosterData.
+*/
+
+
+/*!
+	\fn bool BLocaleRoster::IsFilesystemTranslationPreferred() const
+	\brief Returns whether or not filesystem translation is preferred.
+
+	\returns \c B_ERROR if there was an error locking the default RosterData.
+*/
+
+
+/*!
+	\fn status_t BLocaleRoster::GetLocalizedFileName(BString& localizedFileName,
+		const entry_ref& ref, bool traverse)
+	\brief Looks up a localized filename from a catalog.
+
+	Attribute format:  "signature:context:string"
+	(no colon in any of signature, context and string)
+
+	Lookup is done for the top preferred language only.
+	Lookup fails if a comment is present in the catalog entry.
+
+	\param localizedFileName A pre-allocated BString object for the result
+		of the lookup.
+	\param ref An entry_ref with an attribute holding data for catalog lookup.
+	\param traverse Determines if symlinks should be traversed.
+
+	\returns A status code.
+	\retval B_OK: success
+	\retval B_ENTRY_NOT_FOUND: failure. Attribute not found, entry not found
+		in catalog, etc.
+*/
+
+
+/*!
+	\fn BCatalog* BLocaleRoster::_GetCatalog()
+	\brief Get the current image catalog.
+
+	This function returns the catalog for the calling image (application,
+	add-on, or shared library). Note that it doesn't allow to specify a
+	fingerprint. The language will be selected from the user preferences.
+
+	\warning This function needs the image to be lined with liblocalestub.a
+
+	\returns The catalog, if it was loaded successfully.
 */

docs/user/locale/TimeZone.cpp

@@ -1,72 +0,0 @@
-/*!
-\class BTimeZone
-\ingroup locale
-\brief Class holding information for a time zone.
-
-*/
-
-/*!
-\fn BTimeZone::BTimeZone(const char* zoneCode)
-\brief Construct a timezone from its code.
-
-The constructor only allows you to construct a timezone if you already know its
-code. If you don't know the code, you can instead go through the BCountry class
-which can enumerate all timezones in a country, or use the BLocaleRoster, which
-knows the timezone selected by the user.
-*/
-
-/*!
-\fn const BString& BTimeZone::Code() const
-\brief Returns the timezone code.
-
-Note different time zones with different codes may have the same rules.
-*/
-
-/*!
-\fn const BString& BTimeZone::Name() const
-\brief Returns the localized name of the time zone
-
-Use this for displaying information to the user.
-*/
-
-/*!
-\fn const BString& BTimeZone::DaylightSavingName() const
-\brief Return the name of the daylight savings rules used in this timezone.
-*/
-
-/*!
-\fn const BString& BTimeZone::ShortName() const
-\brief Return the short name of the timezone, in the user's locale.
-*/
-
-/*!
-\fn const BString& BTimeZone::DaylightSavingName() const
-\brief Return the short name of the daylight savings rules used in this
-timezone.
-*/
-
-/*!
-\fn int BTimeZone::OffsetFromGMT() const
-\brief Return the offset from GMT.
-
-The offset is a number of seconds, positive or negative.
-*/
-
-/*!
-\fn bool BTimeZone::SupportsDaylightSaving() const
-\brief Return true if the time zone has daylight saving rules
-*/
-
-/*!
-\fn status_t BTimeZone::InitCheck() const
-\brief Return false if there was an error creating the timezone (you called the
-constructor or SetTo with an invalid code).
-*/
-
-/*!
-\fn status_t BTimeZone::SetTo(const char* zoneCode)
-\brief Set the timezone to another code.
-
-\returns false if there was an error (likely you given an invalid code)
-*/
-

docs/user/locale/TimeZone.dox

@@ -0,0 +1,110 @@
+/*
+ * Copyright 2011, Haiku inc.
+ * Distributed under the terms of the MIT Licence.
+ *
+ * Documentation by:
+ *		Adrien Destugues <[email protected]>
+ *		John Scipione <[email protected]>
+ *		Oliver Tappe <[email protected]>
+ * Corresponds to:
+ *		/trunk/headers/os/locale/TimeZone.h	 rev 42274
+ *		/trunk/src/kits/locale/TimeZone.cpp	 rev 42274
+ */
+
+
+/*!
+	\file TimeZone.h
+	\brief Provides for the BTimeZone class.
+*/
+
+
+/*!
+	\class BTimeZone
+	\ingroup locale
+	\brief Provides information about time zones.
+*/
+
+
+/*!
+	\fn BTimeZone::BTimeZone(const char* zoneID, const BLanguage* language)
+	\brief Construct a timezone from its \a zoneID and \a language.
+
+	The constructor only allows you to construct a timezone if you already
+	know its code. If you don't know the code, you can instead go through the
+	BCountry class which can enumerate all timezones in a country, or use the
+	BLocaleRoster, which knows the timezone selected by the user.
+*/
+
+
+/*!
+	\fn BTimeZone::BTimeZone(const BTimeZone& other)
+*/
+
+
+/*!
+	\fn BTimeZone& BTimeZone::operator=(const BTimeZone& source)
+*/
+
+
+/*!
+	\fn const BString& BTimeZone::ID() const
+	\brief Returns the ID of the time zone.
+*/
+
+
+/*!
+	\fn const BString& BTimeZone::Name() const
+	\brief Returns the localized name of the time zone.
+
+	Use this method to display the time zone's name to the user.
+*/
+
+
+/*!
+	\fn const BString& BTimeZone::DaylightSavingName() const
+	\brief Returns the name of the daylight savings rules used in this timezone.
+*/
+
+
+/*!
+	\fn const BString& BTimeZone::ShortName() const
+	\brief Returns the short name of the timezone, in the user's locale.
+*/
+
+
+/*!
+	\fn const BString& BTimeZone::ShortDaylightSavingName() const
+	\brief Returns the short name of the daylight savings rules used in this
+		timezone.
+*/
+
+
+/*!
+	\fn int BTimeZone::OffsetFromGMT() const
+	\brief Return the offset from GMT.
+
+	The offset is a number of seconds, positive or negative.
+*/
+
+
+/*!
+	\fn bool BTimeZone::SupportsDaylightSaving() const
+	\brief Return true if the time zone has daylight saving rules
+*/
+
+
+/*!
+	\fn status_t BTimeZone::InitCheck() const
+	\brief Return \c false if there was an error creating the timezone
+		for instance if you called the constructor or SetTo() with an invalid
+		timezone code.)
+*/
+
+
+/*!
+	\fn status_t BTimeZone::SetTo(const char* zoneCode)
+	\brief Set the timezone to another code.
+
+	\returns \c false if there was an error (likely due to an invalid
+		timezone code.)
+*/

docs/user/locale/UnicodeChar.dox

@@ -1,167 +1,245 @@
+/*
+ * Copyright 2011, Haiku, Inc. All Rights Reserved.
+ * Distributed under the terms of the OpenBeOS License.
+ *
+ * Authors:
+ *		Axel Dörfler <[email protected]>
+ *		John Scipione <[email protected]>
+ * 
+ * Corresponds to:
+ *		/trunk/headers/os/locale/UnicodeChar.h	 rev 42274
+ *		/trunk/src/kits/locale/UnicodeChar.cpp	 rev 42274
+ */
+
 /*!
-\class BUnicodeChar
+	\class BUnicodeChar
-\ingroup locale
+	\ingroup locale
 
-\brief Management of all information about characters.
+	\brief Management of all information about characters.
 
-This class provide a set of tools for managing the whole set of characters
+	This class provide a set of tools for managing the whole set of characters
-defined in unicode. This include informations such as knowing if the character is
+	defined by unicode. This include information about special sets of
-whitespace, if it is alphanumeric, or solething else ; what is the uppercase
+	characters such as if the character is whitespace, or alphanumeric. It also
-equivalent of a character ; or wether it can be ornamented with accents.
+	provides the uppercase equivalent of a character and determines whether a
+	character can be ornamented with accents.
 
-This class consists entirely of static methods, which means you don't have to
+	This class consists entirely of static methods, so you do not have to
-instanciate it. Just call one of the methods with the char you want examinated.
+	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 most usual
-way to handle characters, but it is the faster. To convert an utf-8 string to an
-utf-32 character, pass it to the FromUTF8 function.
 
+	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.
 */
 
 /*!
-\fn static bool BUnicodeChar::IsAlpha(uint32 c)
+	\fn static bool BUnicodeChar::IsAlpha(uint32 c)
-\brief Tell if the character is alphabetic.
+	\brief Determine if \a c is alphabetic.
+
+	\returns \c true if the specified unicode character is an
+		alphabetic character.
 */
 
 /*!
-\fn static bool BUnicodeChar::IsAlNum(uint32 c)
+	\fn static bool BUnicodeChar::IsAlNum(uint32 c)
-\brief Tell if the character is alphanumeric.
+	\brief Determine if \a c is alphanumeric.
+
+	\returns \c true if the specified unicode character is a
+		alphabetic or numeric character.
 */
 
 /*!
-\fn static bool BUnicodeChar::IsDigit(uint32 c)
+	\fn static bool BUnicodeChar::IsDigit(uint32 c)
-\brief Tell if the caracter is numeric.
+	\brief Determine if \a c is numeric.
+
+	\returns \c true if the specified unicode character is a
+		number character.
 */
 
 /*!
-\fn static bool BUnicodeChar::IsHexDigit(uint32 c)
+	\fn static bool BUnicodeChar::IsHexDigit(uint32 c)
-\brief Tell if the character is numeric in base 16.
+	\brief Determine if \a c is a hexadecimal digit.
+
+	\returns \c true if the specified unicode character is a
+		hexadecimal number character.
 */
 
 /*!
-\fn static bool BUnicodeChar::IsUpper(uint32 c)
+	\fn static bool BUnicodeChar::IsUpper(uint32 c)
-\brief Tell if the character is uppercase.
+	\brief Determine if \a c is uppercase.
+
+	\returns \c true if the specified unicode character is an
+		uppercase character.
 */
 
 /*!
-\fn static bool BUnicodeChar::IsLower(uint32 c)
+	\fn static bool BUnicodeChar::IsLower(uint32 c)
-\brief Tell if the character is lowercase.
+	\brief Determine if \a c is lowercase.
+
+	\returns \c true if the specified unicode character is a
+		lowercase character.
 */
 
 /*!
-\fn static bool BUnicodeChar::IsSpace(uint32 c)
+	\fn static bool BUnicodeChar::IsSpace(uint32 c)
-\brief Tell if the character is space.
+	\brief Determine if \a c is a space.
 
-Unlike IsWhitespace, this function will return true for non-breakable
+	Unlike IsWhitespace() this function will return \c true for non-breakable
-spaces. It is the one to use for determining if the character will render
+	spaces. This method is useful for determining if the character will render
-as an empty space on screen and can be stretched to make the text look
+	as an empty space which can be stretched on-screen.
-nicer.
+
+	\returns \c true if the specified unicode character is some
+		kind of a space character.
+
+	\sa IsWhitespace()
 */
 
 /*!
-\fn static bool BUnicodeChar::IsWhitespace(uint32 c)
+	\fn static bool BUnicodeChar::IsWhitespace(uint32 c)
-\brief Tell if the character is whitespace.
+	\brief Determine if \a c is whitespace.
 
-Unlike IsSpace, this method will return false for non-breakable spaces.
+	This method is essentially the same as IsSpace(), but excludes all
-It is the one to use for selecting where to insert line breaks.
+	non-breakable spaces.
+
+	\returns \c true if the specified unicode character is a whitespace
+		character.
+
+	\sa IsSpace()
 */
 
 /*!
-\fn static bool BUnicodeChar::IsControl(uint32 c)
+	\fn static bool BUnicodeChar::IsControl(uint32 c)
-\brief Tell if the character is a control character.
+	\brief Determine if \a c is a control character.
 
-Example control characters are the non-printable ASCII characters 0 to 0x1F.
+	Example control characters are the non-printable ASCII characters from
+	0x0 to 0x1F.
+
+	\returns \c true if the specified unicode character is a control
+		character.
+
+	\sa IsPrintable()
 */
 
 /*!
-\fn static bool BUnicodeChar::IsPunctuation(uint32 c)
+	\fn static bool BUnicodeChar::IsPunctuation(uint32 c)
-\brief Tell if the character is a punctuation.
+	\brief Determine if \a c is punctuation character.
+
+	\returns \c true if the specified unicode character is a
+		punctuation character.
 */
 
 /*!
-\fn static bool BUnicodeChar::IsPrintable(uint32 c)
+	\fn static bool BUnicodeChar::IsPrintable(uint32 c)
-\brief Tell if the character is printable.
+	\brief Determine if \a c is printable.
+
+	Printable characters are not control characters.
+
+	\returns \c true if the specified unicode character is a printable
+		character.
+
+	\sa IsControl()
 */
 
 /*!
-\fn static bool BUnicodeChar::IsTitle(uint32 c)
+	\fn static bool BUnicodeChar::IsTitle(uint32 c)
-\brief Tell if the character is title case.
+	\brief Determine if \a c is title case.
 
-Title case is usually a smaller version of upercase letters.
+	Title case characters are a smaller version of normal uppercase letters.
+
+	\returns \c true if the specified unicode character is a title case
+		character.
 */
 
 /*!
-\fn static bool BUnicodeChar::IsDefined(uint32 c)
+	\fn static bool BUnicodeChar::IsDefined(uint32 c)
-\brief Tell if the character is defined at all.
+	\brief Determine if \a c is defined.
 
-In unicode, some codes are not valid, or not attributed yet.
+	In unicode some codes are not valid or not attributed yet.
-For these, this method wil lreturn false.
+	For these codes this method will return \c false.
+
+	\returns \c true if the specified unicode character is defined.
 */
 
 /*!
-\fn static bool BUnicodeChar::IsBase(uint32 c)
+	\fn static bool BUnicodeChar::IsBase(uint32 c)
-\brief Tell if the character can be used with a diacritic.
+	\brief Determine if \a c can be used with a diacritic.
+
+	\note IsBase() does not determine if a unicode character is distinct.
+
+	\returns \c true if the specified unicode character is a base
+		form character that can be used with a diacritic.
 */
 
 /*!
-\fn static int8 BUnicodeChar::Type(uint32 c)
+	\fn static int8 BUnicodeChar::Type(uint32 c)
-\brief Returns the type of the character.
+	\brief Gets the type of a character.
 
-Return value is a member of the unicode_char_category enum.
+	\returns A member of the \c unicode_char_category enum.
 */
 
 /*!
-\fn static uint32 ToLower(uint32 c);
+	\fn uint32  BUnicodeChar::ToLower(uint32 c)
-\brief Returns the lowercase version of a character.
+	\brief Transforms \a c to lowercase.
+
+	\returns The lowercase version of the specified unicode character.
 */
 
 /*!
-\fn static uint32 ToUpper(uint32 c);
+	\fn uint32 BUnicodeChar::ToUpper(uint32 c)
-\brief Returns the uppercase version of a character.
+	\brief Transforms \a c to uppercase.
+
+	\returns The uppercase version of the specified unicode character.
 */
 
 /*!
-\fn static uint32 ToTitle(uint32 c);
+	\fn uint32 BUnicodeChar::ToTitle(uint32 c)
-\brief Returns the titlecase version of a character.
+	\brief Transforms \a c to title case.
+
+	\returns The title case version of the specified unicode character.
 */
 
 /*!
-\fn static int32 DigitValue(uint32 c);
+	\fn int32 BUnicodeChar::DigitValue(uint32 c)
-\brief Returns the numeric value of the character.
+	\brief Gets the numeric value \a c.
+
+	\returns The numeric version of the specified unicode character.
 */
 
 /*!
-\fn static void ToUTF8(uint32c, char ù**ou
+	\fn void BUnicodeChar::ToUTF8(uint32 c, char **out)
-\brief Convert a character to utf8 encoding.
+	\brief Transform a character to utf-8 encoding.
+
+	\returns The utf-8 encoding of the specified unicode character.
 */
 
 /*!
-\fn static uint32 FromUTF8(const char** in)
+	\fn uint32 BUnicodeChar::FromUTF8(const char **in)
-\brief Convert an 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.
+	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
+	This function updates the in pointer so that it points on the next
-character for the following call.
+	character for the following call.
+
+	\returns The utf-32 encoded version of \a in.
 */
 
 /*!
-\fn static uint32 FromUTF8(const char* in)
+	\fn size_t BUnicodeChar::UTF8StringLength(const char *str)
-\brief Convert an utfÃ-8 string to an utfÃ-32 character.
+	\brief Counts the characters in the given \c NUL terminated string.
 
-If the string contains multiple characters, only the first one is used.
+	\returns the number of utf-8 characters in the \c NUL terminated string.
-The in pointer is not modified.
+
+	\sa BString::CountChars()
 */
 
 /*!
-\fn static size_t UTF8StringLength(const char* str)
+	\fn size_t BUnicodeChar::UTF8StringLength(const char *str, size_t maxLength)
-\brief This function counts the characters in the given null-terminated string.
+	\brief Counts the characters in the given string up to \a maxLength
+		characters.
 
-\sa BString::CountChars()
+	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
-\fn static size_t UTF8StringLength(const char* str, size_t maxLength)
+		up to \a maxLength characters.
-\brief This function counts the characters in the given string.
-
-The string does not need to be null-terminated if you specify the length.
 */

docs/user/media/Buffer.dox

@@ -0,0 +1,113 @@
+/*
+ * 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
+ *		/trunk/src/kits/media/Buffer.cpp	 rev 42274
+ */
+
+
+/*!
+	\file Buffer.h
+	\brief Defines the buffer_clone_info struct and BBuffer class.
+*/
+
+
+/*!
+	\struct buffer_clone_info
+	\brief A struct that stores where in memory a BBuffer object is in memory
+		as well as the buffer flags.
+*/
+
+
+/*!
+	\class BBuffer
+	\ingroup media
+	\brief A reference to a chunk of memory useful for sharing media data
+		between applications and nodes.
+*/
+
+
+/*!
+	\fn void* BBuffer::Data()
+	\brief Returns a pointer to the data of the buffer.
+*/
+
+
+/*!
+	\fn size_t BBuffer::SizeAvailable()
+	\brief Returns the size of the buffer in bytes. Alias for Size().
+*/
+
+
+/*!
+	\fn size_t BBuffer::SizeUsed()
+	\brief Returns the size of the portion of the buffer that is currently in
+		use 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.
+*/
+
+
+/*!
+	\fn void BBuffer::Recycle()
+	\brief Recycles the buffer so that it can be reused.
+*/
+
+
+/*!
+	\fn buffer_clone_info BBuffer::CloneInfo() const
+	\brief Returns the buffer_clone_info struct that describes the buffer.
+*/
+
+
+/*!
+	\fn media_buffer_id BBuffer::ID()
+	\brief Returns the app_server ID of the buffer.
+*/
+
+
+/*!
+	\fn media_type BBuffer::Type()
+	\brief 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.
+*/
+
+
+/*!
+	\fn media_audio_header* BBuffer::AudioHeader()
+	\brief Returns a pointer to a header of the audio buffer.
+*/
+
+
+/*!
+	\fn media_video_header* BBuffer::VideoHeader()
+	\brief 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().
+*/

docs/user/storage/AppFileInfo.dox

@@ -0,0 +1,769 @@
+/*
+ * Copyright 2011, Haiku inc.
+ * Distributed under the terms of the MIT Licence.
+ *
+ * Documentation by:
+ *		John Scipione <[email protected]>
+ *		Ingo Weinhold <[email protected]>
+ * Corresponds to:
+ *		/trunk/headers/os/storage/AppFileInfo.h	 rev 42274
+ *		/trunk/src/kits/storage/AppFileInfo.cpp	 rev 42274
+ */
+
+
+/*!
+	\file AppFileInfo.h
+	\brief Provides the BAppFileInfo class.
+*/
+
+
+/*!
+	\class BAppFileInfo
+	\ingroup storage
+	\brief Provides access to the metadata associated with executables,
+		   libraries and add-ons.
+
+	The BAppFileInfo class allows for information about an executable or
+	add-on to be accessed or set. Information about an executable that can be
+	accessed include the signature, catalog entry, supported MIME types,
+	application flags, icon(s), and version info.
+
+	You should initialize the BAppFileInfo with a BFile object that represents
+	the executable or add-on that you want to access. If you only want to read
+	metadata from the file you do not have to open it for reading. However, if
+	you also want to write metadata then you should open the BFile for writing.
+
+	To associate a BFile with a BAppFileInfo object you can either pass the
+	BFile object into the constructor or you can use the empty constructor and
+	then use the SetTo() method to set the BFile to the BAppFileInfo object.
+
+	When accessing information from a BFileInfo object it will first look in the
+	attributes of the BFile. If the information is not found then the BFileInfo
+	object will next look at the resource of the BFile. You can tell the
+	BFileInfo object to look only in the attributes or resources with the
+	SetInfoLocation() method.
+*/
+
+
+/*!
+	\fn BAppFileInfo::BAppFileInfo()
+	\brief Creates an uninitialized BAppFileInfo object.
+*/
+
+
+/*!
+	\fn BAppFileInfo::BAppFileInfo(BFile* file)
+	\brief Creates an BAppFileInfo object and initializes it to the supplied
+		file.
+
+	The caller retains ownership of the supplied BFile object. It must not
+	be deleted during the life time of the BAppFileInfo. It is not deleted
+	when the BAppFileInfo is destroyed.
+
+	\param file The BFile object that the BAppFileInfo object shall be
+		initialized to.
+*/
+
+
+/*!
+	\fn BAppFileInfo::~BAppFileInfo()
+	\brief Frees all resources associated with this object.
+
+	The supplied BFile object is not deleted if one is specified.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::SetTo(BFile *file)
+	\brief Initializes the BAppFileInfo to the supplied file.
+
+	The caller retains ownership of the supplied BFile object. It must not
+	be deleted during the life time of the BAppFileInfo. The BFile object
+	is not deleted when the BAppFileInfo is destroyed.
+
+	\param file The BFile object that the BAppFileInfo object shall be
+		initialized to.
+
+	\returns an status code.
+	\retval B_OK Everything went fine.
+	\retval B_BAD_VALUE \c NULL \a file or \a file is not properly initialized.
+*/
+
+
+/*!
+	\name MIME Type
+*/
+
+
+//! @{
+
+
+/*!
+	\fn status_t BAppFileInfo::GetType(char *type) const
+	\brief Gets the MIME type of the associated file.
+
+	\param type A pointer to a pre-allocated character buffer of size
+		   \c B_MIME_TYPE_LENGTH or larger into which the MIME type of the
+		   file will be written.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+	\retval B_BAD_VALUE \c NULL \a type or the type string stored in the
+		attribute/resources is longer than \c B_MIME_TYPE_LENGTH.
+	\retval B_BAD_TYPE The attribute/resources the type string is stored in
+		has the wrong type.
+	\retval B_ENTRY_NOT_FOUND No type is set on the file.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::SetType(const char* type)
+	\brief Sets the MIME type of the associated file.
+
+	If \a type is \c NULL if the file's MIME type is unset.
+
+	\param type The MIME type to be assigned to the file. It must not be
+		longer than \c B_MIME_TYPE_LENGTH (including the terminating null).
+		The MIME type may be \c NULL.
+
+	\returns a status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+	\retval B_BAD_VALUE \a type is longer than \c B_MIME_TYPE_LENGTH.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Signature
+*/
+
+
+//! @{
+
+
+/*!
+	\fn status_t BAppFileInfo::GetSignature(char* signature) const
+	\brief Gets the application signature of the associated file.
+
+	\param signature A pointer to a pre-allocated character buffer of size
+		   \c B_MIME_TYPE_LENGTH or larger into which the application
+		   signature of the file will be written.
+
+	\returns a status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+	\retval B_BAD_VALUE \c NULL \a signature or the signature stored in the
+		attribute/resources is longer than \c B_MIME_TYPE_LENGTH.
+	\retval B_BAD_TYPE The attribute/resources the signature is stored in have
+		the wrong type.
+	\retval B_ENTRY_NOT_FOUND No signature is set on the file.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::SetSignature(const char* signature)
+	\brief Sets the application signature of the associated file.
+
+	If \a signature is \c NULL the file's application signature is unset.
+
+	\param signature The application signature to be assigned to the file.
+		Must not be longer than \c B_MIME_TYPE_LENGTH (including the
+		terminating \c NUL). The \a signature may be \c NULL.
+
+	\returns a status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+	\retval B_BAD_VALUE \a signature is longer than \c B_MIME_TYPE_LENGTH.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Catalog Entry
+*/
+
+
+//! @{
+
+
+/*!
+	\fn status_t BAppFileInfo::GetCatalogEntry(char *catalogEntry) const
+	\brief Gets the catalog entry of the associated file used for localization.
+
+	\param catalogEntry A pointer to a pre-allocated character buffer of size
+		   \c B_MIME_TYPE_LENGTH * 3 or larger into which the catalog entry
+		   of the file will be written.
+
+	\returns a status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+	\retval B_BAD_VALUE \c NULL \a catalogEntry or the entry stored in the
+		attribute/resources is longer than \c B_MIME_TYPE_LENGTH * 3.
+	\retval B_BAD_TYPE The attribute/resources the entry is stored in have
+		the wrong type.
+	\retval B_ENTRY_NOT_FOUND No catalog entry is set on the file.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::SetCatalogEntry(const char* catalogEntry)
+	\brief Sets the catalog entry of the associated file used for localization.
+
+	If \a catalogEntry is \c NULL the file's catalog entry is unset.
+
+	\param catalogEntry The catalog entry to be assigned to the file.
+		Of the form "x-vnd.Haiku-app:context:name". Must not be longer than
+		\c B_MIME_TYPE_LENGTH * 3 (including the terminating \c NUL).
+		The \a catalogEntry may be \c NULL.
+
+	\returns a status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+	\retval B_BAD_VALUE \a catalogEntry is longer than
+		\c B_MIME_TYPE_LENGTH * 3.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Application Flags
+*/
+
+
+//! @{
+
+
+/*!
+	\fn status_t BAppFileInfo::GetAppFlags(uint32* flags) const
+	\brief Gets the application \a flags of the associated file.
+
+	\param flags A pointer to a pre-allocated \c uint32 into which the
+		application flags of the file are written.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+	\retval B_BAD_VALUE \c NULL \a flags.
+	\retval B_BAD_TYPE The attribute/resources the flags are stored in have
+		the wrong type.
+	\retval B_ENTRY_NOT_FOUND No application flags are set on the file.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::SetAppFlags(uint32 flags)
+	\brief Sets the application \a flags of the associated file.
+
+	\param flags The application \a flags to be assigned to the file.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object was not properly initialized.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::RemoveAppFlags()
+	\brief Removes the application flags from the associated file.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object was not properly initialized.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Supported MIME Types
+*/
+
+
+//! @{
+
+
+/*!
+	\fn status_t BAppFileInfo::GetSupportedTypes(BMessage* types) const
+	\brief Gets the MIME types supported by the application.
+
+	The supported MIME types are added to a field "types" of type
+	\c B_STRING_TYPE in \a types.
+
+	\param types A pointer to a pre-allocated BMessage into which the
+		MIME types supported by the application will be written.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+	\retval B_BAD_VALUE \c NULL \a types.
+	\retval B_BAD_TYPE The attribute/resources that the supported types
+		are stored in have the wrong type.
+	\retval B_ENTRY_NOT_FOUND No supported types are set on the file.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::SetSupportedTypes(const BMessage* types,
+		bool syncAll)
+	\brief Sets the MIME types that are supported by the application and allows
+		you to specify whether or not the no longer supported types shall be
+		updated as well.
+
+	If \a types is \c NULL then the application's supported types are unset.
+
+	The supported MIME types must be stored in a field "types" of type
+	\c B_STRING_TYPE in \a types.
+
+	The method informs the registrar about this news.
+	For each supported type the result of BMimeType::GetSupportingApps()
+	will afterwards include the signature of this application. That is,
+	the application file needs to have a signature set.
+
+	\a syncAll specifies whether the no longer supported types shall be
+	updated as well, i.e. whether or not this application shall be removed
+	from the list of supporting applications.
+
+	\param types The supported types to be assigned to the file.
+		May be \c NULL.
+	\param syncAll \c true to also synchronize the no-longer supported
+		types, \c false otherwise.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::SetSupportedTypes(const BMessage* types)
+	\brief Sets the MIME types supported by the application.
+
+	This method is a short-hand for SetSupportedTypes(types, false).
+	\see SetSupportedType(const BMessage*, bool) for detailed information.
+
+	\param types The supported types to be assigned to the file.
+		May be \c NULL.
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+*/
+
+
+/*!
+	\fn bool BAppFileInfo::IsSupportedType(const char* type) const
+	\brief Returns whether the application supports the supplied MIME type.
+
+	If the application supports the wildcard type "application/octet-stream"
+	then this method returns \c true for any MIME type.
+
+	\param type The MIME type in question.
+
+	\returns \c true if \a type is a valid MIME type and it is supported by
+		the application, \c false otherwise.
+*/
+
+
+/*!
+	\fn bool BAppFileInfo::Supports(BMimeType* type) const
+	\brief Returns whether the application supports the supplied MIME type
+		explicitly.
+
+	Unlike IsSupportedType(), this method returns \c true, only if the type
+	is explicitly supported, regardless of whether it supports
+	"application/octet-stream".
+
+	\param type The MIME type in question.
+
+	\returns \c true if \a type is a valid MIME type and it is explicitly
+		supported by the application, \c false otherwise.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Application Icon
+*/
+
+
+//! @{
+
+
+/*!
+	\fn status_t BAppFileInfo::GetIcon(BBitmap* icon, icon_size which) const
+	\brief Gets the icon of the associated file and puts it into a pre-allocated
+		   BBitmap.
+
+	\param icon A pointer to a pre-allocated BBitmap of the correct dimension
+		to store the requested icon (16x16 for the \c B_MINI_ICON and 32x32
+		for the \c B_LARGE_ICON).
+	\param which Specifies the size of the icon to be retrieved:
+		\c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon.
+		For HVIF icons this parameter has no effect.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+	\retval B_BAD_VALUE \c NULL \a icon, unsupported icon size \a which or
+		bitmap dimensions (\a icon) and icon size (\a which) do not match.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::GetIcon(uint8** data, size_t* size) const
+	\brief Gets the icon of the associated file and puts it into a buffer.
+
+	\param data The pointer in which the flat icon data will be returned.
+	\param size The pointer in which the size of the data found will be
+		returned.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+	\retval B_BAD_VALUE \c NULL \a data or \c NULL size.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::SetIcon(const BBitmap* icon, icon_size which)
+	\brief Sets the icon of the associated file from a BBitmap.
+
+	If \a icon is \c NULL then the icon of the file is unset.
+
+	\param icon A pointer to the BBitmap containing the icon to be set.
+		May be \c NULL to specify no icon.
+	\param which Specifies the size of the icon to be set: \c B_MINI_ICON for
+		16x16 mini icon and \c B_LARGE_ICON for the 32x32 large icon.
+		For HVIF icons this parameter has no effect.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+	\retval B_BAD_VALUE Unknown icon size \a which or bitmap dimensions
+		(\a icon) and icon size (\a which) do not match.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::SetIcon(const uint8* data, size_t size)
+	\brief Sets the icon of the associated file from a buffer.
+
+	If \a data is \c NULL then the icon of the file is unset.
+
+	\param data A pointer to the data buffer containing the vector icon
+		   to be set. May be \c NULL.
+	\param size Specifies the size of buffer pointed to by \a data.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+	\retval B_BAD_VALUE \c NULL data.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::GetIconForType(const char* type, BBitmap* icon,
+		icon_size size) const
+	\brief Gets the icon the application provides for a given MIME type and
+		puts it into a BBitmap.
+
+	\note If \a type is \c NULL, the application's icon is retrieved.
+
+	\param type The MIME type in question. May be \c NULL.
+	\param icon A pointer to a pre-allocated BBitmap of the correct dimension
+		to store the requested icon (16x16 for the mini and 32x32 for the
+		large icon).
+	\param size Specifies the size of the icon to be retrieved:
+		\c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+	\retval B_BAD_VALUE \c NULL \a icon, unsupported icon size
+		\a which or bitmap dimensions (\a icon) and icon size (\a which) do
+		not match.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::GetIconForType(const char* type, uint8** data,
+		size_t* size) const
+	\brief Gets the icon the application provides for a given MIME type and
+		puts it into a buffer.
+
+	\note If \a type is set to \c NULL the the application's icon is retrieved.
+
+	\param type The MIME type in question. May be \c NULL.
+	\param data A pointer in which the icon data will be returned. When you
+	are done with the data, you should use free() to deallocate it.
+	\param size A pointer in which the size of the retrieved data is returned.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+	\retval B_BAD_VALUE \c NULL \a data and/or \a size. Or the supplied
+		\a type is not a valid MIME type.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::SetIconForType(const char* type,
+		const BBitmap* icon, icon_size which)
+	\brief Sets the icon the application provides for a given MIME type from a
+		BBitmap.
+
+	\note If \a type is \c NULL then the icon is set.
+	\note If \a icon is \c NULL then the icon is unset.
+
+	If the file has a signature, then the icon is also set on the MIME type.
+	If the type for the signature has not been installed yet, it is installed
+	before.
+
+	\param type The MIME type in question. May be \c NULL.
+	\param icon A pointer to the BBitmap containing the icon to be set.
+		May be \c NULL.
+	\param which Specifies the size of the icon to be set: \c B_MINI_ICON
+		for the mini and \c B_LARGE_ICON for the large icon.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+	\retval B_BAD_VALUE Either the icon size \a which is unknown,
+		the bitmap dimensions (\a icon) and icon size (\a which) do not
+		match, or the provided \a type is not a valid MIME type. 
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::SetIconForType(const char* type,
+		const uint8* data, size_t size)
+	\brief Sets the icon the application provides for a given MIME type from a
+		buffer.
+
+	\note If \a type is \c NULL then the icon is set.
+	\note If \a data is \c NULL then the icon is unset.
+
+	If the file has a signature, then the icon is also set on the MIME type.
+	If the type for the signature has not been installed yet, it is
+	installed before.
+
+	\param type The MIME type in question. May be \c NULL.
+	\param data A pointer to the data containing the icon to be set.
+		   May be \c NULL.
+	\param size Specifies the size of buffer provided in \a data.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+	\retval B_BAD_VALUE The provided \a type is not a valid MIME type.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Version Info
+*/
+
+
+//! @{
+
+
+/*!
+	\fn status_t BAppFileInfo::GetVersionInfo(version_info* info,
+		version_kind kind) const
+	\brief Gets the version info of the associated file.
+
+	\param info A pointer to a pre-allocated version_info structure into
+		which the version info should be written.
+	\param kind Specifies the kind of the version info to be retrieved:
+		- \c B_APP_VERSION_KIND for the application's version info and
+		- \c B_SYSTEM_VERSION_KIND for the suite's info the application
+			 belongs to.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+	\retval B_BAD_VALUE \c NULL \a info.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::SetVersionInfo(const version_info* info,
+		version_kind kind)
+	\brief Sets the version info of the associated file.
+
+	\note If \a info is set to \c NULL then the file's version info is unset.
+
+	\param info The version info to be set. May be \c NULL.
+	\param kind Specifies kind of version info to be set:
+		- \c B_APP_VERSION_KIND for the application's version info and
+		- \c B_SYSTEM_VERSION_KIND for the suite's info the application
+			 belongs to.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT The object is not properly initialized.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Attributes/Resources
+*/
+
+
+//! @{
+
+
+/*!
+	\fn void BAppFileInfo::SetInfoLocation(info_location location)
+	\brief Specifies the location where the metadata shall be stored.
+
+	The options for \a location are:
+		- \c B_USE_ATTRIBUTES: Store the data in the attributes.
+		- \c B_USE_RESOURCES: Store the data in the resources.
+		- \c B_USE_BOTH_LOCATIONS: Store the data in attributes and resources.
+
+	\param location The location where the metadata shall be stored.
+*/
+
+
+/*!
+	\fn bool BAppFileInfo::IsUsingAttributes() const
+	\brief Returns whether the object (also) stores the metadata in the
+		   attributes of the associated file.
+
+	\returns \c true if the metadata are (also) stored in the file's
+		attributes, \c false otherwise.
+*/
+
+
+/*!
+	\fn bool BAppFileInfo::IsUsingResources() const
+	\brief Returns whether the object (also) stores the metadata in the
+		   resources of the associated file.
+
+	\returns \c true if the metadata are (also) stored in the file's
+		resources, \c false otherwise.
+*/
+
+
+//! @}
+
+
+/*!
+	\fn BAppFileInfo & BAppFileInfo::operator=(const BAppFileInfo &)
+	\brief Privatized assignment operator to prevent usage.
+*/
+
+
+/*!
+	\fn BAppFileInfo::BAppFileInfo(const BAppFileInfo &)
+	\brief Privatized copy constructor to prevent usage.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::GetMetaMime(BMimeType* meta) const
+	\brief Initializes a BMimeType to the signature of the associated file.
+
+	\warning The parameter \a meta is not checked.
+
+	\param meta A pointer to a pre-allocated BMimeType that shall be
+		   initialized to the signature of the associated file.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_BAD_VALUE \c NULL \a meta
+	\retval B_ENTRY_NOT_FOUND The file has not signature or the signature is
+			(not installed in the MIME database.) no valid MIME string.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::_ReadData(const char* name, int32 id,
+		type_code type, void* buffer, size_t bufferSize,
+		size_t &bytesRead, void** allocatedBuffer) const
+	\brief Reads data from an attribute or resource.
+
+	\note The data is read from the location specified by \a fWhere.
+
+	\warning The object must be properly initialized. The parameters are
+		\b NOT checked.
+
+	\param name The name of the attribute/resource to be read.
+	\param id The resource ID of the resource to be read. It is ignored
+		   when < 0.
+	\param type The type of the attribute/resource to be read.
+	\param buffer A pre-allocated buffer for the data to be read.
+	\param bufferSize The size of the supplied buffer.
+	\param bytesRead A reference parameter, set to the number of bytes
+		   actually read.
+	\param allocatedBuffer If not \c NULL, the method allocates a buffer
+		   large enough too store the whole data and writes a pointer to it
+		   into this variable. If \c NULL, the supplied buffer is used.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_ENTRY_NOT_FOUND The entry was not found.
+	\retval B_NO_MEMORY Ran out of memory allocating the buffer.
+	\retval B_BAD_VALUE \a type did not match.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::_WriteData(const char* name, int32 id,
+		type_code type, const void* buffer, size_t bufferSize, bool findID)
+	\brief Writes data to an attribute or resource.
+
+	\note The data is written to the location(s) specified by \a fWhere.
+
+	\warning The object must be properly initialized. The parameters are
+		\b NOT checked.
+
+	\param name The name of the attribute/resource to be written.
+	\param id The resource ID of the resource to be written.
+	\param type The type of the attribute/resource to be written.
+	\param buffer A buffer containing the data to be written.
+	\param bufferSize The size of the supplied buffer.
+	\param findID If set to \c true use the ID that is already assigned to the
+		   \a name / \a type pair or take the first unused ID >= \a id.
+		   If \c false, \a id is used.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_ERROR An error occurred while trying to write the data.
+*/
+
+
+/*!
+	\fn status_t BAppFileInfo::_RemoveData(const char* name, type_code type)
+	\brief Removes an attribute or resource.
+
+	\note The removal location is specified by \a fWhere.
+
+	\warning The object must be properly initialized. The parameters are
+		\b NOT checked.
+
+	\param name The name of the attribute/resource to be remove.
+	\param type The type of the attribute/resource to be removed.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_INIT Not using attributes and not using resources.
+	\retval B_ENTRY_NOT_FOUND The attribute or resource was not found.
+*/

docs/user/support/Archivable.dox

@@ -16,15 +16,13 @@
  */
 
 
-/*!
+/*!	\file Archivable.h
-	\file Archivable.h
 	\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.
@@ -65,8 +63,7 @@
 */
 
 
-/*!
+/*!	\fn BArchivable::BArchivable(BMessage* from)
-	\fn BArchivable::BArchivable(BMessage* from)
 	\brief Constructor. Does important behind-the-scenes work in the unarchiving
 		process.
 	
@@ -77,20 +74,17 @@
 */
 
 
-/*!
+/*!	\fn BArchivable::BArchivable()
-	\fn BArchivable::BArchivable()
 	\brief Constructor. Does nothing.
 */
 
 
-/*!
+/*!	\fn BArchivable::~BArchivable()
-	\fn BArchivable::~BArchivable()
 	\brief Destructor. Does nothing.
 */
 
 
-/*!
+/*!	\fn virtual status_t BArchivable::Archive(BMessage* into,
-	\fn virtual status_t BArchivable::Archive(BMessage* into,
 		 bool deep = true) const
 	\brief Archive the object into a BMessage.
 	
@@ -105,8 +99,7 @@
 */
 
 
-/*!
+/*!	\fn static BArchivable* BArchivable::Instantiate(BMessage* archive)
-	\fn static BArchivable* BArchivable::Instantiate(BMessage* archive)
 	\brief Static member to restore objects from messages.
 	
 	You should always check that the \a archive argument actually corresponds to
@@ -127,17 +120,15 @@
 */
 
 
-/*!
+/*!	\fn virtual status_t BArchivable::Perform(perform_code d, void* arg)
-	\fn virtual status_t BArchivable::Perform(perform_code d, void* arg)
+	\brief Internal method defined for binary compatibility purposes.
-	\brief Internal method.
 	\internal This method is defined for binary compatibility purposes, it is
 		used to ensure that the correct AllUnarchived() and AllArchived()
 		methods are called for objects, as those methods are new to Haiku.
 */
 
 
-/*!
+/*!	\fn virtual status_t BArchivable::AllUnarchived(const BMessage* archive)
-	\fn virtual	status_t BArchivable::AllUnarchived(const BMessage* archive)
 	\brief Method relating to the use of \c BUnarchiver.
 
 	This hook function is called triggered in the BUnarchiver::Finish() method.
@@ -146,32 +137,31 @@
 	Implementations of this method should call the implementation of
 	their parent class, the same as for the Archive() method.
 
-	\note To guarantee that your AllUnarchived() method will be called during
+	\warning To guarantee that your AllUnarchived() method will be called
-		unarchival, you must create a BUnarchiver object in your archive
+		during unarchival, you must create a BUnarchiver object in your
-		constructor.
+		archive constructor.
 
 	\see BUnarchiver, BUnarchiver::Finish()
 */
 
 
-/*!
+/*! \fn virtual status_t BArchivable::AllArchived(BMessage* into) const
-	\fn virtual status_t BArchivable::AllArchived(BMessage* into) const
 	\brief Method relating to the use of \c BArchiver.
 
 	This hook function is called once the first BArchiver that was created in
-	an archiving session is either destroyed, or has its \c Finish() method
+	an archiving session is either destroyed, or has its Finish() method
 	called. Implementations of this method can be used, in conjunction with
 	BArchiver::IsArchived(), to reference objects in your archive that you
 	do not own, depending on whether or not those objects were archived by their
 	owners. Implementations of this method should call the implementation of
 	their parent class, the same as for the Archive() method.
 
-	\note To guarantee that your AllArchived() method will be called during
+	\warning To guarantee that your AllArchived() method will be called
-		archival, you must create a BArchiver object in your Archive()
+		during archival, you must create a BArchiver object in your
-		implementation.
+		Archive() implementation.
 
-	\note You should archive any objects you own in your Archive() method 
+	\warning You should archive any objects you own in your Archive()
-		implementation, \b NOT your AllArchived() method.
+		method implementation, and \b NOT your AllArchived() method.
 
 	\see BArchiver BArchiver::Finish()
 */
@@ -184,15 +174,13 @@
 */
 
 
-/*!
+/*!	\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.
 */
 
 
-/*!
+/*!	\fn BArchivable* instantiate_object(BMessage *from, image_id *id)
-	\fn BArchivable* instantiate_object(BMessage *from, image_id *id)
 	\brief Instantiate an archived object with the object being defined in a
 		different application or library.
 	
@@ -206,8 +194,7 @@
 */
 
 
-/*!
+/*!	\fn BArchivable* instantiate_object(BMessage *from)
-	\fn BArchivable* instantiate_object(BMessage *from)
 	\brief Instantiate an archived object.
 	
 	This global function will determine the base class, based on the \a from
@@ -222,30 +209,26 @@
 */
 
 
-/*!
+/*!	\fn bool validate_instantiation(BMessage* from, const char* className)
-	\fn bool validate_instantiation(BMessage* from, const char* className)
 	\brief Internal function that checks if the \a className is the same as the
 		one stored in the \a from message.
 */
 
 
-/*!
+/*!	\fn instantiation_func find_instantiation_func(const char* className,
-	\fn instantiation_func find_instantiation_func(const char* className,
 		const char* signature)
 	\brief Internal function that searches for the instantiation func with a
 		specific signature. Use instantiate_object() instead.
 */
 
 
-/*!
+/*!	\fn instantiation_func find_instantiation_func(const char* className)
-	\fn instantiation_func find_instantiation_func(const char* className)
 	\brief Internal function that searches for the instantiation func of a
 		specific class. Use instantiate_object() instead.
 */
 
 
-/*!
+/*!	\fn instantiation_func find_instantiation_func(BMessage* archive)
-	\fn instantiation_func find_instantiation_func(BMessage* archive)
 	\brief Internal function that searches for the instantiation func that
 		works on the specified \a archive. Use instantiate_object() instead.
 */

docs/user/support/Beep.dox

@@ -13,7 +13,7 @@
  ///// and not completely implemented, so this needs revision if everything
  ///// is finished.
  
- /*!
+/*!
   \file Beep.h
   \brief Functions to generate sounds from the computer.
 */
@@ -24,34 +24,31 @@
 
 //! @{
 
-/*!
+/*!	\fn status_t beep()
-  \fn status_t beep()
+	\brief Invoke the standard system beep to alert users.
-  \brief Invoke the standard system beep to alert users.
 
-  From Beep.h and in libbe.so.
+	From Beep.h and in libbe.so.
-  
+
-  \see system_beep() and add_system_beep_event()
+	\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.
-  \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.
+	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.
-  \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.
+	Call this method to add a specific event to the media server.
-  
+
-  \param eventName The name of the event.
+	From Beep.h and in libbe.so.
-  \param flags Currently unused. Pass \c 0.
+
+	\param eventName The name of the event.
+	\param flags Currently unused. Pass \c 0.
 */
 
-//! @}
+//! @}

docs/user/support/List.dox

@@ -26,7 +26,7 @@
 	\class BList
 	\ingroup support
 	\ingroup libbe
-	\brief An ordered container that is designed to hold generic \c void * 
+	\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
@@ -399,7 +399,7 @@ A C D E F G B H I J
 	If one of the actions on the items fails it means that the \a func function
 	returned \c false and the processing of the list will be stopped.
 	
-	\param func A function that takes a \c void * argument and returns a
+	\param func A function that takes a \c void* argument and returns a
 		boolean.
 	\see DoForEach(bool (*func)(void* item, void* arg2), void *arg2)
 */
@@ -412,8 +412,8 @@ A C D E F G B H I J
 	If one of the actions on the items fails it means that the \a func function
 	returned \c false and the processing of the list will be stopped.
 	
-	\param func A function with the first \c void * argument being the item
+	\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
+		and the second \c void* being the argument that you supply. It should
 		return a boolean value on whether it succeeded or not.
 	\param arg2 An argument to supply to \a func.
 	\see DoForEach(bool (*func)(void* item))

docs/user/support/SupportDefs.dox

@@ -21,7 +21,7 @@
 //! @{
 
 /*!
-  \typedef	typedef __haiku_int8			int8
+	\typedef typedef __haiku_int8			int8
 */
 
 /*!
@@ -29,7 +29,7 @@
 */
 
 /*!
-	\typedef	typedef __haiku_int16			int16
+	\typedef typedef __haiku_int16			int16
 */
 
 /*!
@@ -37,7 +37,7 @@
 */
 
 /*!
-	\typedef	typedef __haiku_int32			int32
+	\typedef typedef __haiku_int32			int32
 */
 
 /*!
@@ -45,7 +45,7 @@
 */
 
 /*!
-	\typedef	typedef __haiku_int64			int64
+	\typedef typedef __haiku_int64			int64
 */
 
 /*!
@@ -137,9 +137,7 @@
 //! @}
 
 
-/*!
+/*!	\name Character Type Formats */
-  \name Character Type Formats
-*/
 
 //! @{
 
@@ -153,20 +151,18 @@
 
 //! @}
 
-/*!
+/*!	\name Descriptive Type Formats */
-  \name Descriptive Type Formats
-*/
 
 //! @{
 
 /*!
-  \typedef typedef int32					status_t
+	\typedef typedef int32					status_t
-  \brief Represents one of the status codes defined in Error.h
+	\brief Represents one of the status codes defined in Error.h
 */
 
 /*!
-  \typedef typedef int64					bigtime_t
+	\typedef typedef int64					bigtime_t
-  \brief Represents time. The unit depends on the context of the function.
+	\brief Represents time. The unit depends on the context of the function.
 */
 
 /*!
@@ -175,23 +171,21 @@
 */
 
 /*!
-  \typedef typedef uint32					type_code
+	\typedef typedef uint32					type_code
-  \brief Represents a certain type of data. See TypeConstants.h for possible
+	\brief Represents a certain type of data. See TypeConstants.h for
-    values.
+		possible values.
 */
 
 /*!
-  \typedef typedef uint32					perform_code
+	\typedef typedef uint32					perform_code
-  \brief Unused. Defined by Be to support 'hidden' commands or
+	\brief Unused. Defined by Be to support 'hidden' commands or
-    extensions to classes. The Haiku API has none of these.
+		extensions to classes. The Haiku API has none of these.
 */
   
 //! @}
  
 
-/*!
+/*!	\name Format strings for printf()/scanf() */
-	\name Format strings for printf()/scanf()
-*/
 
 //! @{
 
@@ -374,9 +368,7 @@
 //! @}
 
 
-/*!
+/*!	\name  Format strings for several standard types */
-	\name  Format strings for several standard types
-*/
 
 //! @{
 
@@ -474,41 +466,35 @@
 
 //////////////// Odds and ends
   
-/*!
+/*!	\var const char *B_EMPTY_STRING
-  \var const char *B_EMPTY_STRING
+	\brief Defines an empty string. Currently defined as the string "".
-  \brief Defines an empty string. Currently defined as the C-string "".
 */
 
-/*!
+/*!	\def min_c(a,b)
-  \def min_c(a,b)
+	\brief Returns the minimum of the values a and b.
-  \brief Returns the minimum of the values a and b.
 
-  \note When including this header in a C file, use the C equivalent called 
+	\note When including this header in a C file, use the C equivalent called 
-    \c min(a,b).
+		\c min(a,b).
 */
 
-/*!
+/*!	\def max_c(a,b)
-  \def max_c(a,b)
+	\brief Returns the maximum of values a and b.
-  \brief Returns the maximum of values a and b.
 
-  \note When including this header in a C file, use the C equivalent called 
+	\note When including this header in a C file, use the C equivalent called 
-    \c max(a,b).
+		\c max(a,b).
 */
 
-/*!
+/*!	\def NULL
-  \def NULL
+	\brief Defines the constant \c NULL if it hasn't been defined
-  \brief Defines the constant \c NULL if it hasn't been defined anywhere before. 
+		anywhere before. 
 */
 
-/*!
+/*!	\addtogroup support_globals */
-  \addtogroup support_globals
-*/
 
 //! @{
 
-/*!
+/*!	\fn int32 atomic_set(vint32 *value, int32 newValue)
-  \fn int32	atomic_set(vint32 *value, int32 newValue)
+	\brief Atomically set the variable \a value to \a newvalue.
-  \brief Atomically set the variable \a value to \a newvalue.
   
 	This is a thread-safe way of performing the \c *value \c = \c newValue
 	operation. You should use these function when two or more threads might
@@ -518,29 +504,28 @@
 	\return The original value of \c value.	
 	
 	\sa atomic_set64() for a version that works on \c long \c long
-  \sa atomic_test_and_set(), atomic_add(), atomic_and(),
+	\sa atomic_test_and_set(), atomic_add(), atomic_and(), atomic_or(),
-    atomic_or(), atomic_get()
+		atomic_get()
 */
 
-/*!
+/*!	\fn int32 atomic_test_and_set(vint32 *value, int32 newValue,
-  \fn int32	atomic_test_and_set(vint32 *value, int32 newValue, int32 testAgainst)
+		int32 testAgainst)
-  \brief Atomically set the variable \a value to \a newValue if the current
+	\brief Atomically set the variable \a value to \a newValue if the current
          value is \a testAgainst.
   
 	This is a thread-safe way of conditionally performing the \c *value \c += 
-	\c newValue operation. You should use these function when two or more threads
+	\c newValue operation. You should use these function when two or more
-	might access the variable simultaneously. You don't have to use a semaphore
+	threads might access the variable simultaneously. You don't have to use
-	or a mutex in this case. 
+	a semaphore or a mutex in this case. 
 	
 	\return The original value of \c value.
-  \sa atomic_test_and_set64() for a version that works on \c long \c long
+
-  \sa atomic_set(), atomic_add(), atomic_and(),
+	\sa atomic_test_and_set64() for a version that works on \c long \c long
-    atomic_or(), atomic_get()
+	\sa atomic_set(), atomic_add(), atomic_and(), atomic_or(), atomic_get()
 */
 
-/*!
+/*!	\fn int32 atomic_add(vint32 *value, int32 addValue)
-  \fn int32	atomic_add(vint32 *value, int32 addValue)
+	\brief Atomically add the value of \a addValue to \a value.
-  \brief Atomically add the value of \a addValue to \a value.
   
 	This is a thread-safe way of performing the \c *value \c += \c addValue
 	operation. You should use these function when two or more threads might
@@ -548,14 +533,14 @@
 	mutex in this case. 
 	
 	\return The original value of \c value.
-  \sa atomic_add64() for a version that works on \c long \c long
+
-  \sa atomic_set(), atomic_test_and_set(), atomic_and(),
+	\sa atomic_add64() for a version that works on \c long \c long
-    atomic_or(), atomic_get()
+	\sa atomic_set(), atomic_test_and_set(), atomic_and(), atomic_or(),	
+		atomic_get()
 */
 
-/*!
+/*!	\fn int32 atomic_and(vint32 *value, int32 andValue)
-  \fn int32	atomic_and(vint32 *value, int32 andValue)
+	\brief Atomically perform a bitwise AND operation of \a andValue to the 
-  \brief Atomically perform a bitwise AND operation of \a andValue to the 
          variable \a andValue.
 
 	This is a thread-safe way of performing the \c *value \c &= \c andValue
@@ -564,15 +549,15 @@
 	mutex in this case. 
 
 	\return The original value of \c value.
-  \sa atomic_and64() for a version that works on \c long \c long
+
-  \sa atomic_set(), atomic_test_and_set(), atomic_add(),
+	\sa atomic_and64() for a version that works on \c long \c long
-    atomic_or(), atomic_get()
+	\sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_or(),	
+		atomic_get()
 */
 
 
-/*!
+/*!	\fn int32 atomic_or(vint32 *value, int32 orValue)
-  \fn int32	atomic_or(vint32 *value, int32 orValue)
+	\brief Atomically perform a bitwise OR operation of \a orValue to the 
-  \brief Atomically perform a bitwise OR operation of \a orValue to the 
          variable \a andValue.
 
 	This is a thread-safe way of performing the \c *value \c |= \c orValue
@@ -581,14 +566,14 @@
 	mutex in this case. 
 
 	\return The original value of \c value.
-  \sa atomic_or64() for a version that works on \c long \c long
+
-  \sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(),
+	\sa atomic_or64() for a version that works on \c long \c long
-    atomic_get()
+	\sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(),
+		atomic_get()
 */
 
-/*!
+/*!	\fn int32 atomic_get(vint32 *value)
-  \fn int32	atomic_get(vint32 *value)
+	\brief Atomically return the value of \c value.
-  \brief Atomically return the value of \c value.
 
 	This is a thread-safe way of reading the contents of the \c value
 	operation. You should use these function when two or more threads might
@@ -596,14 +581,14 @@
 	mutex in this case. 
 
 	\return The original value of \c value.
-  \sa atomic_get64() for a version that works on \c long \c long
+
-  \sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(),
+	\sa atomic_get64() for a version that works on \c long \c long
-    atomic_or()
+	\sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(),
+		atomic_or()
 */
 
-/*!
+/*!	\fn int64 atomic_set64(vint64 *value, int64 newValue)
-  \fn int64	atomic_set64(vint64 *value, int64 newValue)
+	\brief Atomically set the variable \a value to \a newvalue.
-  \brief Atomically set the variable \a value to \a newvalue.
 
 	This is a thread-safe way of performing the \c *value \c = \c newValue
 	operation. You should use these function when two or more threads might
@@ -612,30 +597,30 @@
 
 	\return The original value of \c value.
 
-  \sa atomic_set() for a version that works on an \c int32
+	\sa atomic_set() for a version that works on an \c int32
-  \sa atomic_test_and_set64(), atomic_add64(), atomic_and64(),
+	\sa atomic_test_and_set64(), atomic_add64(), atomic_and64(),
-    atomic_or64(), atomic_get64()
+		atomic_or64(), atomic_get64()
 */
 
-/*!
+/*!	\fn int64 atomic_test_and_set64(vint64 *value, int64 newValue,
-  \fn int64	atomic_test_and_set64(vint64 *value, int64 newValue, int64 testAgainst)
+		int64 testAgainst)
-  \brief Atomically set the variable \a value to \a newValue if the current
+	\brief Atomically set the variable \a value to \a newValue if the current
          value is \a testAgainst.
   
-	This is a thread-safe way of conditionally performing the \c *value \c += 
+	This is a thread-safe way of conditionally performing the \c *value
-	\c newValue operation. You should use these function when two or more threads
+	\c += \c newValue operation. You should use these function when two
-	might access the variable simultaneously. You don't have to use a semaphore
+	or more threads might access the variable simultaneously. You don't
-	or a mutex in this case. 
+	have to use a semaphore or a mutex in this case. 
-	
+
 	\return The original value of \c value.
-  \sa atomic_test_and_set() for a version that works on an \c int32
+
-  \sa atomic_set64(), atomic_add64(), atomic_and64(),
+	\sa atomic_test_and_set() for a version that works on an \c int32
-    atomic_or64(), atomic_get64()
+	\sa atomic_set64(), atomic_add64(), atomic_and64(),
+		atomic_or64(), atomic_get64()
 */
 
-/*!
+/*!	\fn int64 atomic_add64(vint64 *value, int64 addValue)
-  \fn int64	atomic_add64(vint64 *value, int64 addValue)
+	\brief Atomically add the value of \a addValue to \a value.
-  \brief Atomically add the value of \a addValue to \a value.
   
 	This is a thread-safe way of performing the \c *value \c += \c addValue
 	operation. You should use these function when two or more threads might
@@ -643,14 +628,14 @@
 	mutex in this case. 
 	
 	\return The original value of \c value.
-  \sa atomic_add() for a version that works on an \c int32
+
-  \sa atomic_set64(), atomic_test_and_set64(), atomic_and64(),
+	\sa atomic_add() for a version that works on an \c int32
-    atomic_or64(), atomic_get64()
+	\sa atomic_set64(), atomic_test_and_set64(), atomic_and64(),
+		atomic_or64(), atomic_get64()
 */
 
-/*!
+/*!	\fn int64 atomic_and64(vint64 *value, int64 andValue)
-  \fn int64	atomic_and64(vint64 *value, int64 andValue)
+	\brief Atomically perform a bitwise AND operation of \a andValue to the 
-  \brief Atomically perform a bitwise AND operation of \a andValue to the 
          variable \a andValue.
 
 	This is a thread-safe way of performing the \c *value \c &= \c andValue
@@ -659,14 +644,14 @@
 	mutex in this case. 
 
 	\return The original value of \c value.
-  \sa atomic_and() for a version that works on an \c int32
+
-  \sa atomic_set64(), atomic_test_and_set64(), atomic_add64(),
+	\sa atomic_and() for a version that works on an \c int32
-    atomic_or64(), atomic_get64()
+	\sa atomic_set64(), atomic_test_and_set64(), atomic_add64(),
+		atomic_or64(), atomic_get64()
 */
 
-/*!
+/*!	\fn int64 atomic_or64(vint64 *value, int64 orValue)
-  \fn int64	atomic_or64(vint64 *value, int64 orValue)
+	\brief Atomically perform a bitwise OR operation of \a orValue to the 
-  \brief Atomically perform a bitwise OR operation of \a orValue to the 
          variable \a andValue.
 
 	This is a thread-safe way of performing the \c *value \c |= \c orValue
@@ -675,14 +660,14 @@
 	mutex in this case. 
 
 	\return The original value of \c value.
-  \sa atomic_or() for a version that works on an \c int32
+
-  \sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), atomic_and64(),
+	\sa atomic_or() for a version that works on an \c int32
-    atomic_get64()
+	\sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), atomic_and64(),
+		atomic_get64()
 */
 
-/*!
+/*!	\fn int64 atomic_get64(vint64 *value)
-  \fn int64	atomic_get64(vint64 *value)
+	\brief Atomically return the value of \c value.
-  \brief Atomically return the value of \c value.
 
 	This is a thread-safe way of reading the contents of the \c value
 	operation. You should use these function when two or more threads might
@@ -690,33 +675,30 @@
 	mutex in this case. 
 
 	\return The original value of \c value.
-  \sa atomic_get() for a version that works on an \c int32
+
-  \sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), atomic_and64(),
+	\sa atomic_get() for a version that works on an \c int32
-    atomic_or64()
+	\sa atomic_set64(), atomic_test_and_set64(), atomic_add64(),
+		atomic_and64(), atomic_or64()
 */
 
 //! @}
 
-/*!
+/*!	\fn void* get_stack_frame(void)
-  \fn void*	get_stack_frame(void)
   \brief Internal function.
   \internal
 */
 
-/*!
+/*!  \name Deprecated defines */
-	\name Deprecated defines
-*/
 
 //! @{
 
-/*!
+/*!	\def FALSE
-  \def FALSE
+	\brief Obsolete. Use \c false.
-  \brief Obsolete. Use \c false.
 */
 
-/*!
+/*!	\def TRUE
-  \def TRUE
+	\brief Obsolete. Use \c true.
-  \brief Obsolete. Use \c true.
 */
 
 //! @}
+

docs/user/support/Unarchiver.dox

@@ -11,12 +11,11 @@
  */
 
 
-/*!
+/*!	\class BUnarchiver
-\class BUnarchiver
+	\ingroup support
-\ingroup support
+	\ingroup libbe
-\ingroup libbe
+	\brief A class that simplifies the unarchiving of complicated BArchivable
-\brief A class that simplifies the unarchiving of complicated BArchivable
+		hierarchies.
-	hierarchies.
 
 	The BUnarchiver class is a small class used to recover BArchivable objects
 	that have been archived with the BArchiver class. It also provides ownership
@@ -40,8 +39,7 @@
 */
 
 
-/*!
+/*!	\fn BUnarchiver::BUnarchiver(const BMessage* archive)
-	\fn BUnarchiver::BUnarchiver(const BMessage* archive)
 	\brief Constructs a BUnarchiver object to manage \c archive.
 
 	\note To guarantee that your AllUnarchived() method will be called during
@@ -57,74 +55,87 @@
 */
 
 
-/*!
+/*!	\fn BUnarchiver::~BUnarchiver()
-	\fn BUnarchiver::~BUnarchiver()
+	\brief Destroys a BUnarchiver object.
-	\brief Destroys a BUnarchiver object. Calls this objects Finish() method,
+
-		if it has not yet been called.
+	Calls this objects Finish() method, if it has not yet been called.
 */
 
 
-/*!
+/*!	\fn status_t BUnarchiver::EnsureUnarchived(int32 token)
-	\fn status_t BUnarchiver::EnsureUnarchived(int32 token)
+	\brief Ensure the object represented by \a token is unarchived and
-	\brief Ensure the object represented by \c token is unarchived and
 		instantiated.
+
+	\param token the object \a token
 */
 
 
-/*!
+/*!	\fn status_t BUnarchiver::EnsureUnarchived(const char* name,
-	\fn status_t BUnarchiver::EnsureUnarchived(const char* name,
 		int32 index = 0)
-	\brief Ensure the object archived under \c name at \c index is unarchived
+	\brief Ensure the object archived under \a name at \a index is unarchived
 		and instantiated.
+
+	\param name The archive \a name.
+	\param index The archive \a index.
 */
 
 
-/*!
+/*!	\fn bool BUnarchiver::IsInstantiated(int32 token)
-	\fn bool BUnarchiver::IsInstantiated(int32 token)
 	\brief Checks whether the object represented by \c token has been
 		instantiated in this session.
+
+	\param token The object \a token
 */
 
 
-/*!
+/*!	\fn bool BUnarchiver::IsInstantiated(const char* name, int32 index = 0)
-	\fn bool BUnarchiver::IsInstantiated(const char* name, int32 index = 0)
+	\brief Checks whether the object archived under \a name at \a index has been
-	\brief Checks whether the object archived under \c name at \c index has been
 		instantiated in this session.
+
+	\param name The archive \a name.
+	\param index The arcive \a token.
  */
 
 
-/*!
+/*!	\fn template<class T> status_t BUnarchiver::GetObject(int32 token,
-	\fn template<class T> status_t BUnarchiver::GetObject(int32 token,
 		ownership_policy owning, T*& object)
 
 	\brief Recover an object by token that was archived by a BArchiver object.
 	If the object has not yet been instantiated, and this request is not coming
 	from an AllUnarchived() implementation, the object will be instantiated now.
 
-	If the retrieved object is not of the type \c T, then this method will fail.
+	If the retrieved object is not of the type T, then this method will fail.
 	If this method fails, you will not receive ownership of the object, no
 	matter what you specified in \c owning.
 	
-	\tparam T The type of object you wish to find.
+	\tparam T The type of \a object you wish to find.
 
-	\param token The token you got for this object from
+	\param token The \a token you got for this object from
 		BArchiver::GetTokenForArchivable() during archival.
 	\param owning Whether or not you wish to take ownership of the
 		retrieved object.
-	\param object Return parameter for the retrieved object of type \c T.
+	\param object Return parameter for the retrieved object of type T.
 
-	\retval B_BAD_TYPE The object retrieved was not of type \c T.
+	\retval B_OK The object retrieved was of type T.
+	\retval B_BAD_TYPE The object retrieved was not of type T.
 */
 
 
-/*!
+/*!	\fn template<class T> status_t BUnarchiver::GetObject(int32 token,
-	\fn template<class T> status_t BUnarchiver::GetObject(int32 token,
 		T*& object)
 
-	\brief Recover and take ownership of an object represented by \c token.
+	\brief Recover and take ownership of an object represented by \a token.
 
-	Equivalent to calling GetObject(token, BUnarchiver::B_ASSUME_OWNERSHIP,
+	Equivalent to calling GetObject(token, \c B_ASSUME_OWNERSHIP, object)
-		 object)
+
+	\tparam T The type of \a object you wish to find.
+
+	\param token The \a token you got for this object from
+		BArchiver::GetTokenForArchivable() during archival.
+	\param object The return parameter for the retrieved object of type T.
+
+	\retval B_OK The object retrieved was of type T.
+	\retval B_BAD_TYPE The object retrieved was not of type T.
 */
 
 
@@ -137,7 +148,7 @@
 		instantiated, and this request is not coming from an AllUnarchived()
 		implementation, the object will be instantiated now.
 
-	If the retrieved object is not of the type \c T, then this method will fail.
+	If the retrieved object is not of the type T, then this method will fail.
 	If this method fails, you will not receive ownership of the object, no
 	matter what you specified in \c owning.
 	
@@ -145,61 +156,90 @@
 
 	\param name The name that was passed to BArchiver::AddArchivable() when
 		adding this object.
-	\param index The index of the object you wish to recover (0 based, like
+	\param index The index of the object you wish to recover (\c 0-based,
-		BMessage::FindData().
+		like BMessage::FindData().
 	\param owning Dictates whether or not you wish to take ownership of the
 		retrieved object.
-	\param object Return parameter for the retrieved object of type \c T.
+	\param object Return parameter for the retrieved object of type T.
 
-	\retval B_BAD_TYPE The object retrieved was not of type \c T.
+	\retval B_OK The object retrieved was of type T.
+	\retval B_BAD_TYPE The object retrieved was not of type T.
 */
 
 
-/*!
+/*!	\fn template<class T> status_t BUnarchiver::FindObject(const char* name,
-	\fn template<class T> status_t BUnarchiver::FindObject(const char* name,
 		int32 index, T*& object)
 
 	\brief Recover and take ownership of an object that had previously been
 		archived using the BArchiver::AddArchivable() method.
+
+	\tparam T The type of object you wish to find.
+
+	\param name The name that was passed to BArchiver::AddArchivable() when
+		adding this object.
+	\param index The index of the object you wish to recover (\c 0-based,
+		like #BMessage::FindData().
+	\param object Return parameter for the retrieved object of type T.
+
+	\retval B_OK The object retrieved was of type T.
+	\retval B_BAD_TYPE The object retrieved was not of type T.
 */
 
 
-/*!
+/*!	\fn template<class T> status_t BUnarchiver::FindObject(const char* name,
-	\fn template<class T> status_t BUnarchiver::FindObject(const char* name,
 		ownership_policy owning, T*& object)
 
-	\brief Recover an object at index 0 that had previously been archived using
+	\brief Recover an object at index \c 0 that had previously been
-		the BArchiver::AddArchivable() method.
+		archived using the BArchiver::AddArchivable() method.
 
-	Equivalent to calling FindObject(name, 0, owning, object).
+	Equivalent to calling FindObject(name, \c 0, owning, object).
+
+	\tparam T The type of \a object you wish to find.
+
+	\param name The name that was passed to BArchiver::AddArchivable() when
+		adding this object.
+	\param owning Dictates whether or not you wish to take ownership of the
+		retrieved object.
+	\param object Return parameter for the retrieved object of type T.
+
+	\retval B_OK The object retrieved was of type T.
+	\retval B_BAD_TYPE The object retrieved was not of type T.
 */
 
 
-/*!
+/*!	\fn template<class T> status_t BUnarchiver::FindObject(const char* name,
-	\fn template<class T> status_t BUnarchiver::FindObject(const char* name,
 		T*& object)
 
-	\brief Recover and take ownership of an object at index 0 that had
+	\brief Recover and take ownership of an object at index \c 0 that had
 		previously been archived using the BArchiver::AddArchivable() method.
 
-	Equivalent to calling FindObject(name, 0, BUnarchiver::B_ASSUME_OWNERSHIP,
+	Equivalent to calling FindObject(name, \c 0,
-		object).
+		BUnarchiver::B_ASSUME_OWNERSHIP, object).
+
+	\tparam T The type of \a object you wish to find.
+
+	\param name The name that was passed to BArchiver::AddArchivable() when
+		adding this object.
+	\param object Return parameter for the retrieved \a object of type T.
+
+	\retval B_OK The \a object retrieved was of type T.
+	\retval B_BAD_TYPE The \a object retrieved was not of type T.
 */
 
 
-/*!
+/*!	\fn status_t BUnarchiver::Finish(status_t err = B_OK);
-	\fn status_t BUnarchiver::Finish(status_t err = B_OK);
 	\brief Report any unarchiving errors and possibly complete the archiving
 		session.
-	\return The first error reported in this unarchiving session, or B_OK.
 
 	This method may finish an unarchiving session (triggering the call of all
 	instantiated objects' AllUnarchived() methods) if the following conditions
 	are true:
-	\li No errors have been reported to this or any other BUnarchiver object
+
-		within this session.
+	\li No errors have been reported to this or any other BUnarchiver
-	\li This is the last remaining BUnarchiver that has not had its Finish()
+		object within this session.
-		method invoked.
+	\li This is the last remaining BUnarchiver that has not had its
+		Finish() method invoked.
+
 	If you call this method with an error code not equal to B_OK, then this
 	unarchiving session has failed, instantiated objects will not have their
 	AllUnarchived() methods called, and any subsequent calls to this method
@@ -207,22 +247,22 @@
 	Furthermore, any objects that have been instantiated, but have not had
 	their ownership assumed by another object will now be deleted (excluding
 	the root object).
+
+	\return The first error reported in this unarchiving session, or \c B_OK.
 */
 
 
 /*!
 	\fn	const BMessage*	BUnarchiver::ArchiveMessage() const
-	\brief Returns the BMessage* used to construct this BUnarchiver. This is
+	\brief Returns the BMessage* used to construct this BUnarchiver.
-		the archive that FindObject() uses.
+
+	This is the archive that FindObject() uses.
 */
 
 
-/*!
+/*!	\fn static bool BUnarchiver::IsArchiveManaged(const BMessage* archive)
-	\fn static bool BUnarchiver::IsArchiveManaged(const BMessage* archive)
 
-	\brief Checks whether \c archive was managed by a BArchiver object.
+	\brief Checks whether \a archive was managed by a BArchiver object.
-	\retval true if \c archive was managed by a BArchiver object.
-	\retval false otherwise.
 
 	This method can be used to maintain archive backwards-compatibility for a
 	class that has been updated to use the BArchiver class. If there is a
@@ -231,7 +271,7 @@
 	object.
 
 	Here is an example of how you might use this method. Note that you
-	must still call BUnarchiver::PrepareArchive(archive), either way.
+	must still call PrepareArchive(archive) either way.
 
 	\code
 MyArchivableClas::MyArchivableClass(BMessage* archive)
@@ -247,14 +287,14 @@ MyArchivableClas::MyArchivableClass(BMessage* archive)
 	}
 }
 	\endcode
+
+	\retval true if \a archive was managed by a BArchiver object.
+	\retval false otherwise.
 */
 
 
-/*!
+/*!	\fn static BMessage* BUnarchiver::PrepareArchive(BMessage* &archive)
-	\fn static BMessage* BUnarchiver::PrepareArchive(BMessage*& archive)
 	\brief Prepares \c archive for use by a BUnarchiver.
-	\param	archive The archive you wish to have prepared.
-	\return The same BMessage as is passed in.
 
 	This method must be called if you plan to use a BUnarchiver on an archive.
 	It must be called once for each class an object inherits from that
@@ -272,33 +312,45 @@ MyArchivableClas::MyArchivableClas(BMessage* archive)
 	// ...
 }
 	\endcode
+
+	\param archive The archive you wish to have prepared.
+
+	\return The same #BMessage as is passed in.
 */
 
 
-/*!
+/*!	\fn void BUnarchiver::AssumeOwnership(BArchivable* archivable)
-	\fn void BUnarchiver::AssumeOwnership(BArchivable* archivable)
+	\brief Become the owner of \a archivable.
-	\brief Become the owner of \c archivable.
 
-	After calling this method, you are responsible for the deletion
+	After calling this method you are responsible for deleting the
-		of \c archivable.
+	\a archivable.
+
+	\param archivable The \a archivable object.
 */
 
 
-/*!
+/*!	\fn void BUnarchiver::RelinquishOwnership(BArchivable* archivable)
-	\fn void BUnarchiver::RelinquishOwnership(BArchivable* archivable)
+	\brief Relinquish ownership of \a archivable. If \a archivable remains
-	\brief Relinquish ownership of \c archivable. If \c archivable remains
 		unclaimed at the end of the unarchiving session, it will be deleted
 		(unless it is the root object).
+
+	\param archivable The \a archivable object.
 */
 
 
-/*!
+/*!	\fn template<class T> status_t BUnarchiver::InstantiateObject(
-	\fn template<class T> status_t BUnarchiver::InstantiateObject(
 		BMessage* from, T*& object)
-	\brief Attempt to instantiate an object of type \c T from BMessage* \c from.
+	\brief Attempt to instantiate an object of type T from BMessage*
+		\a from.
 
-	If the instantiated object is not of type \c T, then it will be deleted,
+	If the instantiated object is not of type T, then it will be deleted,
 	and this method will return \c B_BAD_TYPE. This method is similar to
 	the instantiate_object() function, but provides error reporting and 
 	protection from memory leaks.
+
+	\param from The #BMessage to instantiate from.
+	\param object Return parameter for the retrieved object of type T.
+
+	\retval B_OK The object retrieved was of type T.
+	\retval B_BAD_TYPE The object retrieved was not of type T.
 */