reflow docs for messenger, nano and ncurl

Author: shikokuchuo

R/messenger.R

@@ -22,32 +22,32 @@
 #' Messenger
 #'
 #' Multi-threaded, console-based, 2-way instant messaging system with
-#'     authentication, based on NNG scalability protocols.
+#' authentication, based on NNG scalability protocols.
 #'
-#' @param url a URL to connect to, specifying the transport and address as
-#'     a character string e.g. 'tcp://127.0.0.1:5555' (see \link{transports}).
+#' @param url a URL to connect to, specifying the transport and address as a
+#'   character string e.g. 'tcp://127.0.0.1:5555' (see \link{transports}).
 #' @param auth [default NULL] an R object (possessed by both parties) which
-#'     serves as a pre-shared key on which to authenticate the communication.
-#'     Note: the object is never sent, only a random subset of its md5 hash
-#'     after serialization.
+#'   serves as a pre-shared key on which to authenticate the communication.
+#'   Note: the object is never sent, only a random subset of its md5 hash after
+#'   serialization.
 #'
 #' @return Invisible NULL.
 #'
 #' @note The authentication protocol is an experimental proof of concept which
-#'     is not secure, and should not be used for critical applications.
+#'   is not secure, and should not be used for critical applications.
 #'
 #' @section Usage:
 #'
-#'     Type outgoing messages and hit return to send.
+#' Type outgoing messages and hit return to send.
 #'
-#'     The timestamps of outgoing messages are prefixed by \code{>} and that of
-#'     incoming messages by \code{<}.
+#' The timestamps of outgoing messages are prefixed by \code{>} and that of
+#' incoming messages by \code{<}.
 #'
-#'     \code{:q} is the command to quit.
+#' \code{:q} is the command to quit.
 #'
-#'     Both parties must supply the same argument for \sQuote{auth}, otherwise
-#'     the party trying to connect will receive an \sQuote{authentication error}
-#'     and be immediately disconnected.
+#' Both parties must supply the same argument for \sQuote{auth}, otherwise the
+#' party trying to connect will receive an \sQuote{authentication error} and be
+#' immediately disconnected.
 #'
 #' @export
 #'

R/nano.R

@@ -19,54 +19,53 @@
 #' Create Nano Object
 #'
 #' Create a nano object, encapsulating a Socket, Dialers/Listeners and
-#'     associated methods.
+#' associated methods.
+#'
+#' This function encapsulates a Socket, Dialer and/or Listener, and its
+#' associated methods.
+#'
+#' The Socket may be accessed by \code{$socket}, and the Dialer or Listener by
+#' \code{$dialer[[1]]} or \code{$listener[[1]]} respectively.
+#'
+#' The object's methods may be accessed by \code{$} e.g. \code{$send()} or
+#' \code{$recv()}. These methods mirror their functional equivalents, with the
+#' same arguments and defaults, apart from that the first argument of the
+#' functional equivalent is mapped to the object's encapsulated socket (or
+#' context, if active) and does not need to be supplied.
+#'
+#' More complex network topologies may be created by binding further dialers or
+#' listeners using the object's \code{$dial()} and \code{$listen()} methods. The
+#' new dialer/listener will be attached to the object e.g. if the object already
+#' has a dialer, then at \code{$dialer[[2]]} etc.
+#'
+#' Note that \code{$dialer_opt()} and \code{$listener_opt()} methods will be
+#' available once dialers/listeners are attached to the object. These methods
+#' get or apply settings for all dialers or listeners equally. To get or apply
+#' settings for individual dialers/listeners, access them directly via
+#' \code{$dialer[[2]]} or \code{$listener[[2]]} etc.
+#'
+#' The methods \code{$opt()}, and also \code{$dialer_opt()} or
+#' \code{$listener_opt()} as may be applicable, will get the requested option if
+#' a single argument 'name' is provided, and will set the value for the option
+#' if both arguments 'name' and 'value' are provided.
+#'
+#' For Dialers or Listeners not automatically started, the
+#' \code{$dialer_start()} or  \code{$listener_start()} methods will be
+#' available. These act on the most recently created Dialer or Listener
+#' respectively.
+#'
+#' For applicable protocols, new contexts may be created by using the
+#' \code{$context_open()} method. This will attach a new context at
+#' \code{$context} as well as a \code{$context_close()} method. While a context
+#' is active, all object methods use the context rather than the socket. A new
+#' context may be created by calling \code{$context_open()}, which will replace
+#' any existing context. It is only necessary to use \code{$context_close()} to
+#' close the existing context and revert to using the socket.
 #'
 #' @inheritParams socket
 #'
 #' @return A nano object of class \sQuote{nanoObject}.
 #'
-#' @details This function encapsulates a Socket, Dialer and/or Listener, and its
-#'     associated methods.
-#'
-#'     The Socket may be accessed by \code{$socket}, and the Dialer or
-#'     Listener by \code{$dialer[[1]]} or \code{$listener[[1]]} respectively.
-#'
-#'     The object's methods may be accessed by \code{$} e.g. \code{$send()} or
-#'     \code{$recv()}. These methods mirror their functional equivalents, with
-#'     the same arguments and defaults, apart from that the first argument of the
-#'     functional equivalent is mapped to the object's encapsulated socket (or
-#'     context, if active) and does not need to be supplied.
-#'
-#'     More complex network topologies may be created by binding further
-#'     dialers or listeners using the object's \code{$dial()} and \code{$listen()}
-#'     methods. The new dialer/listener will be attached to the object e.g. if
-#'     the object already has a dialer, then at \code{$dialer[[2]]} etc.
-#'
-#'     Note that \code{$dialer_opt()} and \code{$listener_opt()} methods
-#'     will be available once dialers/listeners are attached to the object.
-#'     These methods get or apply settings for all dialers or listeners equally.
-#'     To get or apply settings for individual dialers/listeners, access them
-#'     directly via \code{$dialer[[2]]} or \code{$listener[[2]]} etc.
-#'
-#'     The methods \code{$opt()}, and also \code{$dialer_opt()} or
-#'     \code{$listener_opt()} as may be applicable, will get the requested option
-#'     if a single argument 'name' is provided, and will set the value for the
-#'     option if both arguments 'name' and 'value' are provided.
-#'
-#'     For Dialers or Listeners not automatically started, the
-#'     \code{$dialer_start()} or  \code{$listener_start()} methods will be
-#'     available. These act on the most recently created Dialer or Listener
-#'     respectively.
-#'
-#'     For applicable protocols, new contexts may be created by using the
-#'     \code{$context_open()} method. This will attach a new context at
-#'     \code{$context} as well as a \code{$context_close()} method. While a
-#'     context is active, all object methods use the context rather than the
-#'     socket. A new context may be created by calling \code{$context_open()},
-#'     which will replace any existing context. It is only necessary to use
-#'     \code{$context_close()} to close the existing context and revert to using
-#'     the socket.
-#'
 #' @examples
 #' nano <- nano("bus", listen = "inproc://nanonext")
 #' nano

R/ncurl.R

@@ -22,31 +22,31 @@
 #'
 #' @param url the URL address.
 #' @param convert [default TRUE] logical value whether to attempt conversion of
-#'     the received raw bytes to a character vector. Set to FALSE if downloading
-#'     non-text data.
+#'   the received raw bytes to a character vector. Set to FALSE if downloading
+#'   non-text data.
 #' @param follow [default FALSE] logical value whether to automatically follow
-#'     redirects (not applicable for async requests). If FALSE, the redirect
-#'     address is returned as response header 'Location'.
+#'   redirects (not applicable for async requests). If FALSE, the redirect
+#'   address is returned as response header 'Location'.
 #' @param method (optional) the HTTP method as a character string. Defaults to
-#'     'GET' if not specified, and could also be 'POST', 'PUT' etc.
+#'   'GET' if not specified, and could also be 'POST', 'PUT' etc.
 #' @param headers (optional) a named character vector specifying the HTTP
-#'     request headers, for example: \cr
-#'     \code{c(Authorization = "Bearer APIKEY", `Content-Type` = "text/plain")}
-#'     \cr A non-character or non-named vector will be ignored.
+#'   request headers, for example: \cr
+#'   \code{c(Authorization = "Bearer APIKEY", `Content-Type` = "text/plain")}
+#'   \cr A non-character or non-named vector will be ignored.
 #' @param data (optional) character string request data to be submitted. If a
-#'     vector, only the first element is taken, and non-character objects are
-#'     ignored.
+#'   vector, only the first element is taken, and non-character objects are
+#'   ignored.
 #' @param response (optional) a character vector specifying the response headers
-#'     to return e.g. \code{c("date", "server")}. These are case-insensitive and
-#'     will return NULL if not present. A non-character vector will be ignored.
+#'   to return e.g. \code{c("date", "server")}. These are case-insensitive and
+#'   will return NULL if not present. A non-character vector will be ignored.
 #' @param timeout (optional) integer value in milliseconds after which the
-#'     transaction times out if not yet complete.
+#'   transaction times out if not yet complete.
 #' @param tls (optional) applicable to secure HTTPS sites only, a client TLS
-#'     Configuration object created by \code{\link{tls_config}}. If missing or
-#'     NULL, certificates are not validated.
+#'   Configuration object created by \code{\link{tls_config}}. If missing or
+#'   NULL, certificates are not validated.
 #'
 #' @return Named list of 3 elements:
-#'     \itemize{
+#'  \itemize{
 #'     \item \code{$status} - integer HTTP repsonse status code (200 - OK).
 #'     Use \code{\link{status_code}} for a translation of the meaning.
 #'     \item \code{$headers} - named list of response headers supplied in
@@ -57,10 +57,10 @@
 #'     'convert' = TRUE (may be further parsed as html, json, xml etc. as
 #'     required), or a raw byte vector if FALSE (use \code{\link{writeBin}} to
 #'     save as a file).
-#'     }
+#'  }
 #'
 #' @seealso \code{\link{ncurl_aio}} for asynchronous http requests;
-#'     \code{\link{ncurl_session}} for persistent connections.
+#'   \code{\link{ncurl_session}} for persistent connections.
 #' @examples
 #' ncurl("https://postman-echo.com/get",
 #'        convert = FALSE,
@@ -97,8 +97,8 @@ ncurl <- function(url,
 #' @inheritParams ncurl
 #'
 #' @return An 'ncurlAio' (object of class 'ncurlAio' and 'recvAio') (invisibly).
-#'     The following elements may be accessed:
-#'     \itemize{
+#'   The following elements may be accessed:
+#'   \itemize{
 #'     \item \code{$status} - integer HTTP repsonse status code (200 - OK).
 #'     Use \code{\link{status_code}} for a translation of the meaning.
 #'     \item \code{$headers} - named list of response headers supplied in
@@ -109,19 +109,18 @@ ncurl <- function(url,
 #'     'convert' = TRUE (may be further parsed as html, json, xml etc. as
 #'     required), or a raw byte vector if FALSE (use \code{\link{writeBin}} to
 #'     save as a file).
-#'     }
+#'   }
 #'
 #' @section Promises:
 #'
-#'     \sQuote{ncurlAio} may be used anywhere that accepts a \sQuote{promise}
-#'     from the \CRANpkg{promises} package through the included
-#'     \code{as.promise} method.
+#' \sQuote{ncurlAio} may be used anywhere that accepts a \sQuote{promise} from
+#' the \CRANpkg{promises} package through the included \code{as.promise} method.
 #'
-#'     The promises created are completely event-driven and non-polling.
+#' The promises created are completely event-driven and non-polling.
 #'
-#'     If a status code of 200 (OK) is returned then the promise is resolved
-#'     with the reponse body, otherwise it is rejected with a translation of the
-#'     status code or \sQuote{errorValue} as the case may be.
+#' If a status code of 200 (OK) is returned then the promise is resolved with
+#' the reponse body, otherwise it is rejected with a translation of the status
+#' code or \sQuote{errorValue} as the case may be.
 #'
 #' @seealso \code{\link{ncurl_session}} for persistent connections.
 #' @examples
@@ -159,16 +158,16 @@ ncurl_aio <- function(url,
 #' ncurl Session
 #'
 #' nano cURL - a minimalist http(s) client. A session encapsulates a connection,
-#'     along with all related parameters, and may be used to return data
-#'     multiple times by repeatedly calling \code{transact}, which transacts
-#'     once over the connection.
+#' along with all related parameters, and may be used to return data multiple
+#' times by repeatedly calling \code{transact}, which transacts once over the
+#' connection.
 #'
 #' @inheritParams ncurl
 #' @param timeout (optional) integer value in milliseconds after which the
-#'     connection and subsequent transact attempts time out.
+#'   connection and subsequent transact attempts time out.
 #'
 #' @return For \code{ncurl_session}: an 'ncurlSession' object if successful, or
-#'     else an 'errorValue'.
+#'   else an 'errorValue'.
 #'
 #' @seealso \code{\link{ncurl_aio}} for asynchronous http requests.
 #' @examples
@@ -194,7 +193,7 @@ ncurl_session <- function(url,
 #' @param session an 'ncurlSession' object.
 #'
 #' @return For \code{transact}: a named list of 3 elements:
-#'     \itemize{
+#'   \itemize{
 #'     \item \code{$status} - integer HTTP repsonse status code (200 - OK).
 #'     Use \code{\link{status_code}} for a translation of the meaning.
 #'     \item \code{$headers} - named list of response headers (if specified in
@@ -205,7 +204,7 @@ ncurl_session <- function(url,
 #'     'convert = TRUE' was specified for the session), which may be further
 #'     parsed as html, json, xml etc. as required, or else a raw byte vector,
 #'     which may be saved as a file using \code{\link{writeBin}}.
-#'     }
+#'   }
 #'
 #' @rdname ncurl_session
 #' @export
@@ -222,18 +221,17 @@ close.ncurlSession <- function(con, ...) invisible(.Call(rnng_ncurl_session_clos
 #'
 #' Creates a \sQuote{promise} from an \sQuote{ncurlAio} object.
 #'
-#' @param x an object of class \sQuote{ncurlAio}.
+#' This function is an S3 method for the generic \code{as.promise} for class
+#' \sQuote{ncurlAio}.
 #'
-#' @return A \sQuote{promise} object.
+#' Requires the \pkg{promises} package.
 #'
-#' @details This function is an S3 method for the generic \code{as.promise} for
-#'     class \sQuote{ncurlAio}.
+#' Allows an \sQuote{ncurlAio} to be used with the promise pipe \code{\%...>\%},
+#' which schedules a function to run upon resolution of the Aio.
 #'
-#'     Requires the \pkg{promises} package.
+#' @param x an object of class \sQuote{ncurlAio}.
 #'
-#'     Allows an \sQuote{ncurlAio} to be used with the promise pipe
-#'     \code{\%...>\%}, which schedules a function to run upon resolution of the
-#'     Aio.
+#' @return A \sQuote{promise} object.
 #'
 #' @exportS3Method promises::as.promise
 #'