From 99b9f91d90e6baeeadec4b2377eab385b6d43c23 Mon Sep 17 00:00:00 2001
From: Federico Stra <stra.federico@gmail.com>
Date: Thu, 12 Aug 2021 19:13:07 +0200
Subject: [PATCH] Document interaction

---
 src/interactions.jl | 43 ++++++++++++++++++++++++++++++++-----------
 1 file changed, 32 insertions(+), 11 deletions(-)

diff --git a/src/interactions.jl b/src/interactions.jl
index 6dadc25..2f17ec3 100644
--- a/src/interactions.jl
+++ b/src/interactions.jl
@@ -11,7 +11,7 @@ where ``\rho`` is the piecewise-constant density associated to the particles `ys
 
 It `t` is omitted, then `W′(x)` is assumed independent of time.
 
-See also [`integrated_interaction`](@ref).
+See also [`integrated_interaction`](@ref), [`compute_interaction`](@ref).
 """
 function sampled_interaction end
 
@@ -31,15 +31,6 @@ function sampled_interaction(t::Real, x::Real; Wprime, particles::AbstractVector
     -sum(Wprime(t, x - p) for p in particles) / (length(particles) - 1)
 end
 
-# function total_interaction__(Wprime, ys::AbstractVector{<:Real}, x::Real)
-#     T = promote_type(eltype(ys), typeof(x))
-#     w::T = 0
-#     for y in ys
-#         w += Wprime(y - x)
-#     end
-#     w / (length(ys) - 1)
-# end
-
 
 @doc raw"""
     integrated_interaction([t,] x, W, ys[, dens_diff])
@@ -54,7 +45,7 @@ It `t` is omitted, then `W(x)` is assumed independent of time.
     To ensure the correctness of the computation, `dens_diff` must coincide with `diff(pwc_density(ys))`.
     It can be pre-computed and passed explicitly to allow reuse (as an optimization).
 
-See also [`sampled_interaction`](@ref).
+See also [`sampled_interaction`](@ref), [`compute_interaction`](@ref).
 """
 function integrated_interaction end
 
@@ -67,14 +58,44 @@ function integrated_interaction(t::Real, x::Real, W, ys::AbstractVector{<:Real},
 end
 
 
+"""
+    SampledInteraction(W′)
+
+Represents the sampled interaction induced by the function `W′`.
+
+The interaction can be evaluated with [`compute_interaction`](@ref).
+
+See also [`IntegratedInteraction`](@ref).
+"""
 struct SampledInteraction{TWprime}
     Wprime::TWprime
 end
 
+"""
+    IntegratedInteraction(W)
+
+Represents the integrated interaction induced by the function `W`.
+
+The interaction can be evaluated with [`compute_interaction`](@ref).
+
+See also [`SampledInteraction`](@ref).
+"""
 struct IntegratedInteraction{TW}
     W::TW
 end
 
+"""
+    compute_interaction(t, x, interaction, ys[, dens_diff])
+
+Evaluates the interaction generated by the particles `ys` at `(t, x)`.
+
+`interaction` can be a `SampledInteraction`, an `IntegratedInteraction`, or any other
+form of interaction that provides this interface.
+
+See also [`SampledInteraction`](@ref), [`IntegratedInteraction`](@ref),
+[`sampled_interaction`](@ref), [`integrated_interaction`](@ref).
+"""
+function compute_interaction end
 
 function compute_interaction(t::Real, x::Real, int::SampledInteraction, ys::AbstractVector{<:Real}, dens_diff::AbstractVector{<:Real}=Float16[])
     sampled_interaction(t, x, int.Wprime, ys)