Add docs for link, invlink, logpdf_with_trans

docs/src/index.md

@@ -1,6 +1,15 @@
 # Bijectors.jl
 
-This package implements a set of functions for transforming constrained random variables (e.g. simplexes, intervals) to Euclidean space. The 3 main functions implemented in this package are the `link`, `invlink` and `logpdf_with_trans` for a number of distributions. The distributions supported are:
+This package implements a set of functions for transforming constrained random variables (e.g. simplexes, intervals) to Euclidean space.
+The 3 main functions implemented in this package are the `link`, `invlink` and `logpdf_with_trans` for a number of distributions.
+
+```@docs
+Bijectors.link
+Bijectors.invlink
+Bijectors.logpdf_with_trans
+```
+
+The distributions supported are:
 
  1. `RealDistribution`: `Union{Cauchy, Gumbel, Laplace, Logistic, NoncentralT, Normal, NormalCanon, TDist}`,
  2. `PositiveDistribution`: `Union{BetaPrime, Chi, Chisq, Erlang, Exponential, FDist, Frechet, Gamma, InverseGamma, InverseGaussian, Kolmogorov, LogNormal, NoncentralChisq, NoncentralF, Rayleigh, Weibull}`,

src/Bijectors.jl

@@ -126,7 +126,59 @@ end
 
 # Distributions
 
+"""
+    link(d::Distribution, x)
+
+Transforms the input `x` using the constrained-to-unconstrained bijector for
+distribution `d`.
+
+See also: [`invlink`](@ref).
+
+# Example
+
+```jldoctest
+julia> using Bijectors
+
+julia> d = LogNormal()   # support is (0, Inf)
+LogNormal{Float64}(μ=0.0, σ=1.0)
+
+julia> b = bijector(d)   # log function transforms to unconstrained space
+(::Base.Fix1{typeof(broadcast), typeof(log)}) (generic function with 1 method)
+
+julia> b(1.0)
+0.0
+
+julia> link(LogNormal(), 1.0)
+0.0
+```
+"""
 link(d::Distribution, x) = bijector(d)(x)
+
+"""
+    invlink(d::Distribution, y)
+
+Performs the inverse transform on a value `y` that was transformed using the
+constrained-to-unconstrained bijector for distribution `d`.
+
+It should hold that `invlink(d, link(d, x)) = x`.
+
+See also: [`link`](@ref).
+
+# Example
+
+```jldoctest
+julia> using Bijectors
+
+julia> d = LogNormal()    # support is (0, Inf)
+LogNormal{Float64}(μ=0.0, σ=1.0)
+
+julia> link(LogNormal(), 1.0)   # uses a log transform
+0.0
+
+julia> invlink(LogNormal(), 0.0)
+1.0
+```
+"""
 invlink(d::Distribution, y) = inverse(bijector(d))(y)
 
 # To still allow `logpdf_with_trans` to work with "batches" in a similar way
@@ -156,6 +208,37 @@ end
 _logabsdetjac_dist(d::LKJCholesky, x::Cholesky) = logabsdetjac(bijector(d), x)
 _logabsdetjac_dist(d::LKJCholesky, x::AbstractVector) = logabsdetjac.((bijector(d),), x)
 
+"""
+    logpdf_with_trans(d::Distribution, x, transform::Bool)
+
+If `transform` is `false`, `logpdf_with_trans` calculates the log probability
+density function (logpdf) of distribution `d` at `x`.
+
+If `transform` is `true`, the logpdf is calculated after transforming `x` using
+the constrained-to-unconstrained bijector for distribution `d`. Specifically,
+if `x` is distributed according to `d` and `y = link(d, x)` is distributed
+according to `td`, then `logpdf_with_trans(d, x, true) = logpdf(td, y)`.
+
+See also: [`logpdf`](@ref).
+
+# Example
+
+```jldoctest
+julia> using Bijectors
+
+julia> logpdf_with_trans(LogNormal(), ℯ, false)
+-2.4189385332046727
+
+julia> logpdf(LogNormal(), ℯ)  # Same as above
+-2.4189385332046727
+
+julia> logpdf_with_trans(LogNormal(), ℯ, true)
+-1.4189385332046727
+
+julia> logpdf(Normal(), 1.0)   # If x ~ LogNormal(), then log(x) ~ Normal()
+-1.4189385332046727
+```
+"""
 function logpdf_with_trans(d::Distribution, x, transform::Bool)
     if ispd(d)
         return pd_logpdf_with_trans(d, x, transform)