Add doctests for Eval (closes #2479 in part)#4864
Open
MavenRain wants to merge 1 commit into
Open
Conversation
Eval.scala had zero existing doctests despite being the lazy / memoized FP-flagship data type in cats. Adds scaladoc examples for Eval#map, Eval#flatMap, Eval#memoize, Eval.now, Eval.later, Eval.always, and Eval.defer. The Later, Always, memoize, and defer examples use the `var` + side-effecting block pattern (precedent in Defer.scala and FlatMap.scala) to demonstrate the eager vs lazy-memoized vs lazy-not-memoized distinction. Signed-off-by: Onyeka Obi <softwareengineerasaservant@isurvivable.cv>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Partially closes #2479.
Eval.scalahad zero existing doctests despiteEvalbeing the lazy /memoized FP-flagship data type in cats. This PR adds scaladoc examples to
seven
Evalmethods:Eval#map,Eval#flatMap— basic mapping and chaining.Eval#memoize— confirmsAlways.memoizedoes not re-evaluate on repeated.value.Eval.now— eager evaluation.Eval.later— lazy with memoization; counter increments once acrossmultiple
.valuecalls.Eval.always— lazy without memoization; counter increments per.valuecall.
Eval.defer— computation deferred until.valueis forced.The
Later,Always,memoize, anddeferexamples use thevar counter = 0plus side-effecting block pattern already established inDefer.scala:39and
FlatMap.scala:88, to demonstrate the eager vs lazy-memoized vslazy-not-memoized distinction at the doctest assertion level.
Local validation
++ 2.13; coreJVM/test916 / 916 pass (16 newly generatedEvalDoctestassertions included).
++ 3; coreJVM/compile coreJVM/testclean (doctest generation is 2.13-onlyper
build.sbt:59).scalafmtCheckAllclean.scalafmtSbtCheckclean.coreJVM/mimaReportBinaryIssuesno binary issues.A note for future Eval doctest authors
sbt-doctestsilently skipsscala>lines that contain a brace-lambda with a;-separated body (e.g.Eval.now(1).map { x => mutate; x + 2 }). I caughtthis on the first pass when
map.examplewas missing from the test reportdespite being a valid scaladoc block. The workaround is to either avoid
;(use parens-lambda + a helper
def) or to keep the example brace-lambda-free.