use # blocks for code organization; remove ^L, unused file

src/buildingblocks.jl

@@ -1,9 +1,15 @@
-export
-    NUTS_Transition, get_position, get_neg_energy, get_depth, get_termination,
+#####
+##### Building blocks for sampling.
+#####
+##### Only NUTS_Transition and the exported functions are part of the API.
+#####
+
+export NUTS_Transition, get_position, get_neg_energy, get_depth, get_termination,
     get_acceptance_rate, get_steps
 
-
-# utilities
+####
+#### utilities
+####
 
 """
 $(SIGNATURES)
@@ -15,8 +21,9 @@ Random boolean which is `true` with the given probability `prob`.
 rand_bool(rng::AbstractRNG, prob::T) where {T <: AbstractFloat} =
     rand(rng, T) ≤ prob
 
-
-# abstract trajectory interface
+####
+#### abstract trajectory interface
+####
 
 """
     ζ, τ, d, z = adjacent_tree(rng, trajectory, z, depth, fwd)
@@ -106,8 +113,9 @@ function sample_trajectory(rng, trajectory, z, max_depth)
     ζ, d, termination, depth
 end
 
-
-# proposals
+####
+#### proposals
+####
 
 """
 Proposal that is propagated through by sampling recursively when building the
@@ -147,8 +155,9 @@ function combine_proposals(rng, ζ₁::Proposal, ζ₂::Proposal, bias)
     Proposal(z, ω)
 end
 
-
-# divergence statistics
+####
+#### divergence statistics
+####
 
 """
 Divergence and acceptance statistics.
@@ -207,8 +216,9 @@ Return average Metropolis acceptance rate.
 """
 get_acceptance_rate(x::DivergenceStatistic) = x.∑a / x.steps
 
-
-# turn analysis
+####
+#### turn analysis
+####
 
 """
 Statistics for the identification of turning points. See Betancourt (2017,
@@ -243,8 +253,9 @@ function isturning(τ::TurnStatistic)
     dot(p♯₋, ρ) < 0 || dot(p♯₊, ρ) < 0
 end
 
-
-# sampling
+####
+#### sampling
+####
 
 """
 Representation of a trajectory, ie a Hamiltonian with a discrete integrator that

src/diagnostics.jl

@@ -1,4 +1,6 @@
-# statistics and diagnostics
+#####
+##### statistics and diagnostics
+#####
 
 export EBFMI, NUTS_statistics
 

src/hamiltonian.jl

@@ -1,5 +1,7 @@
-# This file contains building blocks for traversing a Hamiltonian
-# deterministically, using the leapfrog integrator.
+#####
+##### Building blocks for traversing a Hamiltonian deterministically, using the leapfrog
+##### integrator.
+#####
 
 export KineticEnergy, EuclideanKE, GaussianKE
 

src/reporting.jl

@@ -1,3 +1,7 @@
+#####
+##### Reporting progress.
+#####
+
 export ReportSilent, ReportIO
 
 """

src/sampler.jl

@@ -1,8 +1,13 @@
-export
-    NUTS, mcmc, mcmc_adapting_ϵ, NUTS_init_tune_mcmc, sample_cov,
-    get_position_matrix
+#####
+##### Sampling: high-level interface and building blocks
+#####
+
+export NUTS, mcmc, mcmc_adapting_ϵ, NUTS_init_tune_mcmc, sample_cov, get_position_matrix
+
+####
+#### high-level interface: sampler
+####
 
-# high-level interface: sampler
 
 """
 Specification for the No-U-turn algorithm, including the random number
@@ -85,8 +90,9 @@ Return the samples of the parameter vector as rows of a matrix.
 """
 get_position_matrix(sample) = vcat(get_position.(sample)'...)
 
-
-# tuning and diagnostics
+####
+#### tuning and diagnostics
+####
 
 """
 $(SIGNATURES)
@@ -137,8 +143,9 @@ function NUTS_init(rng::AbstractRNG, ℓ;
     NUTS(rng, H, q, ϵ, max_depth, report)
 end
 
-
-# tuning: abstract interface
+####
+#### tuning: abstract interface
+####
 
 """
 $(TYPEDEF)
@@ -160,8 +167,9 @@ updated sampler state after tuning.
 """
 function tune end
 
-
-# tuning: tuner building blocks
+####
+#### tuning: tuner building blocks
+####
 
 "Adapt the integrator stepsize for `N` samples."
 struct StepsizeTuner <: AbstractTuner

src/stepsize.jl

@@ -1,4 +1,6 @@
-# stepsize heuristics and adaptation
+#####
+##### stepsize heuristics and adaptation
+#####
 
 """
 $(TYPEDEF)