Rewrite VarInfo docstring

Author: penelopeysm

src/varinfo.jl

@@ -69,32 +69,57 @@ end
 ###########
 
 """
-```
-struct VarInfo{Tmeta, Tlogp} <: AbstractVarInfo
-    metadata::Tmeta
-    logp::Base.RefValue{Tlogp}
-    num_produce::Base.RefValue{Int}
-end
-```
+    struct VarInfo{Tmeta,Tlogp} <: AbstractVarInfo
+        metadata::Tmeta
+        logp::Base.RefValue{Tlogp}
+        num_produce::Base.RefValue{Int}
+    end
+
+A light wrapper over some kind of metadata.
 
-A light wrapper over one or more instances of `Metadata`. Let `vi` be an instance of
-`VarInfo`. If `vi isa VarInfo{<:Metadata}`, then only one `Metadata` instance is used
-for all the sybmols. `VarInfo{<:Metadata}` is aliased `UntypedVarInfo`. If
-`vi isa VarInfo{<:NamedTuple}`, then `vi.metadata` is a `NamedTuple` that maps each
-symbol used on the LHS of `~` in the model to its `Metadata` instance. The latter allows
-for the type specialization of `vi` after the first sampling iteration when all the
-symbols have been observed. `VarInfo{<:NamedTuple}` is aliased `NTVarInfo`.
+The type of the metadata can be one of a number of options. It may either be a
+`Metadata` or a `VarNamedVector`, _or_, it may be a `NamedTuple` which maps
+symbols to `Metadata` or `VarNamedVector` instances. Here, a _symbol_ refers
+to a Julia variable and may consist of one or more `VarName`s which appear on
+the left-hand side of tilde statements. For example, `x[1]` and `x[2]` both
+have the same symbol `x`.
 
-Note: It is the user's responsibility to ensure that each "symbol" is visited at least
-once whenever the model is called, regardless of any stochastic branching. Each symbol
-refers to a Julia variable and can be a hierarchical array of many random variables, e.g. `x[1] ~ ...` and `x[2] ~ ...` both have the same symbol `x`.
+Several type aliases are provided for these forms of VarInfos:
+- `VarInfo{<:Metadata}` is `UntypedVarInfo`
+- `VarInfo{<:VarNamedVector}` is `UntypedVectorVarInfo`
+- `VarInfo{<:NamedTuple}` is `NTVarInfo`
+
+The NamedTuple form, i.e. `NTVarInfo`, is useful for maintaining type stability
+of model evaluation. However, the element type of NamedTuples are not contained
+in its type itself: thus, there is no way to use the type system to determine
+whether the elements of the NamedTuple are `Metadata` or `VarNamedVector`.
+
+Note that for NTVarInfo, it is the user's responsibility to ensure that each
+symbol is visited at least once during model evaluation, regardless of any
+stochastic branching.
 """
 struct VarInfo{Tmeta,Tlogp} <: AbstractVarInfo
     metadata::Tmeta
     logp::Base.RefValue{Tlogp}
     num_produce::Base.RefValue{Int}
 end
 VarInfo(meta=Metadata()) = VarInfo(meta, Ref{LogProbType}(0.0), Ref(0))
+"""
+    VarInfo([rng, ]model[, sampler, context])
+
+Generate a `VarInfo` object for the given `model`, by evaluating it once using
+the given `rng`, `sampler`, and `context`.
+
+!!! warning
+
+    This function currently returns a `VarInfo` with its metadata field set to
+    a `NamedTuple` of `Metadata`. This is an implementation detail. In general,
+    this function may return any kind of object that satisfies the
+    `AbstractVarInfo` interface. If you require precise control over the type
+    of `VarInfo` returned, use the internal functions `untyped_varinfo`,
+    `typed_varinfo`, `untyped_vector_varinfo`, or `typed_vector_varinfo`
+    instead.
+"""
 function VarInfo(
     rng::Random.AbstractRNG,
     model::Model,