API Docs: Clarify BLooper::PostMessage and BMessenger::SendMessage

... docs to make it clear which methods work synchronously and which work
asynchronously. A small number of related edits are included as well as a
couple of pedantic whitespace changes. Clarify sync vs. async reply
handling better in BMessenger class description. Add The to make sentences.

Change-Id: I3069934fc5e82dda25331e85884d6d0c0c100dfd
Reviewed-on: https://review.haiku-os.org/c/haiku/+/2178
Reviewed-by: waddlesplash <[email protected]>

docs/user/app/Looper.dox

@@ -220,7 +220,7 @@
 	Posting a message puts it in the message queue. The message passes through
 	the default handler chain.
 
-	\param command The \c what identifier of the message that needs to be sent.
+	\param command The \c what identifier of the message to be sent.
 
 	\return A status code.
 	\retval B_OK The operation succeeded, and the message is sent to the port.
@@ -262,7 +262,7 @@
 	\retval B_OK The operation succeeded, and the message is sent to the port.
 	\retval B_ERROR There was a general operation error.
 	\retval B_BAD_VALUE This looper is not yet running and therefore cannot
-		receive messages.
+	        receive messages.
 
 	\see PostMessage(uint32) if you want to send a message without data
 	     members.
@@ -278,9 +278,9 @@
 /*!
 	\fn status_t BLooper::PostMessage(uint32 command, BHandler* handler,
 		BHandler* replyTo)
-	\brief Send a message with the \a command as \c what identifier to the
+	\brief Sends a message with \a command \c what identifier to the
-	      \a handler associated with this looper, and (optionally) request a
+	      \a handler associated with this looper. A response may be sent to the
-	      reply.
+	      \a replyTo handler asynchronously.
 
 	The target \a handler should be associated with this looper. This method
 	bypasses the default message queue.
@@ -313,8 +313,8 @@
 /*!
 	\fn status_t BLooper::PostMessage(BMessage* message, BHandler* handler,
 		BHandler* replyTo)
-	\brief Send a \a message to the \a handler associated with this looper,
+	\brief Send a \a message to the \a handler associated with this looper.
-	       and (optionally) request a reply.
+	       A response may be sent to the \a replyTo handler asynchronously.
 
 	The target \a handler should be associated with this looper. This method
 	bypasses the default message queue.

docs/user/app/Messenger.dox

@@ -36,6 +36,11 @@
 	is roughly equivalent in terms of efficiency to posting a message
 	directly to the messenger's target (i.e. BLooper::PostMessage()).
 
+	If you supply a target BMessenger or BHandler to SendMessage() the method
+	will return immediately after delivery and the response will be handled
+	asynchronously, otherwise the method will return once the reply has been
+	delivered or after a set timeout.
+
 	The global \a be_app_messenger pointer targets the main message
 	loop of \a be_app is automatically initialized for you when you create
 	a BApplication object, you can use it wherever a BMessenger is called for.
@@ -88,7 +93,7 @@
 	\param handler The target handler. May be \c NULL.
 	\param looper The target looper. May be \c NULL.
 	\param _result An optional pointer to a pre-allocated status_t into which
-		   the result of the initialization is written.
+	       the result of the initialization is written.
 
 	\since BeOS R3
 */
@@ -206,8 +211,9 @@
 
 /*!
 	\fn	status_t BMessenger::SendMessage(uint32 command, BHandler* replyTo) const
-	\brief Delivers a BMessage with a \c what parameter set to \a command
+	\brief Delivers a BMessage with \a command \c what identifier to the
-	       synchronously to the messenger's target, without waiting for a reply.
+	       messenger's target. A response may be sent to the \a replyTo handler
+	       asynchronously.
 
 	If the target's message port is full, the method waits indefinitely, until
 	space becomes available in the port. After delivery the method returns
@@ -230,8 +236,8 @@
 /*!
 	\fn status_t BMessenger::SendMessage(BMessage* message, BHandler* replyTo,
 		bigtime_t timeout) const
-	\brief Delivers a BMessage synchronously to the messenger's target,
+	\brief Delivers a \a message to the messenger's target. A response message
-	       without waiting for a reply.
+	       may be sent back to the \a replyTo handler asynchronously.
 
 	A copy of the supplied message is sent and the caller retains ownership
 	of \a message.
@@ -241,10 +247,13 @@
 	first). After delivery the method returns immediately. It does not wait
 	until the target processes the message or even sends a reply.
 
+	This method does not return by default until the message has been delivered.
+	You can set a delivery \a timeout in microseconds.
+
 	\param message The message to be sent.
-	\param replyTo The handler to which a reply to the message shall be sent.
+	\param replyTo The handler for a response message to be sent.
 	       May be \c NULL.
-	\param timeout A timeout for the delivery of the message.
+	\param timeout The message delivery timeout in microseconds. (optional)
 
 	\return A status code, \c B_OK on success or an error code otherwise.
 	\retval B_OK Everything went fine.
@@ -262,8 +271,8 @@
 /*!
 	\fn	status_t BMessenger::SendMessage(BMessage* message, BMessenger replyTo,
 		bigtime_t timeout) const
-	\brief Delivers a BMessage synchronously to the messenger's target,
+	\brief Delivers a \a message to the messenger's target. A response message
-	       without waiting for a reply.
+	       may be sent back to the \a replyTo messenger's target asynchronously.
 
 	A copy of the supplied message is sent and the caller retains ownership
 	of \a message.
@@ -273,9 +282,12 @@
 	first). After delivery the method returns immediately. It does not wait
 	until the target processes the message or even sends a reply.
 
+	This method does not return by default until the message has been delivered.
+	You can set a delivery \a timeout in microseconds.
+
 	\param message The message to be sent.
-	\param replyTo A messenger specifying the target for a reply to \a message.
+	\param replyTo A messenger specifying the target for a response message.
-	\param timeout A timeout for the delivery of the message.
+	\param timeout The message delivery timeout in microseconds. (optional)
 
 	\return A status code, \c B_OK on success or an error code otherwise.
 	\retval B_OK Everything went fine.
@@ -292,16 +304,16 @@
 
 /*!
 	\fn	status_t BMessenger::SendMessage(uint32 command, BMessage* reply) const
-	\brief Delivers a BMessage with a \c what parameter set to \a command
+	\brief Delivers a BMessage with \a command \c what identifier to the
-	       synchronously to the messenger's target and waits for a reply.
+	       messenger's target and waits for a \a reply BMessage synchronously.
 
 	The method does wait for a reply. The reply message is copied into
 	\a reply. If the target doesn't send a reply, the \c what field of
 	\a reply is set to \c B_NO_REPLY.
 
 	\param command The what field of the message to deliver.
-	\param reply A pointer to a pre-allocated BMessage into which the reply
+	\param reply A pointer to a pre-allocated BMessage object which the reply
-	       message will be copied.
+	       message will be copied into.
 
 	\return A status code, \c B_OK on success or an error code otherwise.
 	\retval B_OK Everything went fine.
@@ -316,8 +328,8 @@
 /*!
 	\fn	status_t BMessenger::SendMessage(BMessage* message, BMessage* reply,
 		bigtime_t deliveryTimeout, bigtime_t replyTimeout) const
-	\brief Delivers a BMessage synchronously to the messenger's target and
+	\brief Delivers a \a message to the messenger's target and waits for a
-	       waits for a reply.
+	       \a reply to come back synchronously.
 
 	A copy of the supplied message is sent and the caller retains ownership
 	of \a message.
@@ -326,11 +338,16 @@
 	\a reply. If the target doesn't send a reply or if a reply timeout occurs,
 	the \c what field of \a reply is set to \c B_NO_REPLY.
 
+	This method does not return by default until the message has been delivered
+	and the reply has come back. You can set a \a deliveryTimeout and a
+	\a replyTimeout in microseconds.
+
 	\param message The message to be sent.
-	\param reply A pointer to a pre-allocated BMessage into which the reply
+	\param reply A pointer to a pre-allocated BMessage which the reply
-		   message will be copied.
+		   message will be copied into.
-	\param deliveryTimeout A timeout for the delivery of the message.
+	\param deliveryTimeout The message delivery timeout in microseconds.
-	\param replyTimeout A timeout for waiting for the reply.
+	       (optional)
+	\param replyTimeout The reply message timeout in microseconds. (optional)
 
 	\return A status code, \c B_OK on success or an error code otherwise.
 	\retval B_OK Everything went fine.