Docs to markdown per rstudio#68 by @andrie + Barret changes (rstudio#69)

* Use desc::reformat_fields() to reflow DESCRIPTION file

* Use roxygen markdown for comments, using roxygen2md::roxygen2md()

* Use @inheritParams instead of @template, for cleaner documentation and less duplication

* Convert remaining documentation entries to roxygen markdown; Reflow docs; Minor fixes.

* barret suggestions

* LaTeX stuly rlang::quo and build docs

* update link to rlang::eval_tidy

* fix link to glue::glue_data

* add magrittr pipe link

* add magrittr pipe links

* document

* fix conflicts with rebase master

DESCRIPTION

@@ -2,15 +2,28 @@ Package: gradethis
 Type: Package
 Title: Tools for "grading" student exercises in learnr tutorials
 Version: 0.1.0.9002
-Authors@R: c(
-  person("Daniel", "Chen", role = c("aut"), email = "[email protected]"),
-  person("Barret", "Schloerke", role = c("aut"), email = "[email protected]"),
-  person("Garrett", "Grolemund", role = c("ccp", "aut", "cre"), email = "[email protected]"),
-  person(family = "RStudio, Inc.", role = c("cph", "fnd")),
-  person(family = "Ajax.org B.V.", role=c("ctb", "cph"), comment= "Ace library")
-  )
-Description:
-  Pairing with the 'learnr' R package, 'gradethis' provides multiple methods to grade 'learnr' exercises.  To learn more about 'learnr' tutorials, please visit <http://rstudio.github.io/learnr/>.
+Authors@R: 
+    c(person(given = "Daniel",
+             family = "Chen",
+             role = "aut",
+             email = "[email protected]"),
+      person(given = "Barret",
+             family = "Schloerke",
+             role = "aut",
+             email = "[email protected]"),
+      person(given = "Garrett",
+             family = "Grolemund",
+             role = c("ccp", "aut", "cre"),
+             email = "[email protected]"),
+      person(family = "RStudio, Inc.",
+             role = c("cph", "fnd")),
+      person(family = "Ajax.org B.V.",
+             role = c("ctb", "cph"),
+             comment = "Ace library"))
+Description: Pairing with the 'learnr' R package,
+    'gradethis' provides multiple methods to grade 'learnr' exercises.  To
+    learn more about 'learnr' tutorials, please visit
+    <http://rstudio.github.io/learnr/>.
 License: GPL-3
 Encoding: UTF-8
 LazyData: true
@@ -23,6 +36,10 @@ Imports:
     checkmate,
     testthat
 Remotes:
-  rstudio/learnr
-URL: https://rstudio-education.github.io/gradethis/, https://rstudio.github.io/learnr/, https://github.com/rstudio-education/gradethis
-BugReports: https://github.com/rstudio-education/gradethis/issues
+    rstudio/learnr
+URL: https://rstudio-education.github.io/gradethis/,
+    https://rstudio.github.io/learnr/,
+    https://github.com/rstudio-education/gradethis
+BugReports: 
+    https://github.com/rstudio-education/gradethis/issues
+Roxygen: list(markdown = TRUE)

R/check_code.R

@@ -2,54 +2,71 @@
 #'
 #' Checks the code expression or the code result against a solution.
 #'
-#' \code{check_code()} compares student code to a solution (i.e. model code) and
+#' `check_code()` compares student code to a solution (i.e. model code) and
 #' describes the first way that the student code differs. If the student code
-#' exactly matches the solution, \code{check_code()} returns a customizable
-#' success message (\code{correct}). If the student code does not match the
-#' solution, a customizable incorrect message (\code{incorrect}) can also be
-#' provided.
+#' exactly matches the solution, `check_code()` returns a customizable success
+#' message (`correct`). If the student code does not match the solution, a
+#' customizable incorrect message (`incorrect`) can also be provided.
 #'
-#' \code{check_code()} provides a *strict* check in that the student code must
+#' `check_code()` provides a *strict* check in that the student code must
 #' exactly match the solution. It is not enough for the student code to be
 #' equivalent to the solution code (e.g. to return the same result as the
 #' solution).
 #'
-#' You can provide solution code for \code{check_code()} to use in two ways:
+#' You can provide solution code for `check_code()` to use in two ways:
 #'
 #' 1. Pass code as a character string or a quoted expression to the solution
-#' argument of \code{check_code()}
+#' argument of `check_code()`
 #'
 #' 2. Make a "-solution" code chunk for the exercise to be checked in a learnr
-#' document. There is no need to supply a solution argument for
-#' \code{check_code()} if you call it from the "-check" chunk of the same
-#' exercise. Likewise, there is no need to supply a student submitted code
-#' argument when you call \code{check_code()} from a learnr document (learnr
-#' will provide the code that the student submits when it runs
-#' \code{check_code()}.
+#' document. There is no need to supply a solution argument for `check_code()`
+#' if you call it from the "-check" chunk of the same exercise. Likewise, there
+#' is no need to supply a student submitted code argument when you call
+#' `check_code()` from a learnr document (learnr will provide the code that the
+#' student submits when it runs `check_code()`.
 #'
 #' For best results, name all arguments provided in the solution code.
 #'
-#' @template correct
-#' @template incorrect
-#' @template grader_args
-#' @template learnr_args
-#' @template glue_correct
-#' @template glue_incorrect
+#' @param correct A character string to display if the student answer matches a
+#'   known correct answer.
+#'
+#' @param incorrect A character string to display if the student answer matches
+#'   a known incorrect answer.
+#'
+#' @param grader_args A list of parameters passed to `grader` functions
+#'   (provided by [grade_learnr()]). This contains:
+#'
+#'   * `user_quo`: Quoted R code submitted by the user. For example
+#'   \code{\link[rlang:quo]{rlang::quo(1)}}
+#'
+#'   * `solution_quo`: (Optional) Quoted solution R code provided by the
+#'   `*-solution` chunk for an exercise.
+#'
+#' @param learnr_args A list of all parameters passed to [grade_learnr()] by
+#'   `learnr`. See
+#'   <https://rstudio.github.io/learnr/exercises.html#exercise_checking> for
+#'   more details.
+#'
+#' @param glue_correct A glue string that returns the final correct message
+#'   displayed. Defaults to `getOption("gradethis_glue_correct")`.
+#'
+#' @param glue_incorrect A glue string that returns the final incorrect message
+#'   displayed. Defaults to `getOption("gradethis_glue_incorrect")`.
+#'
 #' @param glue_pipe A glue string that returns the final message displayed when
-#'   the student uses a pipe, \code{$>$}. Defaults to
-#'   \code{getOption("gradethis_glue_pipe")}.
+#'   the student uses a pipe, `$>$`. Defaults to
+#'   `getOption("gradethis_glue_pipe")`.
 #'
-#' @return a \code{\link{graded}} object. An incorrect message will describe the
-#'   first way that the answer differs, the message will be the content of the
-#'   \code{glue_pipe} argument.
+#' @return a [graded()] object. An incorrect message will describe the first way
+#'   that the answer differs, the message will be the content of the `glue_pipe`
+#'   argument.
 #'
-#' @seealso \code{\link{check_code}}, \code{\link{check_result}}, and
-#'   \code{\link{test_result}}
+#' @seealso [check_code()], [check_result()], and [test_result()]
 #' @export
 #' @examples
 #' \dontrun{grading_demo()}
 #'
-#' # This is a manual example, see grading demo for learnr tutorial usage
+#' # This is a manual example, see grading demo for `learnr` tutorial usage
 #' y <- quote(sqrt(log(2)))
 #' z <- quote(sqrt(log(1)))
 #' check_code(grader_args = list(user_quo = y, solution_quo = z))

R/check_result.R

@@ -1,24 +1,18 @@
-
-#' Check result of exercise code
+#' Check result of exercise code.
+#'
+#' Compares the final result of the student code to known [pass_if()] and
+#' [fail_if()] [condition()]s. If the student result exactly matches a known
+#' case, returns the matching message value.
 #'
-#' \code{check_result()} compares the final result of the student code to known
-#' \code{\link{pass_if}} and \code{\link{fail_if}} \code{\link{condition}}s.
-#' If the student result exactly matches a known case, \code{check_result}
-#' returns the matching message value.
+#' @inheritParams check_code
 #'
-#' @param ... \code{\link{pass_if}} or \code{\link{fail_if}} \code{\link{condition}}s to check
-#' @template correct
-#' @template incorrect
-#' @template grader_args
-#' @template learnr_args
-#' @template glue_correct
-#' @template glue_incorrect
+#' @param ... [pass_if()] or [fail_if()] [condition()]s to check
 #'
-#' @return a \code{\link{graded}} object from either
-#'   \code{\link{pass_if}} or \code{\link{fail_if}} containing a formatted
-#'   \code{correct} or \code{incorrect} message and whether or not a match was found.
+#' @return a [graded()] object from either [pass_if()] or [fail_if()] containing
+#'   a formatted `correct` or `incorrect` message and whether or not a match was
+#'   found.
 #'
-#' @seealso \code{\link{check_code}}, \code{\link{check_result}}, and \code{\link{test_result}}
+#' @seealso [check_code()], [check_result()], and [test_result()]
 #' @export
 #' @examples
 #' \dontrun{grading_demo()}

R/condition.R

@@ -1,25 +1,33 @@
 #' Condition object
 #'
-#' Captures what the student passes into \code{\link{pass_if}} or \code{\link{fail_if}},
-#' figures out what type of object was passed into \code{x},
-#' and returns a \code{grader_condition} object that will be passed into
-#' \code{\link{evaluate_condition}}.
+#' Captures what the student passes into [pass_if()] or [fail_if()],
+#' figures out what type of object was passed into `x`,
+#' and returns a `grader_condition` object that will be passed into
+#' [evaluate_condition()].
+#'
+#' @param x A formula, function, or value, that returns `TRUE` or `FALSE`.
+#'    When comparing objects that are greater than length 1
+#'    (e.g., vectors, dataframes, matricies, etc)
+#'    A boolean vector will be returned if the user uses `==`, not a single boolean value.
+#'    `gradethis` will run the vector through
+#'     `all(..., na.rm = TRUE)` to check for the boolean value.
+#'    It is advised that the user use `identical()` instead of `==` in this case.
 #'
-#' @template x_condition
 #' @param message character string for message returned (usually passed in from
-#'    \code{\link{pass_if}} or \code{\link{fail_if}}
+#'    [pass_if()] or [fail_if()]
+#'
 #' @param correct logical whether the condition is the correct answer
 #'
-#' @return a \code{grader_condition} object that contains
-#'   the expression \code{x},
-#'   the message \code{message},
-#'   whether or not the expression is the correct answer or not, \code{correct},
-#'   the type of expression (formula, function, or value), \code{type}
+#' @return a `grader_condition` object that contains
+#'   the expression `x`,
+#'   the message `message`,
+#'   whether or not the expression is the correct answer or not, `correct`,
+#'   the type of expression (formula, function, or value), `type`
 #'
 #' @describeIn condition
 #'    A condition object that contains the expression, message,
 #'    correct status, and condition type
-#' @seealso \code{\link{pass_if}}, \code{\link{fail_if}}, and \code{\link{condition}}
+#' @seealso [pass_if()], [fail_if()], and [condition()]
 #' @export
 #'
 #' @examples

R/evaluate_condition.R

@@ -1,13 +1,13 @@
 #' Evaluates a condition
 #'
-#' Evaluates the \code{\link{condition}} object to return a \code{\link{graded}} value.
+#' Evaluates the [condition()] object to return a [graded()] value.
 #'
-#' @param condition a \code{\link{condition}} object
-#' @param grader_args at minimum, a list that just contains the value for \code{solution_quo}
-#' @param learnr_args at minimum, a list that just contains the value for \code{envir_prep}
+#' @param condition a [condition()] object
+#' @param grader_args at minimum, a list that just contains the value for `solution_quo`
+#' @param learnr_args at minimum, a list that just contains the value for `envir_prep`
 #'
-#' @return a \code{\link{graded}} value if \code{condi$x} is \code{TRUE} or
-#'   \code{NULL} if \code{condi$x} is \code{FALSE}
+#' @return a [graded()] value if `condi$x` is `TRUE` or
+#'   `NULL` if `condi$x` is `FALSE`
 #' @export
 #'
 #' @examples

R/get_code.R

@@ -1,11 +1,11 @@
 #' Get Code
 #'
-#' Helper methods around \code{rlang::\link[rlang]{eval_tidy}}
+#' Helper methods around [rlang::eval_tidy()]
 #' to extract user code and solution code.
 #'
-#' @seealso \code{\link{check_result}}, \code{\link{test_result}}, and \code{\link{check_code}}
+#' @seealso [check_result()], [test_result()], and [check_code()]
 #' @param user,solution,expr An expression or quosure to evaluate.
-#' @param name Name to print if a \code{NULL} expression is provided.
+#' @param name Name to print if a `NULL` expression is provided.
 #'
 #' @describeIn get_code Get student code
 #' @inheritParams rlang::eval_tidy

R/glue.R

@@ -1,6 +1,6 @@
 #' Generate Glue string from expression
 #'
-#' Checks and validates arguments passed into \code{glue} to generate messages to the student.
+#' Checks and validates arguments passed into `glue` to generate messages to the student.
 #'
 #' @param glue_expression A glue character expression string.
 #' @param ... Values to be inserted into glue expression.

R/grade_learnr.R

@@ -1,28 +1,28 @@
-#' A checker function to use with \code{learnr}
+#' A checker function to use with `learnr`
 #'
-#' For exercise checking, \code{learnr} tutorials require a function that
-#' \code{learnr} can use in the background to run the code in each "-check"
-#' chunk and to format the results into a format that \code{learnr} can display.
+#' For exercise checking, `learnr` tutorials require a function that
+#' `learnr` can use in the background to run the code in each "-check"
+#' chunk and to format the results into a format that `learnr` can display.
 #' The function must accept a specific set of inputs and return a specific type
-#' of output (see \code{\link{graded}}). Instructors are not intended to use the
-#' \code{grade_learnr} function directly, but to pass it to the
-#' \code{exercise.checker} knitr chunk option within the setup chunk of the
-#' \code{learnr} tutorial.
+#' of output (see [graded()]). Instructors are not intended to use the
+#' `grade_learnr` function directly, but to pass it to the
+#' `exercise.checker` knitr chunk option within the setup chunk of the
+#' `learnr` tutorial.
 #'
 #' To enable exercise checking in your learnr tutorial, set
-#' \code{tutorial_options(exercise.checker = grade_learnr)} in the setup chunk
+#' `tutorial_options(exercise.checker = grade_learnr)` in the setup chunk
 #' of your tutorial.
 #'
-#' Run \code{grading_demo()} to see an example learnr document that uses
-#' \code{grade_learnr()}.
+#' Run `grading_demo()` to see an example learnr document that uses
+#' `grade_learnr()`.
 #'
 #' @param label Label for exercise chunk
 #' @param solution_code Code provided within the “-solution” chunk for the
 #'   exercise.
 #' @param user_code R code submitted by the user
 #' @param check_code Code provided within the “-check” chunk for the exercise.
 #' @param envir_result The R environment after the execution of the chunk.
-#' @param evaluate_result The return value from the \code{evaluate::evaluate}
+#' @param evaluate_result The return value from the `evaluate::evaluate`
 #'   function.
 #' @param envir_prep A copy of the R environment before the execution of the
 #'   chunk.

R/graded.R

@@ -1,7 +1,7 @@
 #' Graded object for submission value
 #'
-#'The return value from \code{graded} should be returned by every
-#'\code{*-check} chunk when used with \code{link{grade_learnr}}.
+#'The return value from `graded` should be returned by every
+#'`*-check` chunk when used with \code{link{grade_learnr}}.
 #'
 #' @param message A character string of the message to be displayed.
 #' @param correct A boolean value of whether or not the checked code is correct.

R/grading_demo.R

@@ -1,20 +1,23 @@
 #' Grading Demo
 #'
-#' If you are using the RStudio IDE, \code{grading_demo()} opens an example learnr
+#' If you are using the RStudio IDE, `grading_demo()` opens an example learnr
 #' file that demonstrates how to use the grader package to check student code.
 #'
-#' The tutorial sets the learnr \code{exercise.checker} option to
-#' \code{grade_learnr()} in the document's setup chunk.
+#' The tutorial sets the learnr `exercise.checker` option to
+#' `grade_learnr()` in the document's setup chunk.
+#'
 #' It then uses three different exercise checking methods:
-#' \code{\link{check_result}}, \code{\link{test_result}}, and \code{\link{check_code}}.
+#' [check_result()], [test_result()], and [check_code()].
+#'
 #' To use a checking method, follow the exercise chunk with a chunk whose label
-#' matches the label of the exercise chunk (ex: \code{myexercise}) but includes the suffix
-#' \code{-check} (ex: \code{myexercise-check}). Call any checking method in that chunk.
+#' matches the label of the exercise chunk (ex: `myexercise`) but includes the suffix
+#' `-check` (ex: `myexercise-check`). Call any checking method in that chunk.
+#'
 #' To ensure that checking method can provide informative feedback,
-#' you may provide custom \code{correct} and \code{incorrect} messages.
+#' you may provide custom `correct` and `incorrect` messages.
 #'
 #' If you are not using RStudio IDE, you can access the demo file at
-#' \code{system.file("extdata", "grading-demo/grading-demo.Rmd", package = "grader")}.
+#' `system.file("extdata", "grading-demo/grading-demo.Rmd", package = "grader")`.
 #'
 #' @export
 #' @importFrom utils browseURL

R/order_calls.R

@@ -1,7 +1,7 @@
 #' Order calls
 #'
 #' Turns a quoted object into a list of symbols that would represent the call as
-#' a pipe if you placed a \code{\%>\%} between each element of the list. This
+#' a pipe if you placed a \code{\link[magrittr]{\%>\%}} between each element of the list. This
 #' let's checking code evaluate the elements in the same order that R would.
 #'
 #' @noRd

R/pass_fail_if.R

@@ -1,9 +1,9 @@
 #' Condition definition
 #'
-#' \code{pass_if} and \code{fail_if} are wrappers around \code{\link{condition}}
-#' that sets the proper \code{correct} argument.
-#' This allows the instructor to specify just the comparison code, \code{x},
-#' and \code{message}.
+#' `pass_if` and `fail_if` are wrappers around [condition()]
+#' that sets the proper `correct` argument.
+#' This allows the instructor to specify just the comparison code, `x`,
+#' and `message`.
 #'
 #' @describeIn condition
 #'    a condition that if matched means the student provided result is correct

R/praise.R

@@ -58,7 +58,7 @@
 #'
 #' Generate a random praise or encouragement phrase.
 #' This can be used in conjunction with
-#' \code{glue::\link[glue]{glue}} to generate praise or encouragement within feedback to users.
+#' `glue::[glue][glue::glue()]` to generate praise or encouragement within feedback to users.
 #'
 #' @examples
 #' replicate(5, glue::glue("Random praise: {random_praise()}"))