(wip) add docstrings

docs/Project.toml

@@ -1,3 +1,2 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-SpinMonteCarlo = "71c4a2d3-ecf8-5cd9-ab6a-09a504837b4f"

docs/make.jl

@@ -1,3 +1,5 @@
+push!(LOAD_PATH, "../src")
+
 using Documenter
 using SpinMonteCarlo
 

docs/src/lib/public.md

@@ -61,6 +61,25 @@ simple_estimator
 improved_estimator
 ```
 
+## Observables
+```@docs
+MCObservable
+ScalarObservable
+VectorObservable
+MCObservableSet
+makeMCObservable!
+SimpleObservable
+SimpleVectorObservable
+SimpleObservableSet
+SimpleVectorObservableSet
+binning
+Jackknife
+JackknifeVector
+JackknifeSet
+JackknifeVectorSet
+jackknife
+```
+
 ## Snapshots
 ```@docs
 gen_snapshot!

src/observables/MCObservables.jl

@@ -13,8 +13,25 @@ export p_value
 export show, dump_plot
 export merge, merge!
 
+@doc """
+    MCObservable
+
+    abstract type representing observable in Monte Carlo calculation.
+"""
 abstract type MCObservable end
+
+"""
+    ScalarObservable <: MCObservable
+
+    abstract type representing scalar-type observable in Monte Carlo calculation.
+"""
 abstract type ScalarObservable <: MCObservable end
+
+"""
+    VectorObservable <: MCObservable
+
+    abstract type representing vector-type observable in Monte Carlo calculation.
+"""
 abstract type VectorObservable <: MCObservable end
 
 function p_value(X::MCObservable, y::Real; verbose::Bool=false)

src/observables/jackknife.jl

@@ -1,10 +1,21 @@
 export Jackknife, JackknifeSet
 export jackknife
 
+"""
+    Jackknife <: ScalarObservable
+
+    Jackknife resampling observable.
+"""
 mutable struct Jackknife <: ScalarObservable
     xs::Vector{Float64}
 end
 
+"""
+    Jackknife(f::Function, jks::Jackknife...)
+
+    Construct a Jackknife observable by applying `f` to `jks`.
+    For example, `Jackknife(mean, jk1, jk2, jk3)` returns a Jackknife observable of the means of `jk1`, `jk2`, and `jk3`.
+"""
 function Jackknife(f::Function, jks::Jackknife...)
     if isempty(jks)
         return Jackknife(zeros(0))
@@ -127,9 +138,25 @@ import Base.^
 ^(lhs::Integer, rhs::Jackknife) = Jackknife(lhs .^ (rhs.xs))
 ^(lhs::Jackknife, rhs::Jackknife) = Jackknife((lhs.xs) .^ (rhs.xs))
 
+"""
+    JackknifeSet
+
+    Alias of `MCObservableSet{Jackknife}`.
+"""
 const JackknifeSet = MCObservableSet{Jackknife}
 
+@doc doc"""
+    jackknife(obs::ScalarObservable)
+
+    Construct a Jackknife observable from a scalar observable
+"""
 jackknife(obs::ScalarObservable) = Jackknife(obs)
+
+@doc doc"""
+    jackknife(obsset::MCObservableSet)
+
+    Construct a JackknifeSet from a MCObservableSet
+"""
 function jackknife(obsset::MCObservableSet)
     JK = JackknifeSet()
     for (k, v) in obsset

src/observables/jackknifevector.jl

@@ -1,5 +1,10 @@
 export JackknifeVector, JackknifeVectorSet
 
+"""
+    JackknifeVector <: VectorObservable
+
+    Jackknife resampling observable for vector-type observable.
+"""
 mutable struct JackknifeVector <: VectorObservable
     xs::Vector{Vector{Float64}}
 end
@@ -21,6 +26,12 @@ end
 
 JackknifeVector() = JackknifeVector(Vector{Float64}[])
 
+"""
+    JackknifeVector(f::Function, jks::JackknifeVector...)
+
+    Construct a JackknifeVector observable by applying `f` to `jks`.
+    For example, `JackknifeVector(mean, jk1, jk2, jk3)` returns a JackknifeVector observable of the means of `jk1`, `jk2`, and `jk3`.
+"""
 function JackknifeVector(f::Function, jks::JackknifeVector...)
     if isempty(jks)
         return JackknifeVector()
@@ -222,8 +233,18 @@ for op in (:*, :/, :\)
                                                                                                  rhs)
 end
 
+"""
+    JackknifeVectorSet
+
+    Alias of `MCObservableSet{JackknifeVector}`.
+"""
 const JackknifeVectorSet = MCObservableSet{JackknifeVector}
 
+"""
+    jackknife(obs::VectorObservable)
+
+    Construct a JackknifeVector observable from a vector observable
+"""
 jackknife(obs::VectorObservable) = JackknifeVector(obs)
 function jackknife(obsset::MCObservableSet{Obs}) where {(Obs <: VectorObservable)}
     JK = JackknifeSet()

src/observables/observableset.jl

@@ -1,8 +1,19 @@
 export MCObservableSet
+
+"""
+    MCObservableSet{Obs}
+
+    Alias of `Dict{String, Obs}` where `Obs` is a subtype of `MCObservable`.
+"""
 const MCObservableSet{Obs<:MCObservable} = Dict{String,Obs}
 
 export makeMCObservable!
 
+"""
+    makeMCObservable!(oset::MCObservableSet{Obs}, name::String)
+
+    Create an observable with the name `name` in the observable set `oset`.
+"""
 function makeMCObservable!(oset::MCObservableSet{Obs},
                            name::String) where {Obs<:MCObservable}
     if haskey(oset, name)

src/observables/simple.jl

@@ -1,5 +1,10 @@
 export SimpleObservable, stddev, binning
 
+"""
+    SimpleObservable
+
+    A simple observable which stores all the data in memory.
+"""
 mutable struct SimpleObservable <: ScalarObservable
     bins::Vector{Float64}
     num::Int64
@@ -107,6 +112,12 @@ end
 merge(lhs::SimpleObservable, rhs::SimpleObservable) = merge!(deepcopy(lhs), rhs)
 
 export SimpleObservableSet
+
+"""
+    SimpleObservableSet
+
+    Alias of `MCObservableSet{SimpleObservable}`.
+"""
 const SimpleObservableSet = MCObservableSet{SimpleObservable}
 
 function merge!(obs::SimpleObservableSet, other::SimpleObservableSet)

src/observables/simplevector.jl

@@ -1,5 +1,10 @@
 export SimpleVectorObservable, stddev
 
+"""
+    SimpleVectorObservable
+
+    A simple observable which stores all the data in memory.   
+"""
 mutable struct SimpleVectorObservable <: VectorObservable
     bins::Vector{Vector{Float64}}
     num::Int64