Tweak expectation() docs

To make it more clear this is not for developers. Fixes #2264.

Author: hadley

R/expectation.R

@@ -39,15 +39,17 @@ expect <- function(
   }
 }
 
-#' Construct an expectation object
+#' Expectation conditions
 #'
 #' @description
-#' For advanced use only. If you are creating your own expectation, you should
-#' call [pass()] or [fail()]. See `vignette("custom-expectation")` for more
-#' details.
+#' `new_expectation()` creates an expectation condition object and
+#' `exp_signal()` signals it. `expectation()` does both. `is.expectation()`
+#' tests if a captured condition is a testthat expectation.
 #'
-#' `new_expectation()` creates an expectation object and `exp_signal()` signals
-#' it. `expectation()` does both.
+#' These functions are primarily for internal use. If you are creating your
+#' own expectation, you do not need these functions are instead should use
+#' [pass()] or [fail()]. See `vignette("custom-expectation")` for more
+#' details.
 #'
 #' @param type Expectation type. Must be one of "success", "failure", "error",
 #'   "skip", "warning".