[haiku-commits] haiku: hrev53803 - docs/user/app

  • From: waddlesplash <waddlesplash@xxxxxxxxx>
  • To: haiku-commits@xxxxxxxxxxxxx
  • Date: Sat, 1 Feb 2020 19:52:46 -0500 (EST)

hrev53803 adds 1 changeset to branch 'master'
old head: e557eb2c664e3954e71bd768413834dd153df848
new head: 151a4f7f9354583f183b5fe1ec5f4fe83c6d2262
overview: 
https://git.haiku-os.org/haiku/log/?qt=range&q=151a4f7f9354+%5Ee557eb2c664e

----------------------------------------------------------------------------

151a4f7f9354: 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 <waddlesplash@xxxxxxxxx>

                                     [ John Scipione <jscipione@xxxxxxxxx> ]

----------------------------------------------------------------------------

Revision:    hrev53803
Commit:      151a4f7f9354583f183b5fe1ec5f4fe83c6d2262
URL:         https://git.haiku-os.org/haiku/commit/?id=151a4f7f9354
Author:      John Scipione <jscipione@xxxxxxxxx>
Date:        Sat Feb  1 02:50:11 2020 UTC
Committer:   waddlesplash <waddlesplash@xxxxxxxxx>
Commit-Date: Sun Feb  2 00:52:41 2020 UTC

----------------------------------------------------------------------------

2 files changed, 45 insertions(+), 28 deletions(-)
docs/user/app/Looper.dox    | 14 +++++-----
docs/user/app/Messenger.dox | 59 ++++++++++++++++++++++++++---------------

----------------------------------------------------------------------------

diff --git a/docs/user/app/Looper.dox b/docs/user/app/Looper.dox
index 482c0f909c..d04063df25 100644
--- a/docs/user/app/Looper.dox
+++ b/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
-             \a handler associated with this looper, and (optionally) request a
-             reply.
+       \brief Sends a message with \a command \c what identifier to the
+             \a handler associated with this looper. 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.
@@ -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,
-              and (optionally) request a reply.
+       \brief Send a \a message to the \a handler associated with this looper.
+              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.
diff --git a/docs/user/app/Messenger.dox b/docs/user/app/Messenger.dox
index 100fab7f1a..30ff0ea9d5 100644
--- a/docs/user/app/Messenger.dox
+++ b/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
-              synchronously to the messenger's target, without waiting for a 
reply.
+       \brief Delivers a BMessage with \a command \c what identifier to the
+              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,
-              without waiting for a reply.
+       \brief Delivers a \a message to the messenger's target. A response 
message
+              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,
-              without waiting for a reply.
+       \brief Delivers a \a message to the messenger's target. A response 
message
+              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 timeout A timeout for the delivery of the message.
+       \param replyTo A messenger specifying the target for a response 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
-              synchronously to the messenger's target and waits for a reply.
+       \brief Delivers a BMessage with \a command \c what identifier to the
+              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
-              message will be copied.
+       \param reply A pointer to a pre-allocated BMessage object which the 
reply
+              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
-              waits for a reply.
+       \brief Delivers a \a message to the messenger's target and waits for a
+              \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
-                  message will be copied.
-       \param deliveryTimeout A timeout for the delivery of the message.
-       \param replyTimeout A timeout for waiting for the reply.
+       \param reply A pointer to a pre-allocated BMessage which the reply
+                  message will be copied into.
+       \param deliveryTimeout The message delivery timeout in microseconds.
+              (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.


Other related posts:

  • » [haiku-commits] haiku: hrev53803 - docs/user/app - waddlesplash