Add comments

doc/genrst.jl

@@ -42,9 +42,13 @@ to_gen = Dict(
     :title  =>  "Sampler",
     :list   =>  ["IS", "SMC", "PG", "HMC"]
   ),
-  "tarray" => Dict(
+  "tarrayapi" => Dict(
     :title  =>  "TArray",
     :list   =>  ["TArray", "tzeros"]
+  ),
+  "chainapi" => Dict(
+    :title  =>  "Chain",
+    :list   => ["Chain", "Sample"]
   )
 )
 
@@ -56,7 +60,7 @@ cd(joinpath(dirname(@__FILE__),"source")) do
       for api in to_gen[fname][:list]
         md = include_string("@doc $api")
         if isa(md,Markdown.MD)
-          isa(md.content[1].content[1],Markdown.Code) || error("Incorrect docstring format: $D")
+          isa(md.content[1].content[1],Markdown.Code) || error("Incorrect docstring format: $api")
 
           printrst(f,md)
         else

doc/source/chainapi.rst

@@ -0,0 +1,47 @@
+Chain
+=========
+
+.. function:: Chain(weight::Float64, value::Array{Sample})
+
+   A wrapper of output trajactory of samplers.
+
+   Example:
+
+   .. code-block:: julia
+
+       # Define a model
+       @model xxx begin
+         ...
+         @predict mu sigma
+       end
+
+       # Run the inference engine
+       chain = sample(xxx, SMC(1000))
+
+       chain[:logevidence]   # show the log model evidence
+       chain[:mu]            # show the weighted trajactory for :mu
+       chain[:sigma]         # show the weighted trajactory for :sigma
+       mean(chain[:mu])      # find the mean of :mu
+       mean(chain[:sigma])   # find the mean of :sigma
+
+.. function:: Sample(weight::Float64, value::Dict{Symbol,Any})
+
+   A wrapper of output samples.
+
+   Example:
+
+   .. code-block:: julia
+
+       # Define a model
+       @model xxx begin
+         ...
+         @predict mu sigma
+       end
+
+       # Run the inference engine
+       chain = sample(xxx, SMC(1000))
+
+       sample = chain[:mu][1]  # get the first sample
+       sample.weight           # show the weight of this sample
+       sample.value            # show the value of this sample (a dictionary)
+

doc/source/index.rst

@@ -16,8 +16,9 @@ Contents
 
    replayapi
    samplerapi
-   tarray
+   tarrayapi
    compilerapi
+   chainapi
 
 .. toctree::
    :maxdepth: 2

src/Turing.jl

@@ -24,7 +24,7 @@ StatsFuns.gammalogpdf(k::Real, θ::Real, x::Real) = -log(gamma(k)) - k * log(θ)
 ###########################################
 
 # Turing essentials - modelling macros and inference algorithms
-export @model, @assume, @observe, @predict, InferenceAlgorithm, HMC, IS, SMC, PG, sample
+export @model, @assume, @observe, @predict, InferenceAlgorithm, HMC, IS, SMC, PG, sample, Chain, Sample
 
 # Turing-safe data structures and associated functions
 export TArray, tzeros, localcopy, IArray

src/core/io.jl

@@ -1,16 +1,73 @@
-# Some utility functions for extracting results.
+#########################
+# Sampler I/O Interface #
+#########################
 
+##########
+# Sample #
+##########
+
+doc"""
+    Sample(weight::Float64, value::Dict{Symbol,Any})
+
+A wrapper of output samples.
+
+Example:
+
+```julia
+# Define a model
+@model xxx begin
+  ...
+  @predict mu sigma
+end
+
+# Run the inference engine
+chain = sample(xxx, SMC(1000))
+
+sample = chain[:mu][1]  # get the first sample
+sample.weight           # show the weight of this sample
+sample.value            # show the value of this sample (a dictionary)
+```
+"""
 type Sample
-  weight :: Float64 # particle weight
+  weight :: Float64     # particle weight
   value :: Dict{Symbol,Any}
 end
 
 Base.getindex(s::Sample, v::Symbol) = Base.getindex(s.value, v)
 
+#########
+# Chain #
+#########
+
+doc"""
+    Chain(weight::Float64, value::Array{Sample})
+
+A wrapper of output trajactory of samplers.
+
+Example:
+
+```julia
+# Define a model
+@model xxx begin
+  ...
+  @predict mu sigma
+end
+
+# Run the inference engine
+chain = sample(xxx, SMC(1000))
+
+chain[:logevidence]   # show the log model evidence
+chain[:mu]            # show the weighted trajactory for :mu
+chain[:sigma]         # show the weighted trajactory for :sigma
+mean(chain[:mu])      # find the mean of :mu
+mean(chain[:sigma])   # find the mean of :sigma
+```
+"""
 type Chain
   weight :: Float64 # log model evidence
   value :: Array{Sample}
 end
+
 Chain() = Chain(0, Vector{Sample}())
 
 function Base.show(io::IO, ch1::Chain)