FIFO and Unix Sockets docs improvements

- add NEWS
- add 'experimental' lifecycle badges
- comment on sockets being better
- link to internal vignette

Author: gaborcsardi

NEWS.md

@@ -1,6 +1,11 @@
 
 # processx development version
 
+* New functions for creating portable FIFOs and Unix socket connections.
+  See `conn_create_fifo()`, `conn_create_unix_socket()` and
+  `vignettes/internals.Rmd` for documentation. These functions are currently
+  experimental.
+
 # processx 3.6.1
 
 * processx now closes file unneeded file descriptors when redirecting

R/connections.R

@@ -29,6 +29,9 @@ conn_create_fd <- function(fd, encoding = "", close = TRUE) {
 
 #' Processx FIFOs
 #'
+#' @description
+#' `r lifecycle::badge("experimental")`
+#'
 #' Create a FIFO for inter-process communication
 #' Note that these functions are currently experimental.
 #'
@@ -42,6 +45,9 @@ conn_create_fd <- function(fd, encoding = "", close = TRUE) {
 #'
 #' # Notes
 #'
+#' ## In general Unix domain sockets work better than FIFOs, so we suggest
+#' you use sockets if you can. See [conn_create_unix_socket()].
+#'
 #' ## Creating the read end of the FIFO
 #'
 #' This case is simpler. To wait for a writer to connect to the FIFO
@@ -81,6 +87,8 @@ conn_create_fd <- function(fd, encoding = "", close = TRUE) {
 #' [poll()], especially on Windows. We might remove this option in the
 #' future and make all FIFOs non-blocking.
 #'
+#' @seealso [processx internals](https://processx.r-lib.org/dev/articles/internals.html)
+#'
 #' @rdname processx_fifos
 #' @export
 
@@ -488,11 +496,15 @@ is_valid_fd <- function(fd) {
 
 #' Unix domain sockets
 #'
+#' @description
+#' `r lifecycle::badge("experimental")`
+#'
 #' Cross platform point-to-point inter-process communication with
 #' Unix=domain sockets, implemented via named pipes on Windows.
 #' These connection are always bidirectional, i.e. you can read from them
 #' and also write to them.
 #'
+#' @details
 #' `conn_create_unix_socket()` creates a server socket. The new socket
 #' is listening at `filename`. See `filename` above.
 #'
@@ -524,6 +536,8 @@ is_valid_fd <- function(fd) {
 #' @param con Connection. An error is thrown if not a socket connection.
 #' @return A new socket connection.
 #'
+#' @seealso [processx internals](https://processx.r-lib.org/dev/articles/internals.html)
+#'
 #' @rdname processx_sockets
 #' @export