fix docs

Author: penelopeysm

docs/src/api.md

@@ -438,13 +438,21 @@ DynamicPPL.varname_and_value_leaves
 
 ### Evaluation Contexts
 
-Internally, both sampling and evaluation of log densities are performed with [`AbstractPPL.evaluate!!`](@ref).
+Internally, model evaluation is performed with [`AbstractPPL.evaluate!!`](@ref).
 
 ```@docs
 AbstractPPL.evaluate!!
 ```
 
-The behaviour of a model execution can be changed with evaluation contexts that are passed as additional argument to the model function.
+This method mutates the `varinfo` used for execution.
+By default, it does not perform any actual sampling: it only evaluates the model using the values of the variables that are already in the `varinfo`.
+To perform sampling, you can either wrap `model.context` in a `SamplingContext`, or use this convenience method:
+
+```@docs
+DynamicPPL.sample!!
+```
+
+The behaviour of a model execution can be changed with evaluation contexts, which are a field of the model.
 Contexts are subtypes of `AbstractPPL.AbstractContext`.
 
 ```@docs

src/model.jl

@@ -794,22 +794,23 @@ julia> # Now `a.x` will be sampled.
 fixed(model::Model) = fixed(model.context)
 
 """
-    (model::Model)([rng[, varinfo]])
+    (model::Model)([rng, varinfo])
 
-Sample from the `model` using the `sampler` with random number generator `rng`
-and the `context`, and store the sample and log joint probability in `varinfo`.
+Sample from the prior of the `model` with random number generator `rng`.
 
 Returns the model's return value.
 
-If no arguments are provided, uses the default random number generator and
-samples from the prior.
+Note that calling this with an existing `varinfo` object will mutate it.
 """
+(model::Model)() = model(Random.default_rng(), VarInfo())
+function (model::Model)(varinfo::AbstractVarInfo)
+    return model(Random.default_rng(), varinfo)
+end
+# ^ Weird Documenter.jl bug means that we have to write the two above separately
+# as it can only detect the `function`-less syntax.
 function (model::Model)(rng::Random.AbstractRNG, varinfo::AbstractVarInfo=VarInfo())
     return first(sample!!(rng, model, varinfo))
 end
-function (model::Model)(varinfo::AbstractVarInfo=VarInfo())
-    return model(Random.default_rng(), varinfo)
-end
 
 """
     use_threadsafe_eval(context::AbstractContext, varinfo::AbstractVarInfo)
@@ -853,10 +854,10 @@ end
 
 Evaluate the `model` with the given `varinfo`. If an extra context stack is
 provided, the model's context is inserted into that context stack. See
-[`combine_model_and_external_contexts`](@ref).
+`combine_model_and_external_contexts`.
 
 If multiple threads are available, the varinfo provided will be wrapped in a
-[`DynamicPPL.ThreadSafeVarInfo`](@ref) before evaluation.
+`ThreadSafeVarInfo` before evaluation.
 
 Returns a tuple of the model's return value, plus the updated `varinfo`
 (unwrapped if necessary).
@@ -871,6 +872,10 @@ end
 function AbstractPPL.evaluate!!(
     model::Model, varinfo::AbstractVarInfo, context::AbstractContext
 )
+    Base.depwarn(
+        "The `context` argument to evaluate!!(model, varinfo, context) is deprecated.",
+        :dynamicppl_evaluate_context,
+    )
     new_ctx = combine_model_and_external_contexts(model.context, context)
     model = contextualize(model, new_ctx)
     return evaluate!!(model, varinfo)