Add Aqua and a docstring on every exported name

CHANGELOG.md

@@ -47,6 +47,14 @@ first entry is written.
 - **`Base.iterate(pl::ParticleList, state)` forwards to `pl.particles`.** One method covers the
   first and the later steps, and the state is the state of `iterate` over the particle vector:
   the index of the next particle, not of the last one.
+- **Aqua.jl 0.8 added as a test dependency.** `Aqua.test_all(ParticleMethods)` runs inside
+  its own `@testset "Aqua"` in `test/runtests.jl`, so a failing check fails the suite. All
+  11 checks pass with Aqua 0.8.18, among them undefined exports, piracy, ambiguities and
+  stale dependencies.
+- **Docstrings written for the module, `Particle` and `ParticleList`.** These were the only
+  exported names without one (`eachparticle` had one).
+  `Base.Docs.undocumented_names(ParticleMethods)` is now empty, and the library page renders
+  all four.
 
 ### Bug Fixes
 

Project.toml

@@ -7,15 +7,17 @@ version = "0.1.2"
 HDF5 = "f67ccb44-e63f-5c2f-98bd-6dc0ccc4ba2f"
 
 [compat]
+Aqua = "0.8"
 HDF5 = "0.16, 0.17"
 StaticArrays = "1"
 Test = "1"
 julia = "1.10"
 
 [extras]
+Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
 HDF5 = "f67ccb44-e63f-5c2f-98bd-6dc0ccc4ba2f"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["HDF5", "StaticArrays", "Test"]
+test = ["Aqua", "HDF5", "StaticArrays", "Test"]

src/ParticleMethods.jl

@@ -1,3 +1,9 @@
+"""
+    ParticleMethods
+
+Data structures for particles and particle lists: [`Particle`](@ref) and
+[`ParticleList`](@ref), with named access to parts of the state and to parameters.
+"""
 module ParticleMethods
 
 using HDF5

src/particle.jl

@@ -1,6 +1,24 @@
 
 import Base.hasproperty, Base.getproperty
 
+"""
+    Particle(state; variables = NamedTuple(), parameters = NamedTuple())
+    Particle(DT, len; variables = NamedTuple(), parameters = NamedTuple())
+
+A particle with the state vector `state`, or a zero state of element type `DT` and length `len`.
+
+`variables` maps names to indices or index ranges into `state`, and `parameters` maps names to
+values. Each name is a property of the particle: `p.x` is a view into `state` for a variable `x`,
+and the stored value for a parameter. The names must not repeat each other or the field names
+`state`, `views` and `params`.
+
+# Example
+
+```julia
+p = Particle(Float64, 7; variables = (x = 1:3, v = 4:6, w = 7))
+p.x    # view(p.state, 1:3)
+```
+"""
 struct Particle{T, ST <: AbstractVector{T}, VT <: NamedTuple, PT <: NamedTuple}
     state::ST
     views::VT

src/particle_list.jl

@@ -7,6 +7,26 @@ _sort_names(::NamedTuple{N, T}) where {N, T} = Tuple(sort([N...]))
 
 _sort_ntuple(nt::NamedTuple) = NamedTuple{_sort_names(nt)}(nt)
 
+"""
+    ParticleList(list::AbstractMatrix; variables = NamedTuple(), parameters = NamedTuple())
+    ParticleList(DT, np, nd; variables = NamedTuple(), parameters = NamedTuple())
+    ParticleList(x, v, w; parameters = NamedTuple())
+    ParticleList(h5::H5DataStore, path = "/")
+    ParticleList(fpath::AbstractString, path = "/")
+
+A list of particles, stored as the columns of the matrix `list`. Each column is the state of one
+particle, and `pl[i]` is that particle as a [`Particle`](@ref).
+
+`variables` maps names to row indices or row ranges of `list`, and `parameters` maps names to
+values. Each name is a property of the list: `pl.x` is a view into the rows of a variable `x` for
+all particles, and the stored value for a parameter. The names must not repeat each other or the
+field names `list`, `views`, `params`, `particles`, `variables` and `indices`.
+
+The second form makes a zero list of element type `DT` with `np` particles of `nd` components.
+The third form stacks positions `x`, velocities `v` and weights `w`, and defines the variables
+`x`, `v`, `z` (positions and velocities) and `w`. The last two forms read a list that `h5save`
+wrote, from a group `path` of an HDF5 file or from the file at `fpath`.
+"""
 struct ParticleList{T, ST <: AbstractMatrix{T}, VT <: NamedTuple, PT <: NamedTuple,
     PART <: AbstractVector, VART <: NamedTuple, IND <: NamedTuple}
     list::ST

test/runtests.jl

@@ -1,9 +1,14 @@
 using ParticleMethods
 using Test
 
+using Aqua: Aqua
 using StaticArrays: MVector
 
 @testset "ParticleMethods.jl" begin
+    @testset "Aqua" begin
+        Aqua.test_all(ParticleMethods)
+    end
+
     @testset "Particles" begin
         include("particle_tests.jl")
     end