update docs rc2

Author: shikokuchuo

R/aio.R

@@ -1,37 +1,37 @@
 # nanonext - Core Functions - Aio Functions ------------------------------------
 
-#' Call the Result of an Asynchronous AIO Operation
+#' Call the Value of an Asynchronous AIO Operation
 #'
-#' Retrieve the result of an asynchronous AIO operation, waiting for the AIO
+#' Retrieve the value of an asynchronous AIO operation, waiting for the AIO
 #'     operation to complete if still in progress.
 #'
 #' @param aio An Aio (object of class 'sendAio' or 'recvAio').
 #'
 #' @return The passed Aio object (invisibly).
 #'
-#' @details For a 'recvAio', the received raw vector will be attached in \code{$raw}
+#' @details For a 'recvAio', the received raw vector may be retrieved at \code{$raw}
 #'     (unless 'keep.raw' was set to FALSE when receiving), and the converted R
-#'     object in \code{$data}.
+#'     object at \code{$data}.
 #'
-#'     For a 'sendAio', the send result will be attached to the Aio in \code{$result}.
-#'     This will be zero on success.
+#'     For a 'sendAio', the send result may be retrieved at \code{$result}. This
+#'     will be zero on success, or else an integer error code.
 #'
-#'     To access the values directly, use for example on a sendAio 'x':
-#'     \code{call_aio(x)$result}.
+#'     To access the values directly, use for example on a 'recvAio' \code{x}:
+#'     \code{call_aio(x)$data}.
 #'
-#'     For a 'recvAio', in case of an error in unserialisation or data conversion,
-#'     the received raw vector will be stored in \code{$data} to allow for the
-#'     data to be recovered.
+#'     For a 'recvAio', in case of an error in unserialisation or data conversion
+#'     (for example if the incorrect mode was specified), the received raw vector
+#'     will be stored at \code{$data} to allow for the data to be recovered.
 #'
-#'     Once the result has been successfully retrieved, the Aio is deallocated
-#'     and only the result is stored in the Aio object.
+#'     Once the value has been successfully retrieved, the Aio is deallocated
+#'     and only the value is stored in the Aio object.
 #'
 #' @section Alternatively:
 #'
 #'     Aio values may be accessed directly at \code{$result} for a 'sendAio',
 #'     and \code{$raw} or \code{$data} for a 'recvAio'. If the Aio operation is
 #'     yet to complete, an 'unresolved' logical NA will be returned. Once
-#'     completed, the resolved value will be returned instead.
+#'     complete, the resolved value will be returned instead.
 #'
 #'     \code{\link{unresolved}} may also be used, which returns TRUE only if an
 #'     Aio or Aio value has yet to resolve and FALSE otherwise. This is suitable

R/context.R

@@ -58,7 +58,8 @@ context <- function(socket) {
 #' @inheritParams send
 #' @inheritParams send_aio
 #'
-#' @return Raw vector of sent data, or zero (invisibly) if 'echo' is set to FALSE.
+#' @return Raw vector of sent data, or (invisibly) an integer exit code (zero on
+#'     success) if 'echo' is set to FALSE.
 #'
 #' @details Will block if the send is in progress and has not yet completed -
 #'     certain protocol / transport combinations may limit the number of messages
@@ -104,14 +105,20 @@ send_ctx <- function(context, data, mode = c("serial", "raw"), timeout, echo = T
 #' @inheritParams send_aio
 #'
 #' @return Named list of 2 elements: 'raw' containing the received raw vector
-#'     and 'data' containing the converted R object, or else the converted R
-#'     object if 'keep.raw' is set to FALSE.
+#'     and 'data' containing the converted object, or else the converted object
+#'     if 'keep.raw' is set to FALSE.
 #'
 #' @details Will block while awaiting the receive operation to complete.
 #'     Set a timeout to ensure that the function returns under all scenarios.
 #'
-#'     In case of an error in unserialisation or data conversion, the function
-#'     will still return the received raw vector to allow the data to be recovered.
+#'     In case of an error, an integer 'errorValue' is returned (to be
+#'     distiguishable from an integer message value). This can be verified using
+#'     \code{\link{is_error_value}}.
+#'
+#'     If the raw data was successfully received but an error occurred in
+#'     unserialisation or data conversion (for example if the incorrect mode was
+#'     specified), the received raw vector will always be returned to allow for
+#'     the data to be recovered.
 #'
 #' @examples
 #' req <- socket("req", listen = "inproc://nanonext")
@@ -177,17 +184,17 @@ recv_ctx <- function(context,
 #'     that the requestor has become unavailable since sending the request).
 #' @param ... additional arguments passed to the function specified by 'execute'.
 #'
-#' @return Zero (invisibly) on success.
+#' @return Invisibly, an integer exit code (zero on success).
 #'
 #' @details Receive will block while awaiting a message to arrive and is usually
 #'     the desired behaviour. Set a timeout to allow the function to return
 #'     if no data is forthcoming.
 #'
 #'     In the event of an error in either processing the messages or in evaluation
 #'     of the function with respect to the data, a nul byte \code{00} (or serialized
-#'     nul byte) will be sent in reply to the client to signal an error. This makes
-#'     it easy to distigush an error from a NULL return value.
-#'     \code{\link{is_nul_byte}} can be used to test for a nul byte.
+#'     nul byte) will be sent in reply to the client to signal an error. This is
+#'     to be distinguishable from a possible return value. \code{\link{is_nul_byte}}
+#'     can be used to test for a nul byte.
 #'
 #' @examples
 #' req <- socket("req", listen = "tcp://127.0.0.1:6546")
@@ -251,7 +258,7 @@ reply <- function(context,
 #' @param timeout in ms. If unspecified, a socket-specific default timeout will
 #'     be used. Note that this applies to receiving the result.
 #'
-#' @return A recv Aio (object of class 'recvAio').
+#' @return A 'recvAio' (object of class 'recvAio').
 #'
 #' @details Sending the request and receiving the result are both performed async,
 #'     hence the function will return immediately with a 'recvAio' object. Access

R/listdial.R

@@ -12,8 +12,9 @@
 #'     you wish to set configuration options on the dialer as it is not
 #'     generally possible to change these once started.
 #'
-#' @return Zero (invisibly) on success. A new Dialer (object of class 'nanoDialer'
-#'     and 'nano') is created and bound to the Socket.
+#' @return Invisibly, an integer exit code (zero on success). A new Dialer
+#'     (object of class 'nanoDialer' and 'nano') is created and bound to the
+#'     Socket or nano object if successful.
 #'
 #' @details To view all Dialers bound to a socket use \code{$dialer} on the
 #'     socket, which returns a list of Dialer objects. To access any individual
@@ -136,8 +137,9 @@ dial <- function(socket,
 #'     if you wish to set configuration options on the listener as it is not
 #'     generally possible to change these once started.
 #'
-#' @return Zero (invisibly) on success. A new Listener (object of class
-#'     'nanoListener' and 'nano') is created and bound to the Socket or nano object.
+#' @return Invisibly, an integer exit code (zero on success). A new Listener
+#'     (object of class 'nanoListener' and 'nano') is created and bound to the
+#'     Socket or nano object if successful.
 #'
 #' @details  To view all Listeners bound to a socket use \code{$listener} on the
 #'     socket, which returns a list of Listener objects. To access any individual

R/methods.R

@@ -13,7 +13,7 @@
 #'     action will be taken.
 #' @param ... not used.
 #'
-#' @return Zero (invisibly) on success.
+#' @return Invisibly, an integer exit code (zero on success).
 #'
 #' @name start
 #' @rdname start
@@ -61,7 +61,7 @@ start.nanoDialer <- function(x, async = TRUE, ...) {
 #' @param con a Socket, Context, Dialer or Listener.
 #' @param ... not used.
 #'
-#' @return Zero (invisibly) on success.
+#' @return Invisibly, an integer exit code (zero on success).
 #'
 #' @details Closing an object explicitly frees its resources. An object can also
 #'     be removed directly in which case its resources are freed when the object

R/opts.R

@@ -11,7 +11,7 @@
 #'     See \link{opts}.
 #' @param value value of option.
 #'
-#' @return Zero (invisibly) on success.
+#' @return Invisibly, an integer exit code (zero on success).
 #'
 #' @details Note: once a dialer or listener has started, it is not generally
 #'     possible to change its configuration. Hence create the dialer or listener

R/sendrecv.R

@@ -17,7 +17,8 @@
 #'     sent data. Set to FALSE for performance-critical applications where zero
 #'     will be returned (invisibly) instead.
 #'
-#' @return Raw vector of sent data, or zero (invisibly) if 'echo' is set to FALSE.
+#' @return Raw vector of sent data, or (invisibly) an integer exit code (zero on
+#'     success) if 'echo' is set to FALSE.
 #'
 #' @examples
 #' pub <- socket("pub", dial = "inproc://nanonext")
@@ -56,12 +57,15 @@ send <- function(socket,
 #' @param timeout in ms. If unspecified, a socket-specific default timeout will
 #'     be used.
 #'
-#' @return A send Aio (object of class 'sendAio').
+#' @return A 'sendAio' (object of class 'sendAio').
 #'
-#' @details Async send is always non-blocking and returns immediately.
+#' @details Async send is always non-blocking and returns a 'sendAio'
+#'     immediately.
 #'
-#'     The send result is available at \code{$result}, which will return an
-#'     'unresolved' logical NA if the async operation is yet to complete.
+#'     For a 'sendAio', the send result is available at \code{$result}. An
+#'     'unresolved' logical NA is returned if the async operation is yet to
+#'     complete, The resolved value will be zero on success, or else an integer
+#'     error code.
 #'
 #'     To wait for and check the result of the send operation, use
 #'     \code{\link{call_aio}} on the returned 'sendAio' object.
@@ -124,12 +128,17 @@ send_aio <- function(socket, data, mode = c("serial", "raw"), timeout) {
 #'     the converted data only.
 #'
 #' @return Named list of 2 elements: 'raw' containing the received raw vector
-#'     and 'data' containing the converted R object, or else the converted R
-#'     object if 'keep.raw' is set to FALSE.
+#'     and 'data' containing the converted object, or else the converted object
+#'     if 'keep.raw' is set to FALSE.
 #'
-#' @details In case of an error in unserialisation or data conversion, the
-#'     function will still return the received raw vector to allow the data to
-#'     be recovered.
+#' @details In case of an error, an integer 'errorValue' is returned (to be
+#'     distiguishable from an integer message value). This can be verified using
+#'     \code{\link{is_error_value}}.
+#'
+#'     If the raw data was successfully received but an error occurred in
+#'     unserialisation or data conversion (for example if the incorrect mode was
+#'     specified), the received raw vector will always be returned to allow for
+#'     the data to be recovered.
 #'
 #' @examples
 #' s1 <- socket("bus", listen = "inproc://nanonext")
@@ -179,19 +188,29 @@ recv <- function(socket,
 #' @inheritParams recv
 #' @inheritParams send_aio
 #'
-#' @return A recv Aio (object of class 'recvAio').
+#' @return A 'recvAio' (object of class 'recvAio').
 #'
-#' @details Async receive is always non-blocking and returns immediately.
+#' @details Async receive is always non-blocking and returns a 'recvAio'
+#'     immediately.
 #'
-#'     The received message is available at \code{$data}, and the raw message at
-#'     \code{$raw} (if kept). An 'unresolved' logical NA will be returned if the
-#'     async operation is yet to complete.
+#'     For a 'recvAio', the received message is available at \code{$data}, and
+#'     the raw message at \code{$raw} (if kept). An 'unresolved' logical NA is
+#'     returned if the async operation is yet to complete.
 #'
 #'     To wait for the async operation to complete and retrieve the received
 #'     message, use \code{\link{call_aio}} on the returned 'recvAio' object.
 #'
 #'     Alternatively, to stop the async operation, use \code{\link{stop_aio}}.
 #'
+#'     In case of an error, an integer 'errorValue' is returned (to be
+#'     distiguishable from an integer message value). This can be verified using
+#'     \code{\link{is_error_value}}.
+#'
+#'     If the raw data was successfully received but an error occurred in
+#'     unserialisation or data conversion (for example if the incorrect mode was
+#'     specified), the received raw vector will be stored at \code{$data} to
+#'     allow for the data to be recovered.
+#'
 #' @examples
 #' s1 <- socket("pair", listen = "inproc://nanonext")
 #' s2 <- socket("pair", dial = "inproc://nanonext")

R/socket.R

@@ -89,7 +89,7 @@ socket <- function(protocol = c("pair", "bus", "push", "pull", "req", "rep",
 #' @param topic [default NULL] a topic (given as a character string). The default
 #'     NULL subscribes to all topics.
 #'
-#' @return Zero (invisibly) on success.
+#' @return Invisibly, an integer exit code (zero on success).
 #'
 #' @details To use pub/sub the publisher must:
 #'     \itemize{
@@ -140,7 +140,7 @@ subscribe <- function(socket, topic = NULL) {
 #' @param topic [default NULL] a topic (given as a character string). The default
 #'     NULL unsubscribes from all topics (if all topics were previously subscribed).
 #'
-#' @return Zero (invisibly) on success.
+#' @return Invisibly, an integer exit code (zero on success).
 #'
 #' @details Note that if the topic was not previously subscribed to then an
 #'     'entry not found' error will result.
@@ -195,7 +195,7 @@ unsubscribe <- function(socket, topic = NULL) {
 #' @param socket a Socket or Context using the surveyor protocol.
 #' @param time the survey timeout in ms.
 #'
-#' @return Zero (invisibly) on success.
+#' @return Invisibly, an integer exit code (zero on success).
 #'
 #' @details After using this function, to start a new survey, the surveyor must:
 #'     \itemize{

R/utils.R

@@ -108,9 +108,9 @@ is_error_value <- function(x) inherits(x, "errorValue")
 #'     socket open etc. to stdout.}
 #'     }
 #'
-#' @return Invisible NULL, or if 'level' is not specified, the integer code of
-#'     the logging level. A confirmation is printed to the console (stdout) if
-#'     the logging level has changed.
+#' @return Invisible NULL. A confirmation is printed to the console (stdout) if
+#'     the logging level has changed. If the function is called with no arguments,
+#'     the integer code of the logging level is returned instead.
 #'
 #' @details The environment variable 'NANONEXT_LOG' is checked automatically on
 #'     package load and then cached for optimal performance. It is also checked