Caching documentation

[Steve Cumming]

In the vignette for Caching, many example code chunks contain something like this

system.time(outSimCached <- spades(Copy(mySim), cache = TRUE))

where the Copy function is apparently making a deep copy of mySim. The documentation should perhaps explain what this function is doing, as capital-C Cache is mentioned, but never capital-C Copy.

[Alex Chubaty]

`?Copy` leads to the documentation on this function, and is the standard way of accessing manuals in R.

That being said, it's probably worth mentioning why we cache the copy in the first place. I'll add a TO DO item. Thanks.

[Eliot McIntire]

All the *objects* in the simList are pass-by-reference because they are in an environment. That means that objects that are in your "mySim" are the same as the ones in your "mySimOut" ... if there are new objects during simulation, it is not a problem... but any inputs that exist in mySim that are modified during the simulation are modified in mySimOut & mySim ...  you don't get the original values of the inputs even if you look at the mySim.

[Steve Cumming]

Thank you. I think that would help people understand the rest of the Cache documentation better.

[Eliot McIntire]

?simInit -- 3rd sentence states that the objects are pass-by-reference

?Copy - 1st sentence states that all objects are pass-by-reference

Could you please indicate what we can say to make this more clear? It is understandable that one doesn't know why one would want a "deep copy", and that one may not know what "pass-by-reference" means. Please be specific.

Note: this is *not* a Cache issue per se. Cache makes this a little more complicated and the exact behaviour is subtle (and perhaps not fully tested/known). We implemented a non-deep copy approach by default so that the user had control of whether they copy large objects or not.