Skip to content

Add doctests for Eval (closes #2479 in part)#4864

Open
MavenRain wants to merge 1 commit into
typelevel:mainfrom
MavenRain:eval-doctests
Open

Add doctests for Eval (closes #2479 in part)#4864
MavenRain wants to merge 1 commit into
typelevel:mainfrom
MavenRain:eval-doctests

Conversation

@MavenRain
Copy link
Copy Markdown

Partially closes #2479.

Eval.scala had zero existing doctests despite Eval being the lazy /
memoized FP-flagship data type in cats. This PR adds scaladoc examples to
seven Eval methods:

  • Eval#map, Eval#flatMap — basic mapping and chaining.
  • Eval#memoize — confirms Always.memoize does not re-evaluate on repeated
    .value.
  • Eval.now — eager evaluation.
  • Eval.later — lazy with memoization; counter increments once across
    multiple .value calls.
  • Eval.always — lazy without memoization; counter increments per .value
    call.
  • Eval.defer — computation deferred until .value is forced.

The Later, Always, memoize, and defer examples use the var counter = 0 plus side-effecting block pattern already established in Defer.scala:39
and FlatMap.scala:88, to demonstrate the eager vs lazy-memoized vs
lazy-not-memoized distinction at the doctest assertion level.

Local validation

  • ++ 2.13; coreJVM/test 916 / 916 pass (16 newly generated EvalDoctest
    assertions included).
  • ++ 3; coreJVM/compile coreJVM/test clean (doctest generation is 2.13-only
    per build.sbt:59).
  • scalafmtCheckAll clean.
  • scalafmtSbtCheck clean.
  • coreJVM/mimaReportBinaryIssues no binary issues.

A note for future Eval doctest authors

sbt-doctest silently skips scala> lines that contain a brace-lambda with a
;-separated body (e.g. Eval.now(1).map { x => mutate; x + 2 }). I caught
this on the first pass when map.example was missing from the test report
despite 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.

  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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add doctests (excellent first-time issue)

1 participant