update docstrings and api page of the docs

docs/src/api.md

@@ -10,6 +10,18 @@ Celani
 Xie
 ```
 
+```@docs
+position
+direction
+speed
+velocity
+motilepattern
+turnrate
+rotational_diffusivity
+radius
+state
+```
+
 ## [Motility](@id Motility)
 ```@docs
 AbstractMotility
@@ -22,19 +34,22 @@ RunReverseFlick
 
 ## [Utils](@id Utils)
 ```@docs
-vectorize_adf_measurement
+distance
+distancevector
 random_speed
 random_velocity
+Analysis.adf_to_matrix
+Analysis.adf_to_vectors
+Analysis.unfold
+Analysis.unfold!
 ```
 
 ## [Data analysis](@id Analysis)
 ```@docs
+Analysis.detect_turns!
+Analysis.run_durations
+Analysis.driftvelocity_point!
+Analysis.driftvelocity_direction!
 msd
 acf
-driftvelocity_direction
-driftvelocity_point
-detect_turns
-rundurations
-mean_runduration
-mean_turnrate
 ```

src/api.jl

@@ -2,17 +2,63 @@ export position, direction, speed, velocity, motilepattern,
     turnrate, rotational_diffusivity, radius, state,
     distance, distancevector
 
+"""
+    position(m::AbstractMicrobe)
+Return the position of the microbe.
+"""
 Base.position(m::AbstractMicrobe) = m.pos
+"""
+    direction(m::AbstractMicrobe)
+Return the direction versor of the microbe.
+"""
 direction(m::AbstractMicrobe) = m.vel
+"""
+    speed(m::AbstractMicrobe)
+Return the speed of the microbe.
+"""
 speed(m::AbstractMicrobe) = m.speed
+"""
+    velocity(m::AbstractMicrobe)
+Return the velocity vector of the microbe (direction times speed).
+"""
 velocity(m::AbstractMicrobe) = direction(m) .* speed(m)
+"""
+    motilepattern(m::AbstractMicrobe)
+Return the motile pattern of the microbe.
+"""
 motilepattern(m::AbstractMicrobe) = m.motility
+"""
+    turnrate(m::AbstractMicrobe)
+Return the unbiased turn rate of the microbe.
+"""
 turnrate(m::AbstractMicrobe) = m.turn_rate
+"""
+    rotational_diffusivity(m::AbstractMicrobe)
+Return the rotational diffusivity of the microbe.
+"""
 rotational_diffusivity(m::AbstractMicrobe) = m.rotational_diffusivity
+"""
+    radius(m::AbstractMicrobe)
+Return the radius of the microbe.
+"""
 radius(m::AbstractMicrobe) = m.radius
+"""
+    state(m::AbstractMicrobe)
+Return the internal state of the microbe.
+"""
 state(m::AbstractMicrobe) = m.state
 
+"""
+    distance(a, b, model)
+Evaluate the euclidean distance between `a` and `b` respecting
+the boundary conditions of the `model`
+"""
 distance(a, b, model) = euclidean_distance(position(a), position(b), model)
+"""
+    distancevector(a, b, model)
+Evaluate the distance vector from `a` to `b` respecting
+the boundary conditions of the `model`.
+"""
 distancevector(a, b, model) = distancevector(position(a), position(b), model)
 function distancevector(a::SVector{D}, b::SVector{D}, model) where D
     extent = spacesize(model)

src/submodules/Analysis/drift.jl

@@ -11,10 +11,9 @@ of microbes.
 By convention the drift velocity will be positive
 for motion towards the target point.
 
-If `normalize` is set to `true`, drift velocities are normalized by the
-instantaneous speed of the microbe.
-
 **Keywords**
+- `normalize = false`: whether drift velocities should be normalized by
+  the instantaneous speed of the microbes
 - `pos_key::Symbol = :position`: name of the column containing microbe positions
 - `vel_key::Symbol = :velocity`: name of the column containing microbe velocities
 """
@@ -76,10 +75,9 @@ Requires the existence of a column containing the velocity of microbes.
 By convention the drift velocity will be positive
 for motion along the target directoin.
 
-If `normalize` is set to `true`, drift velocities are normalized by the
-instantaneous speed of the microbe.
-
 **Keywords**
+- `normalize = false`: whether drift velocities should be normalized by the
+  instantaneous speed of the microbes
 - `vel_key::Symbol = :velocity`: name of the column containing microbe velocities
 """
 function driftvelocity_direction! end