Merge branch 'f-#88-prose'

- Use markdown in documentation.

DESCRIPTION

@@ -24,6 +24,7 @@ License: LGPL (>= 2)
 LazyData: true
 Encoding: UTF-8
 BugReports: https://github.com/rstats-db/DBItest/issues
+Roxygen: list(markdown = TRUE)
 RoxygenNote: 5.0.1.9000
 VignetteBuilder: knitr
 Collate:

R/DBItest.R

@@ -1,8 +1,8 @@
 #' @details
-#' The two most important functions are \code{\link{make_context}} and
-#' \code{\link{test_all}}.  The former tells the package how to connect to your
+#' The two most important functions are [make_context()] and
+#' [test_all()].  The former tells the package how to connect to your
 #' DBI backend, the latter executes all tests of the test suite. More
-#' fine-grained test functions (all with prefix \code{test_}) are available.
+#' fine-grained test functions (all with prefix `test_`) are available.
 #'
 #' See the package's vignette for more details.
 #'

R/context.R

@@ -2,20 +2,20 @@
 #'
 #' Create a test context, set and query the default context.
 #'
-#' @param drv \code{[DBIDriver]}\cr An expression that constructs a DBI driver,
+#' @param drv `[DBIDriver]`\cr An expression that constructs a DBI driver,
 #'   like `SQLite()`.
-#' @param connect_args \code{[named list]}\cr Connection arguments (names and
+#' @param connect_args `[named list]`\cr Connection arguments (names and
 #'   values).
-#' @param set_as_default \code{[logical(1)]}\cr Should the created context be
+#' @param set_as_default `[logical(1)]`\cr Should the created context be
 #'   set as default context?
-#' @param tweaks \code{[DBItest_tweaks]}\cr Tweaks as constructed by the
-#'   \code{\link{tweaks}} function.
-#' @param ctx \code{[DBItest_context]}\cr A test context.
-#' @param name \code{[character]}\cr An optional name of the context which will 
+#' @param tweaks `[DBItest_tweaks]`\cr Tweaks as constructed by the
+#'   [tweaks()] function.
+#' @param ctx `[DBItest_context]`\cr A test context.
+#' @param name `[character]`\cr An optional name of the context which will 
 #'   be used in test messages.
-#' @return \code{[DBItest_context]}\cr A test context, for
-#'   \code{set_default_context} the previous default context (invisibly) or
-#'   \code{NULL}.
+#' @return `[DBItest_context]`\cr A test context, for
+#'   `set_default_context` the previous default context (invisibly) or
+#'   `NULL`.
 #'
 #' @rdname context
 #' @export

R/spec-connection-connect.R

@@ -1,7 +1,7 @@
 #' @template dbispec-sub-wip
 #' @format NULL
 #' @section Connection:
-#' \subsection{Construction: \code{dbConnect("DBIDriver")} and \code{dbDisconnect("DBIConnection", "ANY")}}{
+#' \subsection{Construction: `dbConnect("DBIDriver")` and `dbDisconnect("DBIConnection", "ANY")`}{
 spec_connection_connect <- list(
   #' Can connect and disconnect, connection object inherits from
   #'   "DBIConnection".

R/spec-connection-data-type.R

@@ -1,7 +1,7 @@
 #' @template dbispec-sub-wip
 #' @format NULL
 #' @section Connection:
-#' \subsection{\code{dbDataType("DBIConnection", "ANY")}}{
+#' \subsection{`dbDataType("DBIConnection", "ANY")`}{
 spec_connection_data_type <- list(
   #' SQL Data types exist for all basic R data types. dbDataType() does not
   #' throw an error and returns a nonempty atomic character

R/spec-connection-get-info.R

@@ -1,7 +1,7 @@
 #' @template dbispec-sub-wip
 #' @format NULL
 #' @section Connection:
-#' \subsection{\code{dbGetInfo("DBIConnection")} (deprecated)}{
+#' \subsection{`dbGetInfo("DBIConnection")` (deprecated)}{
 spec_connection_get_info <- list(
   #' Return value of dbGetInfo has necessary elements
   get_info_connection = function(ctx) {

R/spec-driver-class.R

@@ -4,7 +4,7 @@
 spec_driver_class <- list(
   inherits_from_driver = function(ctx) {
     #' Each DBI backend implements a \dfn{driver class},
-    #' which must be an S4 class and inherit from the \code{DBIDriver} class.
+    #' which must be an S4 class and inherit from the `DBIDriver` class.
     expect_s4_class(ctx$drv, "DBIDriver")
   },
 

R/spec-driver-constructor.R

@@ -9,11 +9,11 @@ spec_driver_constructor <- list(
     #' The backend must support creation of an instance of this driver class
     #' with a \dfn{constructor function}.
     #' By default, its name is the package name without the leading \sQuote{R}
-    #' (if it exists), e.g., \code{SQLite} for the \pkg{RSQLite} package.
+    #' (if it exists), e.g., `SQLite` for the \pkg{RSQLite} package.
     default_constructor_name <- gsub("^R", "", pkg_name)
 
     #' For the automated tests, the constructor name can be tweaked using the
-    #' \code{constructor_name} tweak.
+    #' `constructor_name` tweak.
     constructor_name <- ctx$tweaks$constructor_name %||% default_constructor_name
 
     #'
@@ -29,7 +29,7 @@ spec_driver_constructor <- list(
 
     #' that is callable without arguments.
     #' For the automated tests, unless the
-    #' \code{constructor_relax_args} tweak is set to \code{TRUE},
+    #' `constructor_relax_args` tweak is set to `TRUE`,
     if (!isTRUE(ctx$tweaks$constructor_relax_args)) {
       #' an empty argument list is expected.
       expect_that(constructor, arglist_is_empty())

R/spec-driver-data-type.R

@@ -1,9 +1,9 @@
 #' @template dbispec-sub
 #' @format NULL
 #' @section Driver:
-#' \subsection{\code{dbDataType("DBIDriver", "ANY")}}{
+#' \subsection{`dbDataType("DBIDriver", "ANY")`}{
 spec_driver_data_type <- list(
-  #' The backend can override the \code{\link[DBI]{dbDataType}} generic
+  #' The backend can override the [DBI::dbDataType()] generic
   #' for its driver class.
   data_type_driver = function(ctx) {
     #' This generic expects an arbitrary object as second argument
@@ -16,7 +16,7 @@ spec_driver_data_type <- list(
         expect_is(dbDataType(ctx$drv, .(value)), "character")
         #' with at least one character.
         expect_match(dbDataType(ctx$drv, .(value)), ".")
-        #' As-is objects (i.e., wrapped by \code{\link[base]{I}}) must be
+        #' As-is objects (i.e., wrapped by [base::I()]) must be
         #' supported and return the same results as their unwrapped counterparts.
         expect_identical(dbDataType(ctx$drv, I(.(value))),
                          dbDataType(ctx$drv, .(value)))
@@ -25,29 +25,29 @@ spec_driver_data_type <- list(
 
     #'
     #' To query the values returned by the default implementation,
-    #' run \code{example(dbDataType, package = "DBI")}.
+    #' run `example(dbDataType, package = "DBI")`.
     #' If the backend needs to override this generic,
     #' it must accept all basic R data types as its second argument, namely
     expect_driver_has_data_type <- function(value) {
       eval(bquote(
         expect_error(check_driver_data_type(.(value)), NA)))
     }
 
-    #' \code{\link[base]{logical}},
+    #' [base::logical()],
     expect_driver_has_data_type(logical(1))
-    #' \code{\link[base]{integer}},
+    #' [base::integer()],
     expect_driver_has_data_type(integer(1))
-    #' \code{\link[base]{numeric}},
+    #' [base::numeric()],
     expect_driver_has_data_type(numeric(1))
-    #' \code{\link[base]{character}},
+    #' [base::character()],
     expect_driver_has_data_type(character(1))
-    #' dates (see \code{\link[base]{Dates}}),
+    #' dates (see [base::Dates()]),
     expect_driver_has_data_type(Sys.Date())
-    #' date-time (see \code{\link[base]{DateTimeClasses}}),
+    #' date-time (see [base::DateTimeClasses()]),
     expect_driver_has_data_type(Sys.time())
-    #' and \code{\link[base]{difftime}}.
+    #' and [base::difftime()].
     expect_driver_has_data_type(Sys.time() - Sys.time())
-    #' It also must accept lists of \code{raw} vectors
+    #' It also must accept lists of `raw` vectors
     #' and map them to the BLOB (binary large object) data type.
     if (!isTRUE(ctx$tweaks$omit_blob_tests)) {
       expect_driver_has_data_type(list(raw(1)))

R/spec-driver-get-info.R

@@ -1,7 +1,7 @@
 #' @template dbispec-sub-wip
 #' @format NULL
 #' @section Driver:
-#' \subsection{\code{dbGetInfo("DBIDriver")} (deprecated)}{
+#' \subsection{`dbGetInfo("DBIDriver")` (deprecated)}{
 spec_driver_get_info <- list(
   #' Return value of dbGetInfo has necessary elements.
   get_info_driver = function(ctx) {

R/spec-meta-bind.R

@@ -1,7 +1,7 @@
 #' @template dbispec-sub-wip
 #' @format NULL
 #' @section Meta:
-#' \subsection{\code{dbBind("DBIResult")}}{
+#' \subsection{`dbBind("DBIResult")`}{
 spec_meta_bind <- list(
   #' Empty binding with check of
   #' return value.
@@ -92,7 +92,7 @@ spec_meta_bind <- list(
     })
   },
 
-  #' Binding of \code{NULL} values.
+  #' Binding of `NULL` values.
   bind_null = function(ctx) {
     with_connection({
       test_select_bind(
@@ -116,7 +116,7 @@ spec_meta_bind <- list(
     })
   },
 
-  #' Binding of timestamp values.
+  #' Binding of [POSIXct] timestamp values.
   bind_timestamp = function(ctx) {
     with_connection({
       data_in <- as.POSIXct(round(Sys.time()))
@@ -129,7 +129,7 @@ spec_meta_bind <- list(
     })
   },
 
-  #' Binding of \code{\link{POSIXlt}} timestamp values.
+  #' Binding of [POSIXlt] timestamp values.
   bind_timestamp_lt = function(ctx) {
     with_connection({
       data_in <- as.POSIXlt(round(Sys.time()))
@@ -370,13 +370,13 @@ BindTester <- R6::R6Class(
 
 #' Create a function that creates n placeholders
 #'
-#' For internal use by the \code{placeholder_format} tweak.
+#' For internal use by the `placeholder_format` tweak.
 #'
-#' @param pattern \code{[character(1)]}\cr Any character, optionally followed by \code{1} or \code{name}. Examples: \code{"?"}, \code{"$1"}, \code{":name"}
+#' @param pattern `[character(1)]`\cr Any character, optionally followed by `1` or `name`. Examples: `"?"`, `"$1"`, `":name"`
 #'
-#' @return \code{[function(n)]}\cr A function with one argument \code{n} that
-#'   returns a vector of length \code{n} with placeholders of the specified format.
-#'   Examples: \code{?, ?, ?, ...}, \code{$1, $2, $3, ...}, \code{:a, :b, :c}
+#' @return `[function(n)]`\cr A function with one argument `n` that
+#'   returns a vector of length `n` with placeholders of the specified format.
+#'   Examples: `?, ?, ?, ...`, `$1, $2, $3, ...`, `:a, :b, :c`
 #'
 #' @keywords internal
 make_placeholder_fun <- function(pattern) {

R/spec-meta-column-info.R

@@ -1,7 +1,7 @@
 #' @template dbispec-sub-wip
 #' @format NULL
 #' @section Meta:
-#' \subsection{\code{dbColumnInfo("DBIResult")}}{
+#' \subsection{`dbColumnInfo("DBIResult")`}{
 spec_meta_column_info <- list(
   #' Column information is correct.
   column_info = function(ctx) {

R/spec-meta-get-info-result.R

@@ -1,7 +1,7 @@
 #' @template dbispec-sub-wip
 #' @format NULL
 #' @section Meta:
-#' \subsection{\code{dbGetInfo("DBIResult")} (deprecated)}{
+#' \subsection{`dbGetInfo("DBIResult")` (deprecated)}{
 spec_meta_get_info_result <- list(
   #' Return value of dbGetInfo has necessary elements
   get_info_result = function(ctx) {

R/spec-meta-get-row-count.R

@@ -1,7 +1,7 @@
 #' @template dbispec-sub-wip
 #' @format NULL
 #' @section Meta:
-#' \subsection{\code{dbGetRowCount("DBIResult")}}{
+#' \subsection{`dbGetRowCount("DBIResult")`}{
 spec_meta_get_row_count <- list(
   #' Row count information is correct.
   row_count = function(ctx) {

R/spec-meta-get-rows-affected.R

@@ -1,7 +1,7 @@
 #' @template dbispec-sub-wip
 #' @format NULL
 #' @section Meta:
-#' \subsection{\code{dbGetRowsAffected("DBIResult")}}{
+#' \subsection{`dbGetRowsAffected("DBIResult")`}{
 spec_meta_get_rows_affected <- list(
   #' Information on affected rows is correct.
   rows_affected = function(ctx) {

R/spec-meta-get-statement.R

@@ -1,7 +1,7 @@
 #' @template dbispec-sub-wip
 #' @format NULL
 #' @section Meta:
-#' \subsection{\code{dbGetStatement("DBIResult")}}{
+#' \subsection{`dbGetStatement("DBIResult")`}{
 spec_meta_get_statement <- list(
   #' SQL query can be retrieved from the result.
   get_statement = function(ctx) {

R/spec-meta-is-valid-connection.R

@@ -1,7 +1,7 @@
 #' @template dbispec-sub-wip
 #' @format NULL
 #' @section Meta:
-#' \subsection{\code{dbIsValid("DBIConnection")}}{
+#' \subsection{`dbIsValid("DBIConnection")`}{
 spec_meta_is_valid_connection <- list(
   #' Only an open connection is valid.
   is_valid_connection = function(ctx) {

R/spec-meta-is-valid-result.R

@@ -1,7 +1,7 @@
 #' @template dbispec-sub-wip
 #' @format NULL
 #' @section Meta:
-#' \subsection{\code{dbIsValid("DBIResult")}}{
+#' \subsection{`dbIsValid("DBIResult")`}{
 spec_meta_is_valid_result <- list(
   #' Only an open result set is valid.
   is_valid_result = function(ctx) {

R/spec-result-fetch.R

@@ -1,7 +1,7 @@
 #' @template dbispec-sub-wip
 #' @format NULL
 #' @section Result:
-#' \subsection{\code{dbFetch("DBIResult")} and \code{dbHasCompleted("DBIResult")}}{
+#' \subsection{`dbFetch("DBIResult")` and `dbHasCompleted("DBIResult")`}{
 spec_result_fetch <- list(
   #' Single-value queries can be fetched.
   fetch_single = function(ctx) {

R/spec-result-get-query.R

@@ -3,7 +3,7 @@
 #' @template dbispec-sub-wip
 #' @format NULL
 #' @section Result:
-#' \subsection{\code{dbGetQuery("DBIConnection", "ANY")}}{
+#' \subsection{`dbGetQuery("DBIConnection", "ANY")`}{
 spec_result_get_query <- list(
   #' Single-value queries can be read with dbGetQuery
   get_query_single = function(ctx) {
@@ -27,7 +27,7 @@ spec_result_get_query <- list(
   },
 
   #' Empty single-column queries can be read with
-  #' \code{\link[DBI]{dbGetQuery}}. Not all SQL dialects support the query
+  #' [DBI::dbGetQuery()]. Not all SQL dialects support the query
   #' used here.
   get_query_empty_single_column = function(ctx) {
     with_connection({
@@ -61,7 +61,7 @@ spec_result_get_query <- list(
   },
 
   #' Empty multi-column queries can be read with
-  #' \code{\link[DBI]{dbGetQuery}}. Not all SQL dialects support the query
+  #' [DBI::dbGetQuery()]. Not all SQL dialects support the query
   #' used here.
   get_query_empty_multi_column = function(ctx) {
     with_connection({

R/spec-result-roundtrip.R

@@ -48,7 +48,7 @@ spec_result_roundtrip <- list(
   },
 
   #' Data conversion from SQL to R: logical. Optional, conflict with the
-  #' \code{data_logical_int} test.
+  #' `data_logical_int` test.
   data_logical = function(ctx) {
     with_connection({
       test_select(.ctx = ctx, con,
@@ -76,7 +76,7 @@ spec_result_roundtrip <- list(
   },
 
   #' Data conversion from SQL to R: logical (as integers). Optional,
-  #' conflict with the \code{data_logical} test.
+  #' conflict with the `data_logical` test.
   data_logical_int = function(ctx) {
     with_connection({
       test_select(.ctx = ctx, con,

R/spec-result-send-query.R

@@ -1,7 +1,7 @@
 #' @template dbispec-sub-wip
 #' @format NULL
 #' @section Result:
-#' \subsection{Construction: \code{dbSendQuery("DBIConnection")} and \code{dbClearResult("DBIResult")}}{
+#' \subsection{Construction: `dbSendQuery("DBIConnection")` and `dbClearResult("DBIResult")`}{
 spec_result_send_query <- list(
   #' Can issue trivial query, result object inherits from "DBIResult".
   trivial_query = function(ctx) {
@@ -13,7 +13,7 @@ spec_result_send_query <- list(
   },
 
   #' Return value, currently tests that the return value is always
-  #' \code{TRUE}, and that an attempt to close a closed result set issues a
+  #' `TRUE`, and that an attempt to close a closed result set issues a
   #' warning.
   clear_result_return = function(ctx) {
     with_connection({

R/spec-sql-list-fields.R

@@ -1,7 +1,7 @@
 #' @template dbispec-sub-wip
 #' @format NULL
 #' @section SQL:
-#' \subsection{\code{dbListFields("DBIConnection")}}{
+#' \subsection{`dbListFields("DBIConnection")`}{
 spec_sql_list_fields <- list(
   #' Can list the fields for a table in the database.
   list_fields = function(ctx) {

R/spec-sql-list-tables.R

@@ -1,7 +1,7 @@
 #' @template dbispec-sub-wip
 #' @format NULL
 #' @section SQL:
-#' \subsection{\code{dbListTables("DBIConnection")}}{
+#' \subsection{`dbListTables("DBIConnection")`}{
 spec_sql_list_tables <- list(
   #' Can list the tables in the database, adding and removing tables affects
   #' the list. Can also check existence of a table.

R/spec-sql-quote-identifier.R

@@ -1,7 +1,7 @@
 #' @template dbispec-sub-wip
 #' @format NULL
 #' @section SQL:
-#' \subsection{\code{dbQuoteIdentifier("DBIConnection")}}{
+#' \subsection{`dbQuoteIdentifier("DBIConnection")`}{
 spec_sql_quote_identifier <- list(
   #' Can quote identifiers that consist of letters only.
   quote_identifier = function(ctx) {