Improve/fix docstring for VarName (#213)

Couple of improvements in line with TuringLang/Turing.jl#1527.

Author: phipsgabler

Project.toml

@@ -1,6 +1,6 @@
 name = "DynamicPPL"
 uuid = "366bfd00-2699-11ea-058f-f148b4cae6d8"
-version = "0.10.6"
+version = "0.10.7"
 
 [deps]
 AbstractMCMC = "80f14c24-f653-4e6a-9b94-39d6b0f70001"

src/varname.jl

@@ -1,23 +1,30 @@
 """
-```
-struct VarName{sym, T<:Tuple}
-    indexing::T
-end
-```
+    VarName(sym[, indexing=()])
+
+A variable identifier for a symbol `sym` and indices `indexing` in the format
+returned by [`@vinds`](@ref).
+
+The Julia variable in the model corresponding to `sym` can refer to a single value or to a
+hierarchical array structure of univariate, multivariate or matrix variables. The field `indexing`
+stores the indices requires to access the random variable from the Julia variable indicated by `sym`
+as a tuple of tuples. Each element of the tuple thereby contains the indices of one indexing
+operation.
+
+`VarName`s can be manually constructed using the `VarName(sym, indexing)` constructor, or from an
+indexing expression through the [`@varname`](@ref) convenience macro.
+
+# Examples
 
-A variable identifier. Every variable has a symbol `sym` and indices `indexing` in the format
-returned by [`@vinds`](@ref).  The Julia variable in the model corresponding to `sym` can refer to a
-single value or to a hierarchical array structure of univariate, multivariate or matrix
-variables. `indexing` stores the indices that can access the random variable from the Julia
-variable.
+```jldoctest
+julia> vn = VarName(:x, ((Colon(), 1), (2,)))
+x[Colon(),1][2]
 
-Examples:
+julia> vn.indexing
+((Colon(), 1), (2,))
 
-- `x[1] ~ Normal()` will generate a `VarName` with `sym == :x` and `indexing == "((1,))"`.
-- `x[:,1] ~ MvNormal(zeros(2))` will generate a `VarName` with `sym == :x` and
- `indexing == ((Colon(), 1))"`.
-- `x[:,1][2] ~ Normal()` will generate a `VarName` with `sym == :x` and
- `indexing == ((Colon(), 1), (2,))`.
+julia> VarName(DynamicPPL.@vsym(x[:, 1][1+1]), DynamicPPL.@vinds(x[:, 1][1+1]))
+x[Colon(),1][2]
+```
 """
 struct VarName{sym, T<:Tuple}
     indexing::T
@@ -26,7 +33,7 @@ end
 VarName(sym::Symbol, indexing::Tuple = ()) = VarName{sym, typeof(indexing)}(indexing)
 
 """
-    VarName(vn::VarName, indexing)
+    VarName(vn::VarName[, indexing=()])
 
 Return a copy of `vn` with a new index `indexing`.
 """
@@ -131,8 +138,29 @@ _issubrange(i::Colon, j::ConcreteIndex) = true
 """
     @varname(expr)
 
-A macro that returns an instance of `VarName` given the symbol or expression of a Julia variable, 
-e.g. `@varname x[1,2][1+5][45][3]` returns `VarName{:x}(((1, 2), (6,), (45,), (3,)))`.
+A macro that returns an instance of [`VarName`](@ref) given a symbol or indexing expression `expr`.
+
+The `sym` value is taken from the actual variable name, and the index values are put appropriately
+into the constructor (and resolved at runtime).
+
+# Examples
+
+```jldoctest
+julia> @varname(x).indexing
+()
+
+julia> @varname(x[1]).indexing
+((1,),)
+
+julia> @varname(x[:, 1]).indexing
+((Colon(), 1),)
+
+julia> @varname(x[:, 1][2]).indexing
+((Colon(), 1), (2,))
+
+julia> @varname(x[1,2][1+5][45][3]).indexing
+((1, 2), (6,), (45,), (3,))
+```
 
 !!! compat "Julia 1.5"
     Using `begin` in an indexing expression to refer to the first index requires at least

test/Project.toml

@@ -4,6 +4,7 @@ Bijectors = "76274a88-744f-5084-9051-94815aaf08c4"
 Distributed = "8ba89e20-285c-5b6f-9357-94700520ee1b"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 DistributionsAD = "ced4e74d-a319-5a8a-b0ac-84af2272839c"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
 MCMCChains = "c7f686f2-ff18-58e9-bc7b-31028e88f75d"
 MacroTools = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09"
@@ -19,6 +20,7 @@ AbstractMCMC = "2.1"
 Bijectors = "0.8.2"
 Distributions = "0.24"
 DistributionsAD = "0.6.3"
+Documenter = "0.26.1"
 ForwardDiff = "0.10.12"
 MCMCChains = "4.0.4"
 MacroTools = "0.5.5"

test/runtests.jl

@@ -3,6 +3,7 @@ using AbstractMCMC
 using Bijectors
 using Distributions
 using DistributionsAD
+using Documenter
 using ForwardDiff
 using MacroTools
 using MCMCChains
@@ -59,4 +60,16 @@ include("test_util.jl")
             include(joinpath("turing", "runtests.jl"))
         end
     end
+
+    @testset "doctests" begin
+        DocMeta.setdocmeta!(
+            DynamicPPL,
+            :DocTestSetup,
+            quote
+            using DynamicPPL
+            end;
+            recursive=true,
+        )
+        doctest(DynamicPPL; manual=false)
+    end
 end