From 4fe872565fdd7b6bdd140be1bca62d9b42b3fb93 Mon Sep 17 00:00:00 2001
From: George Stagg <george.stagg@posit.co>
Date: Tue, 25 Jul 2023 10:01:43 +0100
Subject: [PATCH] docs: Tweak R API documentation

* Minor changes to titles/description of exported R functions in
  the file canvas.R.
* Add links to `Message`, `type` and `data` in the webr::canvas() function
  documentation.
---
 packages/webr/R/canvas.R            | 27 ++++++++++++++++++---------
 packages/webr/man/canvas.Rd         | 19 ++++++++++++-------
 packages/webr/man/canvas_install.Rd |  7 ++++---
 3 files changed, 34 insertions(+), 19 deletions(-)

diff --git a/packages/webr/R/canvas.R b/packages/webr/R/canvas.R
index 7323a89d..027f86b5 100644
--- a/packages/webr/R/canvas.R
+++ b/packages/webr/R/canvas.R
@@ -1,20 +1,25 @@
-#' Graphics device for webR HTML canvas element
+#' Graphics device for drawing to a HTML canvas element
 #'
 #' A graphics device that generates HTML canvas API calls and executes them on
 #' the worker thread using a JavaScript `OffscreenCanvas`. Once drawing has
 #' finished, a JavaScript `ImageBitmap` object is transmitted to the main webR
 #' thread for display.
 #'
-#' The resulting webR output messages are of type `Message` with the `type`
-#' property set as `'canvas'` and the `data` property populated with further
-#' details about the event that triggered the message.
+#' The resulting webR output messages are of type
+#' \href{./js/interfaces/WebRChan.CanvasMessage.html}{`CanvasMessage`}, with
+#' the \href{./js/interfaces/WebRChan.CanvasMessage.html#type}{`type`}
+#' property set as `'canvas'` and the
+#' \href{./js/interfaces/WebRChan.CanvasMessage.html#data}{`data`} property
+#' populated with further details about the event that triggered the message.
 #'
 #' When the graphics device creates a new page an output message is emitted with
-#' the `data` property set to `{ event: 'canvasNewPage' }`.
+#' the \href{./js/interfaces/WebRChan.CanvasMessage.html#data}{`data`}
+#' property set to `{ event: 'canvasNewPage' }`.
 #'
 #' When bitmap image data is sent to the main thread for display, a message is
-#' emitted with the the bitmap additionally included as part of the `data`
-#' property, `{ event: 'canvasImage', image: ImageBitmap }`.
+#' emitted with the the bitmap additionally included as part of the
+#' \href{./js/interfaces/WebRChan.CanvasMessage.html#data}{`data`} property,
+#' `{ event: 'canvasImage', image: ImageBitmap }`.
 #'
 #' A 2x scaling is used to improve the bitmap output visual quality. As such,
 #' the width and height of the HTML canvas element should be twice the width and
@@ -34,8 +39,12 @@ canvas <- function(width=504, height=504, pointsize=12, bg="transparent", ...) {
   .Call(ffi_dev_canvas, width, height, pointsize, bg)
 }
 
-#' Use the webR canvas device as the default graphics device
-#' @param ... Arguments to be passed to the canvas graphics device.
+#' Use the webR canvas graphics device
+#'
+#' Set R options so that the webR canvas graphics device is used as the default
+#' graphics device for new plots.
+#'
+#' @param ... Arguments to be passed to the graphics device.
 #' @export
 canvas_install <- function(...) {
   options(device = function() { webr::canvas(...) })
diff --git a/packages/webr/man/canvas.Rd b/packages/webr/man/canvas.Rd
index 9a8106b1..c13a5e30 100644
--- a/packages/webr/man/canvas.Rd
+++ b/packages/webr/man/canvas.Rd
@@ -2,7 +2,7 @@
 % Please edit documentation in R/canvas.R
 \name{canvas}
 \alias{canvas}
-\title{Graphics device for webR HTML canvas element}
+\title{Graphics device for drawing to a HTML canvas element}
 \usage{
 canvas(width = 504, height = 504, pointsize = 12, bg = "transparent", ...)
 }
@@ -24,16 +24,21 @@ finished, a JavaScript \code{ImageBitmap} object is transmitted to the main webR
 thread for display.
 }
 \details{
-The resulting webR output messages are of type \code{Message} with the \code{type}
-property set as \code{'canvas'} and the \code{data} property populated with further
-details about the event that triggered the message.
+The resulting webR output messages are of type
+\href{./js/interfaces/WebRChan.CanvasMessage.html}{\code{CanvasMessage}}, with
+the \href{./js/interfaces/WebRChan.CanvasMessage.html#type}{\code{type}}
+property set as \code{'canvas'} and the
+\href{./js/interfaces/WebRChan.CanvasMessage.html#data}{\code{data}} property
+populated with further details about the event that triggered the message.
 
 When the graphics device creates a new page an output message is emitted with
-the \code{data} property set to \code{{ event: 'canvasNewPage' }}.
+the \href{./js/interfaces/WebRChan.CanvasMessage.html#data}{\code{data}}
+property set to \code{{ event: 'canvasNewPage' }}.
 
 When bitmap image data is sent to the main thread for display, a message is
-emitted with the the bitmap additionally included as part of the \code{data}
-property, \verb{\{ event: 'canvasImage', image: ImageBitmap \}}.
+emitted with the the bitmap additionally included as part of the
+\href{./js/interfaces/WebRChan.CanvasMessage.html#data}{\code{data}} property,
+\verb{\{ event: 'canvasImage', image: ImageBitmap \}}.
 
 A 2x scaling is used to improve the bitmap output visual quality. As such,
 the width and height of the HTML canvas element should be twice the width and
diff --git a/packages/webr/man/canvas_install.Rd b/packages/webr/man/canvas_install.Rd
index bfb642f2..2ef1f04a 100644
--- a/packages/webr/man/canvas_install.Rd
+++ b/packages/webr/man/canvas_install.Rd
@@ -2,13 +2,14 @@
 % Please edit documentation in R/canvas.R
 \name{canvas_install}
 \alias{canvas_install}
-\title{Use the webR canvas device as the default graphics device}
+\title{Use the webR canvas graphics device}
 \usage{
 canvas_install(...)
 }
 \arguments{
-\item{...}{Arguments to be passed to the canvas graphics device.}
+\item{...}{Arguments to be passed to the graphics device.}
 }
 \description{
-Use the webR canvas device as the default graphics device
+Set R options so that the webR canvas graphics device is used as the default
+graphics device for new plots.
 }