fix tests + add documentation (rstudio#14)

* fixes#10 fix tests

* remove str() and browser()

* documentation except correct/incorrect/is_rrect

* grader_args and learnr_args template docs, all docs up 🎉

* code review changes from barret

* minor doc fixes

.Rbuildignore

@@ -6,3 +6,5 @@
 ^pkgdown$
 ^\.travis\.yml$
 ^codecov\.yml$
+^man-roxygen$
+^\.lintr$

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: grader
 Type: Package
 Title: Tools for "grading" student exercises in learnr tutorials
-Version: 0.1.0
-Author@R: c(
+Version: 0.1.0.9001
+Authors@R: c(
   person("Garrett", "Grolemund", role = c("aut", "cre"), email = "[email protected]"),
   person("Barret", "Schloerke", role = c("aut"), email = "[email protected]"),
   person(family = "RStudio, Inc.", role = c("cph", "fnd")),

NAMESPACE

@@ -3,22 +3,18 @@
 export(add_tutorial)
 export(check_code)
 export(check_result)
-export(correct)
 export(get_code)
 export(get_solution_code)
 export(get_user_code)
 export(grade_learnr)
 export(graded)
 export(grading_demo)
-export(incorrect)
-export(is_rrect)
 export(random_encourage)
 export(random_praise)
 export(result)
 export(test)
 export(test_result)
 export(test_solutions)
-export(tests)
 export(view_tutorial)
 importFrom(rlang,"%||%")
 importFrom(utils,browseURL)

R/check_code.R

@@ -30,18 +30,18 @@
 #' @param incorrect A character string to display if the student answer matches
 #'   the solution code.
 #'   This character string will be run through \code{glue::\link[glue]{glue_data}} with \code{list(correct = FALSE, message = "<STRING>")} where message is the error found while comparing the user solution to the known solution.
-#' @param solution (Optional) solution code surrounded by \code{quote()},
-#'   \code{rlang::quo()}, or provided as a character string.
-#' @param user (Optional) student code to check against the solution surrounded
-#'   by \code{quote()}, \code{rlang::quo()}, or provided as a character string.
+#' @template grader_args
+#' @template learnr_args
 #'
-#' @return a \code{grader_result} structure from \code{\link{result}}.
-#'   If the student answer differs from the
-#'   solution code, the message will describe the first way that the answer
-#'   differs, and it will ask the student to try again. If the answer matches
-#'   the solution code, the message will be the content of the \code{success}
+#' @return a \code{grader_graded} structure from \code{\link{result}}.
+#'   An incorrect message will describe the first way that the answer differs,
+#'   the message will be the content of the \code{correct}
 #'   argument.
 #'
+#'
+#'
+#'
+#'
 #' @export
 #' @examples
 #' \dontrun{grading_demo()}

R/check_result.R

@@ -5,19 +5,15 @@
 #' If the user result exactly matches a known \code{result}, \code{check_result}
 #' returns the matching message value.
 #'
-#' @param results A \code{\link{results}} object that contains possible \code{\link{result}} values to compare against.
-#' @param correct A character string to display if the student answer matches
-#'   a known answer.
-#'   This character string will be run through \code{glue::\link[glue]{glue_data}} with \code{list(correct = TRUE, message = "<result message>")}. where message is the matched result message.
+#' @template correct
 #' @param incorrect A character string to display if the student answer matches
 #'   a known answer.
 #'   This character string will be run through \code{glue::\link[glue]{glue_data}} with \code{list(correct = FALSE, message = "<result message>")}. where message is the matched result message.
-#' @param empty_msg A character string to display as a message if the user code is NULL.
+#' @template grader_args
+#' @template learnr_args
 #' @param ... ignored
-#' @param user (Optional) student code to check against the \code{results} surrounded
-#'   by \code{quote()}, \code{rlang::quo()}, or provided as a character string.
 #'
-#' @return a \code{grader_result} structure from \code{\link{result}} containing a formatted \code{correct} or \code{incorrect} message.
+#' @return a \code{grader_graded} structure from \code{\link{result}} containing a formatted \code{correct} or \code{incorrect} message and whether or not a match was found.
 #'
 #' @export
 #' @examples
@@ -26,15 +22,13 @@ check_result <- function(
   ...,
   correct = "{paste0(random_praise(), if (nchar(message) > 0) \" \", message)}",
   incorrect = "{paste0(message, if(nchar(message) > 0) \" \", random_encourage())}",
-  empty_msg = "I did not notice a result. Does your code return one?",
   grader_args = list(), # provided by `grade_learnr`
   learnr_args = list() # provided by `grade_learnr`
 ) {
   results <- list(...)
   chkm8_item_class(results, "grader_result")
   chkm8_single_character(correct)
   chkm8_single_character(incorrect)
-  chkm8_single_character(empty_msg)
 
   if (!any(vapply(results, `[[`, logical(1), "correct"))) {
     stop("At least one correct result must be provided")
@@ -43,16 +37,19 @@ check_result <- function(
   user_answer <- learnr_args$last_value
 
   # init final answer as not found
-  final_result <- graded(correct = FALSE, "Answer not found")
+  final_result <- graded(correct = FALSE, NULL)
+  found_match <- FALSE
   for (resu in results) {
     if (identical(resu$x, user_answer)) {
       final_result <- resu
+      found_match <- TRUE
       break
     }
   }
 
   message <- glue::glue_data(
     list(
+      matched = found_match,
       correct = final_result$correct,
       message = final_result$message
     ),

R/grade_learnr.R

@@ -139,7 +139,8 @@ grade_learnr <- function(label = NULL,
       )
     }
   )
-  if (!checkmate::test_class(checked_result, "grader_result")) {
+
+  if (!checkmate::test_class(checked_result, "grader_graded")) {
     stop("`grade_learnr` should receive a `graded` value from every `-check` chunk")
   }
 

R/result.R

@@ -23,10 +23,14 @@ result <- function(x, message = NULL, correct = FALSE) {
 }
 
 
-# TODO-document
-# Should be what EVERY check_* returns
+#' Graded submission value
+#'
+#'The return value from \code{graded} should be returned by every \code{*-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.
 #' @export
-graded <- function(message, correct) {
+graded <- function(correct, message = NULL) {
   chkm8_single_character(message)
   checkmate::expect_logical(correct, any.missing = FALSE, len = 1, null.ok = FALSE)
 

R/test_result.R

@@ -3,7 +3,6 @@
 #' \code{test_result()} executes tests against the final result of the user code.
 #' If a test throws an error, the test fails and the submitted answer will be marked incorrect.
 #'
-#' @param tests A \code{\link{tests}} object that contains all \code{\link{test}} functions to check the user's result.
 #' @param correct A character string to display if all tests pass.
 #'   This character string will be run through \code{glue::\link[glue]{glue_data}} with
 #' \itemize{
@@ -18,13 +17,12 @@
 #'   \item \code{num_total}: Number of tests
 #'   \item \code{errors}: Vector of errors found
 #' }
-#' @param empty_msg A character string to display as a message if the user code is NULL.
+#' @template grader_args
+#' @template learnr_args
 #' @param ... ignored
-#' @param user (Optional) student code to check against the \code{results} surrounded
-#'   by \code{quote()}, \code{rlang::quo()}, or provided as a character string.
 #'
-#' @return a \code{grader_result} structure from \code{\link{result}} containing a formatted \code{correct} or \code{incorrect} message.
-#' @seealso \code{tests}, \code{test}
+#' @return a \code{grader_graded} structure from \code{\link{result}} containing a formatted \code{correct} or \code{incorrect} message.
+#' @seealso \code{test}
 #' @export
 #' @examples
 #' \dontrun{grading_demo()}
@@ -36,19 +34,15 @@ test_result <- function(
     "Fix this first: '{errors[1]}'. ",
     "{random_encourage()}"
   ),
-  empty_msg = "I did not notice a result. Does your code return one?",
   grader_args = list(), # provided by `grade_learnr`
   learnr_args = list() # provided by `grade_learnr`
 ) {
-  chkm8_item_class(tests, "grader_test")
+  tests <- grader_tests(...)
+  chkm8_class(tests, "grader_tests")
   chkm8_single_character(correct)
   chkm8_single_character(incorrect)
-  chkm8_single_character(empty_msg)
 
-  user_answer <- get_user_code(user)
-  if (is.null(user_answer)) {
-    return(graded(correct = FALSE, message = empty_msg))
-  }
+  user_answer <- get_user_code(grader_args$user_quo)
 
   results <- lapply(tests$fns, function(test_fn) {
     tryCatch(
@@ -94,7 +88,7 @@ test_result <- function(
 #'
 #' Collect a set of test to execute against a user's result value
 #' @param ... a set of functions that will accept the evaluated user solution. If the test fails, it should throw an error with the message to display.
-#' @export
+#' @noRd
 #' @rdname test
 #' @examples
 #'
@@ -118,7 +112,7 @@ test_result <- function(
 #' )
 #'
 #' \dontrun{grading_demo()}
-tests <- function(...) {
+grader_tests <- function(...) {
   fns <- list(...)
   lapply(fns, function(fn) {
     checkmate::assert_function(fn)
@@ -133,6 +127,7 @@ tests <- function(...) {
     )
   )
 }
+#' TODO document with 'tests' documentation
 #' @export
 #' @rdname test
 #' @param message Message to report back if the test throws an error.

man-roxygen/correct.R

@@ -0,0 +1,4 @@
+#' @param correct A character string to display if the student answer matches
+#'   a known answer.
+#'   This character string will be run through \code{glue::\link[glue]{glue_data}} with \code{list(correct = TRUE, message = "<result message>")}. where message is the matched result message.
+#'   \code{matched} is a boolean value about whether the submitted is found in a set of provided values.

man-roxygen/grader_args.R

@@ -0,0 +1,4 @@
+#' @param grader_args A list of parameters passed to \code{grader} functions (provided by \code{grade_learnr}).  This contains: \describe{
+#'    \item{\code{user_quo}}{Quoted R code submitted by the user.  Ex: \code{rlang::\link[rlang]{quo}(1)} }
+#'    \item{\code{solution_quo}}{[Optional] Quoted solution R code provided by the \code{*-solution} chunk for an exercise.}
+#'   }

man-roxygen/learnr_args.R

@@ -0,0 +1 @@
+#' @param learnr_args A list of all parameters passed to \code{\link{grade_learnr}} by \code{learnr}. See \url{https://rstudio.github.io/learnr/exercises.html#exercise_checking} for more details.