docs: blurb memoise package (closes #353)

coding-practices/benchmarking.qmd

@@ -542,6 +542,7 @@ n_iterations <- 1000
 
 - [`{bench}`](https://bench.r-lib.org/) - Accurate benchmarking
 - [`{profvis}`](https://profvis.r-lib.org/) - Interactive profiling
+- [`{memoise}`](https://memoise.r-lib.org/) - Function-call caching to eliminate repeated bottlenecks (@sec-memoise)
 - [Measuring Performance](https://adv-r.hadley.nz/perf-measure.html) chapter in Advanced R
 - [Improving Performance](https://adv-r.hadley.nz/perf-improve.html) chapter in Advanced R
 - [`{touchstone}`](https://github.com/lorenzwalthert/touchstone) - CI benchmarking with PR comments

coding-practices/r-lib-packages.qmd

@@ -209,8 +209,22 @@ This manual requires `{here}` for file paths (see @sec-here-package-practices).
 ### [`{memoise}`](https://memoise.r-lib.org/) {#sec-memoise}
 
 [`{memoise}`](https://memoise.r-lib.org/) adds memoisation (function-call caching) to R functions.
-Wrapping a function with `memoise()` causes it to cache results so repeated calls
-with the same arguments return the cached value instead of recomputing.
+Wrapping an expensive, pure function with `memoise::memoise()` causes it to cache computed return values
+in memory or on disk,
+so repeated calls with identical arguments return instantly from cache instead of recomputing.
+It supports multiple storage backends via the `cache` argument
+(such as `cachem::cache_mem()` for in-memory caching
+and `cachem::cache_disk()` for persistent disk caching across sessions),
+and provides `memoise::forget()` to clear caches,
+`memoise::is.memoised()` to test whether a function is memoised,
+and `memoise::has_cache()` to check whether specific arguments have cached results.
+Use `{memoise}` only for deterministic functions without side effects
+(such as pure mathematical evaluations,
+stable API queries,
+or idempotent data processing pipelines).
+Do not memoise stochastic simulation routines or functions that draw pseudorandom numbers;
+memoisation suppresses stochastic variation across calls with identical arguments,
+returning identical pseudorandom draws unless an explicit RNG seed argument is passed and sets the generator state deterministically.
 
 ### [`{scales}`](https://scales.r-lib.org/) {#sec-scales}