From 412f030b0f95e4d79cb88955e4b6c954d8db3cdd Mon Sep 17 00:00:00 2001
From: Adrien Destugues <pulkomandy@gmail.com>
Date: Sat, 17 Jan 2015 13:41:55 +0100
Subject: [PATCH] Some clarifications to BInvoker docs.

---
 docs/user/app/Invoker.dox | 34 ++++++++++++++++++++++------------
 1 file changed, 22 insertions(+), 12 deletions(-)

diff --git a/docs/user/app/Invoker.dox b/docs/user/app/Invoker.dox
index ae82a18ed0..3c5d2ca930 100644
--- a/docs/user/app/Invoker.dox
+++ b/docs/user/app/Invoker.dox
@@ -103,10 +103,12 @@
 	You may pass \c NULL into \a message to delete the current message
 	without replacing it.
 
-	When Invoke() is called, the message is sent to the designated BHandler
-	known as the "target". The message is sent as a BMessage. The message is
-	not copied, rather ownership of the BMessage object is transferred to
-	the invoker.
+	When Invoke() is called without a specific message, a copy of the
+	message given here is sent to the "target" BHandler. The message
+	is sent as a BMessage.
+
+	BInvoker takes ownership of the BMessage object, so you must not delete
+	it yourself.
 
 	\since BeOS R3
 */
@@ -128,7 +130,7 @@
 	\brief Returns the message's \c what data member.
 
 	\note If a message has not been assigned to the invoker this method
-	      returns \c NULL instead.
+	      returns \c 0 instead.
 
 	\since BeOS R3
 */
@@ -138,6 +140,9 @@
 	\fn status_t BInvoker::SetTarget(BMessenger messenger)
 	\brief Sets the invoker's target to \a messenger.
 
+	A BMessenger target can be used to designate a remote handler (living
+	in another team).
+
 	\since BeOS R3
 */
 
@@ -151,12 +156,10 @@
 	\note It is not necessary to specify both the \a handler and the
 	      \a looper, the unused parameter should be passed in as \c NULL.
 
-	If given a \a handler, it must be attached to a BLooper. The message
-	is always sent to a BLooper which distributes the message to the
-	correct handler (which might be the \a looper itself).
+	If given only a \a handler, it must already be attached to a BLooper.
 
-	The preferred handler, i.e. for a window, is the view that currently
-	has focus.
+	If given only a \a looper, the message will be sent to its preferred
+	handler (in the case of a BWindow that is the focused view).
 
 	\since BeOS R3
 */
@@ -220,8 +223,11 @@
 	\fn status_t BInvoker::Invoke(BMessage* message)
 	\brief Sends the \a message to the invoker's target.
 
-	If \a message is \c NULL the message previously set on the invoker is sent
-	to the invoker's target instead.
+	If \a message is \c NULL the default message is sent instead. You can set
+	the default message using \a SetMessage or in the constructor.
+
+	This method also sends a B_CONTROL_INVOKED notification to handlers
+	which registered themselves using StartWatching
 
 	\since BeOS R3
 */
@@ -236,7 +242,11 @@
 	of the invoker's handler will receive their expected notifications.
 	By default, \a kind is \c B_CONTROL_INVOKED, the same as sent by Invoke().
 
+	BInvoker does not send the notification itself, it is up to subclasses to
+	do that as needed.
+
 	\sa BLooper::StartWatching()
+	\sa BLooper::SendNotices()
 	\sa BHandler::NoticeChange()
 
 	\since BeOS R5