improve docs

scripts/BHM-example.jl

@@ -79,10 +79,11 @@ plot!(df.steps, df.norm, label="norm", ylabel="norm", xlabel="steps")
 # Now let's look at estimating the energy from the shift.
 # The mean of the shift is a useful estimator of the shift. Calculating the error bars
 # is a bit more involved as correlations have to be removed from the time series.
-# The following code does that:
+# The following code does that with blocking transformations:
 se = shift_estimator(df; skip=steps_equilibrate)
 
-# For the projected energy, it a bit more complicated as it's a ratio of two means:
+# For the projected energy, it a bit more complicated as it's a ratio of fluctuationg
+# quantities:
 pe = projected_energy(df; skip=steps_equilibrate)
 
 # The result is a ratio distribution. Let's get its median and lower and upper error bars
@@ -107,6 +108,8 @@ dimension(Ĥ)
 # using standard linear algebra:
 using LinearAlgebra
 exact_energy = eigvals(Matrix(Ĥ))[1]
+# Read more about `Rimu.jl`s capabilities for exact diagonalisation in the example
+# "Exact diagonalisation".
 
 # Comparing our results for the energy:
 println("Energy from $steps_measure steps with $targetwalkers walkers:

src/lomc.jl

@@ -289,12 +289,12 @@ end
 Return a default starting vector for [`lomc!`](@ref). The default choice for the starting
 vector is
 ```julia
-v = PDVec(starting_address => 10; style)
+v = PDVec(address => 10; style)
 ```
 if threading is available or
 
 ```julia
-v = DVec(starting_address => 10; style)
+v = DVec(address => 10; style)
 ```
 otherwise. See [`PDVec`](@ref), [`DVec`](@ref) and [`StochasticStyle`](@ref).
 """
@@ -404,7 +404,8 @@ julia> metadata(df2, "hamiltonian") # some metadata is automatically added
 
 The default choice for the starting vector is
 `v = default_starting_vector(; address, style, threading)`.
-See [`default_starting_vector`](@ref).
+See [`default_starting_vector`](@ref), [`PDVec`](@ref), [`DVec`](@ref), and
+[`StochasticStyle`](@ref).
 """
 function lomc!(ham, v; df=DataFrame(), name="lomc!", metadata=nothing, kwargs...)
     state = QMCState(ham, v; kwargs...)