Document Launch flags and Preference directory for findpath

Change-Id: I150c0ca1e0deb5749689bb1019a48efdcdc99def
Reviewed-on: https://review.haiku-os.org/c/haiku/+/6701
Tested-by: Commit checker robot <[email protected]>
Reviewed-by: Adrien Destugues <[email protected]>
Reviewed-by: nephele nephele <[email protected]>

docs/user/app/Roster.dox

@@ -24,15 +24,24 @@
 
 /*!
 	\def B_SINGLE_LAUNCH
-	\brief Single launch.
+	\brief Similar to B_EXCLUSIVE_LAUNCH, with the exception that it is per file location,
+	copying the file to a second location therefore allows the application to be started a second time.
 
+	Attempts to launch the same application from the same path again will result in a B_ARGV_RECEIVED or
+	B_REFS_RECEIVED message delivered to the existing instance. The application should take care of handling
+	these messages correctly. Applications which can't or don't want to handle this should use
+	B_MULTIPLE_LAUNCH instead.
+	
+	This flag only ensures exclusive launches when started via BRoster, launching an application in another
+	way, for example with fork+exec will allow the application to run a second time. This should not be
+	relied on for applications that need to run exclusively in all cases.
 	\since BeOS R3
 */
 
 
 /*!
 	\def B_MULTIPLE_LAUNCH
-	\brief Multiple launch.
+	\brief There are no restrictions on how many times this application can be opened.
 
 	\since BeOS R3
 */
@@ -40,8 +49,16 @@
 
 /*!
 	\def B_EXCLUSIVE_LAUNCH
-	\brief Exclusive launch.
+	\brief This will make the registrar ensure only one application with this application signature is
+	running at any given time.
 
+	Attempts to launch the same application again will result in a B_ARGV_RECEIVED or B_REFS_RECEIVED message
+	delivered to the existing instance. The application should take care of handling these messages
+	correctly. Applications which can't or don't want to handle this should use B_MULTIPLE_LAUNCH instead.
+	
+	This flag only ensures exclusive launches when started via BRoster, launching an application in another
+	way, for example with fork+exec will allow the application to run a second time. This should not be
+	relied on for applications that need to run exclusively in all cases.
 	\since BeOS R3
 */
 
@@ -56,7 +73,8 @@
 
 /*!
 	\def B_BACKGROUND_APP
-	\brief Background app, won't appear in Deskbar.
+	\brief This is intended for background executables, these are hidden from the Deskbar. They also receive
+	 less lenience when the system shuts down.
 
 	\since BeOS R3
 */
@@ -67,6 +85,12 @@
 	\brief The application can't receive messages, information must be
 	       passed at launch through argv, typically from the command line.
 
+	\warning B_ARGV_ONLY Is never intended for GUI Applications.
+	Executables marked with this flag will be killed on shutdown.
+	BMessages are absolutely required for correct operation of GUI applications on Haiku.
+	
+	Using this flag with B_EXCLUSIVE_LAUNCH and B_SINGLE_LAUNCH will prevent the application
+	from correctly getting the messages about subsequent launch requests!
 	\since BeOS R3
 */
 

docs/user/storage/FindDirectory.dox

@@ -180,6 +180,11 @@
 	\var directory_which B_SYSTEM_PREFERENCES_DIRECTORY
 	\brief The system preferences directory.
 
+	Contains applications used to configure Haiku, which are usually available in the "Preferences" Deskbar
+	menu.
+
+	\warning Not to be confused with B_SYSTEM_SETTINGS_DIRECTORY, where system settings files can be saved.
+
 	\since Haiku R1
 */
 
@@ -408,8 +413,11 @@
 
 /*!
 	\var directory_which B_USER_CONFIG_DIRECTORY
-	\brief The user packaged installation location directory.
+	\brief The top-level directory of the user packages installation.
 
+	This directory has a similar layout to the main system directory, and can be used to install user-specific packages.
+
+	\warning Do not store configuration and settings files directly here, instead use B_USER_SETTINGS_DIRECTORY
 	\since BeOS R3
 */
 
@@ -582,6 +590,11 @@
 	\var directory_which B_USER_PREFERENCES_DIRECTORY
 	\brief The user preference applications directory.
 
+	Can contain applications used to configure Haiku or third-party applications,
+	which are usually available in the "Preferences" Deskbar menu.
+
+	\warning Not to be confused with B_USER_SETTINGS_DIRECTORY, where user settings files can be saved.
+
 	\since Haiku R1
 */
 
@@ -733,6 +746,11 @@
 	\var directory_which B_PREFERENCES_DIRECTORY
 	\brief The global preference applications directory.
 
+	Can contain applications used to configure Haiku,
+	which are usually available in the "Preferences" Deskbar menu.
+
+	\warning Not to be confused with B_SYSTEM_SETTINGS_DIRECTORY, where system settings files can be saved.
+
 	\since BeOS R3
 */
 
@@ -1125,6 +1143,11 @@
 	\var B_FIND_PATH_PREFERENCES_DIRECTORY
 	\brief The preference application directory.
 
+	Contain applications used to configure Haiku,
+	which are usually available in the "Preferences" Deskbar menu.
+
+	\warning Not to be confused with B_FIND_PATH_SETTINGS_DIRECTORY, where system settings files can be saved.
+
 	\since Haiku R1
 */