Improve docs with an eye to passing initial CRAN checks

R/chat.R

@@ -13,6 +13,11 @@ NULL
 #'
 #' You should generally not create this object yourself,
 #' but instead call [chat_openai()] or friends instead.
+#'
+#' @return A Chat object
+#' @examplesIf elmer:::openai_key_exists()
+#' chat <- chat_openai(echo = TRUE)
+#' chat$chat("Tell me a funny joke")
 Chat <- R6::R6Class("Chat",
   public = list(
     #' @param provider A provider object.

R/content.R

@@ -2,11 +2,11 @@
 NULL
 
 #' Format contents into a textual representation
-#' 
+#'
 #' @description
 #' These generic functions can be use to convert [Turn] contents or [Content]
-#' objects into textual representations. 
-#' 
+#' objects into textual representations.
+#'
 #' * `contents_text()` is the most minimal and only includes [ContentText]
 #'   objects in the output.
 #' * `contents_markdown()` returns the text content (which it assumes to be
@@ -15,7 +15,7 @@ NULL
 #' * `contents_html()` returns the text content, converted from markdown to
 #'   HTML with [commonmark::markdown_html()], plus HTML representations of
 #'   images and other content types.
-#' 
+#'
 #' @examples
 #' turns <- list(
 #'   Turn("user", contents = list(
@@ -30,12 +30,12 @@ NULL
 #' if (rlang::is_installed("commonmark")) {
 #'   contents_html(turns[[1]])
 #' }
-#' 
+#'
 #' @param content The [Turn] or [Content] object to be converted into text.
 #'   `contents_markdown()` also accepts [Chat] instances to turn the entire
 #'   conversation history into markdown text.
 #' @param ... Additional arguments passed to methods.
-#' 
+#'
 #' @return A string of text, markdown or HTML.
 #' @export
 contents_text <- new_generic("contents_text", "content")
@@ -52,12 +52,14 @@ contents_markdown <- new_generic("contents_markdown", "content")
 #' Content types received from and sent to a chatbot
 #'
 #' @description
+#' Use these functions if you're writing a package that extends elmer and need
+#' to customise methods for various types of content. For normal use, see
+#' [content_image_url()] and friends.
+#'
 #' elmer abstracts away differences in the way that different [Provider]s
 #' represent various types of content, allowing you to more easily write
-#' code that works with any chatbot.
-#'
-#' This set of classes represents the various types of content that can be
-#' sent to and received from a provider:
+#' code that works with any chatbot. This set of classes represents types of
+#' content that can be either sent to and received from a provider:
 #'
 #' * `ContentText`: simple text (often in markdown format). This is the only
 #'   type of content that can be streamed live as it's received.
@@ -70,6 +72,12 @@ contents_markdown <- new_generic("contents_markdown", "content")
 #' * `ContentToolResult`: the result of calling the tool (sent by the user).
 #'
 #' @export
+#' @return S7 objects that all inherit from `Content`
+#' @examples
+#' Content()
+#' ContentText("Tell me a joke")
+#' ContentImageRemote("https://www.r-project.org/Rlogo.png")
+#' ContentToolRequest(id = "abc", name = "mean", arguments = list(x = 1:5))
 Content <- new_class("Content")
 
 method(contents_text, Content) <- function(content) {
@@ -128,7 +136,7 @@ ContentImageRemote <- new_class(
   parent = Content,
   properties = list(
     url = prop_string(),
-    detail = prop_string()
+    detail = prop_string(default = "")
   )
 )
 method(format, ContentImageRemote) <- function(x, ...) {

R/interpolate.R

@@ -13,6 +13,7 @@
 #' @param .envir Environment to evaluate `...` expressions in. Used when
 #'   wrapping in another function. See `vignette("wrappers", package = "glue")`
 #'   for more details.
+#' @return A \{glue\} string.
 #' @export
 #' @examples
 #' joke <- "You're a cool dude who loves to make jokes. Tell me a joke about {{topic}}."

R/provider-azure.R

@@ -24,6 +24,11 @@ NULL
 #' @inheritParams chat_openai
 #' @inherit chat_openai return
 #' @export
+#' @examples
+#' \dontrun{
+#' chat <- chat_azure(deployment_id = "gpt-4o-mini")
+#' chat$chat("Tell me three jokes about statisticians")
+#' }
 chat_azure <- function(endpoint = azure_endpoint(),
                        deployment_id,
                        api_version = NULL,

R/provider-bedrock.R

@@ -21,6 +21,11 @@ NULL
 #' @inherit chat_openai return
 #' @family chatbots
 #' @export
+#' @examples
+#' \dontrun{
+#' chat <- chat_bedrock()
+#' chat$chat("Tell me three jokes about statisticians")
+#' }
 chat_bedrock <- function(system_prompt = NULL,
                          turns = NULL,
                          model = NULL,

R/provider-claude.R

@@ -26,6 +26,9 @@ NULL
 #' @param max_tokens Maximum number of tokens to generate before stopping.
 #' @family chatbots
 #' @export
+#' @examplesIf elmer:::anthropic_key_exists()
+#' chat <- chat_claude()
+#' chat$chat("Tell me three jokes about statisticians")
 chat_claude <- function(system_prompt = NULL,
                             turns = NULL,
                             max_tokens = 4096,

R/provider-databricks.R

@@ -40,6 +40,11 @@
 #' @inheritParams chat_openai
 #' @inherit chat_openai return
 #' @export
+#' @examples
+#' \dontrun{
+#' chat <- chat_databricks()
+#' chat$chat("Tell me three jokes about statisticians")
+#' }
 chat_databricks <- function(workspace = databricks_workspace(),
                             system_prompt = NULL,
                             turns = NULL,

R/provider-gemini.R

@@ -18,6 +18,11 @@ NULL
 #' @inherit chat_openai return
 #' @family chatbots
 #' @export
+#' @examples
+#' \dontrun{
+#' chat <- chat_gemini()
+#' chat$chat("Tell me three jokes about statisticians")
+#' }
 chat_gemini <- function(system_prompt = NULL,
                             turns = NULL,
                             base_url = "https://generativelanguage.googleapis.com/v1beta/",

R/provider-github.R

@@ -18,6 +18,11 @@
 #' @export
 #' @inheritParams chat_openai
 #' @inherit chat_openai return
+#' @examples
+#' \dontrun{
+#' chat <- chat_github()
+#' chat$chat("Tell me three jokes about statisticians")
+#' }
 chat_github <- function(system_prompt = NULL,
                         turns = NULL,
                         base_url = "https://models.inference.ai.azure.com/",
@@ -30,6 +35,7 @@ chat_github <- function(system_prompt = NULL,
   check_installed("gitcreds")
 
   model <- set_default(model, "gpt-4o")
+  echo <- check_echo(echo)
 
   chat_openai(
     system_prompt = system_prompt,

R/provider-groq.R

@@ -14,14 +14,20 @@ NULL
 #' @export
 #' @family chatbots
 #' @inheritParams chat_openai
+#' @inherit chat_openai return
+#' @examples
+#' \dontrun{
+#' chat <- chat_groq()
+#' chat$chat("Tell me three jokes about statisticians")
+#' }
 chat_groq <- function(system_prompt = NULL,
-                          turns = NULL,
-                          base_url = "https://api.groq.com/openai/v1",
-                          api_key = groq_key(),
-                          model = NULL,
-                          seed = NULL,
-                          api_args = list(),
-                          echo = NULL) {
+                      turns = NULL,
+                      base_url = "https://api.groq.com/openai/v1",
+                      api_key = groq_key(),
+                      model = NULL,
+                      seed = NULL,
+                      api_args = list(),
+                      echo = NULL) {
 
   turns <- normalize_turns(turns, system_prompt)
   model <- set_default(model, "llama3-8b-8192")

R/provider-ollama.R

@@ -16,8 +16,14 @@
 #'   tried it with.
 #'
 #' @inheritParams chat_openai
+#' @inherit chat_openai return
 #' @family chatbots
 #' @export
+#' @examples
+#' \dontrun{
+#' chat <- chat_ollama(model = "llama3.2")
+#' chat$chat("Tell me three jokes about statisticians")
+#' }
 chat_ollama <- function(system_prompt = NULL,
                         turns = NULL,
                         base_url = "http://localhost:11434",
@@ -36,6 +42,7 @@ chat_ollama <- function(system_prompt = NULL,
       i = "Locally installed models: {.str {models}}."
     ))
   }
+  echo <- check_echo(echo)
 
   chat_openai(
     system_prompt = system_prompt,

R/provider-openai.R

@@ -49,6 +49,8 @@ NULL
 #'   What is the difference between a tibble and a data frame?
 #'   Answer with a bulleted list
 #' ")
+#'
+#' chat$chat("Tell me three funny jokes about statistcians")
 chat_openai <- function(system_prompt = NULL,
                             turns = NULL,
                             base_url = "https://api.openai.com/v1",

R/provider-perplexity.R

@@ -3,9 +3,9 @@
 #' @description
 #' Sign up at <https://www.perplexity.ai>.
 #'
-#' Perplexity AI is a platform for running LLMs that are capable of 
-#' searching the web in real-time to help them answer questions with 
-#' information that may not have been available when the model was 
+#' Perplexity AI is a platform for running LLMs that are capable of
+#' searching the web in real-time to help them answer questions with
+#' information that may not have been available when the model was
 #' trained.
 #'
 #' This function is a lightweight wrapper around [chat_openai()] with
@@ -18,14 +18,19 @@
 #'   variable.
 #' @inheritParams chat_openai
 #' @inherit chat_openai return
+#' @examples
+#' \dontrun{
+#' chat <- chat_perplexity()
+#' chat$chat("Tell me three jokes about statisticians")
+#' }
 chat_perplexity <- function(system_prompt = NULL,
-                                turns = NULL,
-                                base_url = "https://api.perplexity.ai/",
-                                api_key = perplexity_key(),
-                                model = NULL,
-                                seed = NULL,
-                                api_args = list(),
-                                echo = NULL) {
+                            turns = NULL,
+                            base_url = "https://api.perplexity.ai/",
+                            api_key = perplexity_key(),
+                            model = NULL,
+                            seed = NULL,
+                            api_args = list(),
+                            echo = NULL) {
 
   model <- set_default(model, "llama-3.1-sonar-small-128k-online")
 

R/provider-vllm.R

@@ -12,6 +12,11 @@ NULL
 #' @inheritParams chat_openai
 #' @inherit chat_openai return
 #' @export
+#' @examples
+#' \dontrun{
+#' chat <- chat_vllm("http://my-vllm.com")
+#' chat$chat("Tell me three jokes about statisticians")
+#' }
 chat_vllm <- function(base_url,
                       system_prompt = NULL,
                       turns = NULL,

R/provider.R

@@ -15,6 +15,9 @@ NULL
 #' @export
 #' @param base_url The base URL for the API.
 #' @param extra_args Arbitrary extra arguments to be included in the request body.
+#' @return An S7 Provider object.
+#' @examples
+#' Provider(base_url = "https://cool-models.com")
 Provider <- new_class(
   "Provider",
   properties = list(

R/shiny.R

@@ -13,6 +13,12 @@
 #'   to use the console.
 #' @export
 #' @returns (Invisibly) The input `chat`.
+#' @examples
+#' \dontrun{
+#' chat <- chat_claude()
+#' live_console(chat)
+#' live_browser(chat)
+#' }
 live_console <- function(chat, quiet = FALSE) {
   if (!is_interactive()) {
     cli::cli_abort("The chat console is only available in interactive mode.")

R/tokens.R

@@ -22,6 +22,9 @@ tokens_reset <- function() {
 #' have sent and recieved in the current session.
 #'
 #' @export
+#' @return A data frame
+#' @examples
+#' token_usage()
 token_usage <- function() {
   if (is.null(the$tokens)) {
     cli::cli_inform(c(x = "No recorded usage in this session"))

R/tools-def.R

@@ -19,6 +19,7 @@ NULL
 #'   function. Each element should be created by a [`type_*()`][type_boolean]
 #'   function.
 #' @export
+#' @return An S7 `ToolDef` object.
 #' @examplesIf elmer:::openai_key_exists()
 #'
 #' # First define the metadata that the model uses to figure out when to

R/turns.R

@@ -27,6 +27,9 @@ NULL
 #'   input and output tokens (respectively) used in this turn. Currently
 #'   only recorded for assistant turns.
 #' @export
+#' @return An S7 `Turn` object
+#' @examples
+#' Turn(role = "user", contents = list(ContentText("Hello, world!")))
 Turn <- new_class(
   "Turn",
   properties = list(

R/types.R

@@ -8,6 +8,10 @@ NULL
 #'
 #' @name Type
 #' @inheritParams type_boolean
+#' @return S7 objects inheriting from `Type`
+#' @examples
+#' TypeBasic(type = "boolean")
+#' TypeArray(items = TypeBasic(type = "boolean"))
 NULL
 
 Type <- new_class(

R/utils-S7.R

@@ -4,7 +4,7 @@ prop_string <- function(default = NULL, allow_null = FALSE, allow_na = FALSE) {
 
   new_property(
     class = if (allow_null) NULL | class_character else class_character,
-    default = default,
+    default = if (is.null(default) && !allow_null) quote(stop("Required")) else default,
     validator = function(value) {
       if (allow_null && is.null(value)) {
         return()