From 77362968a87a87888731d7e993edaf78826a8009 Mon Sep 17 00:00:00 2001
From: ChrisRackauckas-Claude <accounts@chrisrackauckas.com>
Date: Fri, 10 Jul 2026 14:33:36 -0400
Subject: [PATCH] Document PoissonRandom public APIs

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
---
 docs/src/pois_rand.md      |  1 +
 src/PoissonRandom.jl       | 53 +++++++++++++++++++++++++++-----------
 test/qa/public_api_docs.jl | 17 ++++++++++++
 test/qa/qa.jl              |  2 ++
 4 files changed, 58 insertions(+), 15 deletions(-)
 create mode 100644 test/qa/public_api_docs.jl

diff --git a/docs/src/pois_rand.md b/docs/src/pois_rand.md
index ec9aa72..c93ef75 100644
--- a/docs/src/pois_rand.md
+++ b/docs/src/pois_rand.md
@@ -1,5 +1,6 @@
 # Poisson Random API
 
 ```@docs
+PassthroughRNG
 pois_rand
 ```
diff --git a/src/PoissonRandom.jl b/src/PoissonRandom.jl
index 91170d4..9a449c0 100644
--- a/src/PoissonRandom.jl
+++ b/src/PoissonRandom.jl
@@ -6,7 +6,25 @@ using PrecompileTools: @compile_workload
 
 export pois_rand, PassthroughRNG
 
-# GPU-compatible Poisson sampling via PassthroughRNG
+"""
+    PassthroughRNG()
+
+An `AbstractRNG` sentinel for backend-specific random number generation.
+
+`PassthroughRNG` forwards scalar `rand`, `randn`, and `randexp` calls to the
+ambient random number implementation. It is useful when a backend, such as a GPU
+kernel overlay, provides the actual random number generation but an
+`AbstractRNG` argument is still needed by the Poisson sampler.
+
+# Examples
+
+```julia
+using PoissonRandom
+
+x = pois_rand(PassthroughRNG(), 3.0)
+x isa Integer
+```
+"""
 struct PassthroughRNG <: AbstractRNG end
 
 Base.rand(rng::PassthroughRNG) = rand()
@@ -122,26 +140,31 @@ function procf(λ::Real, K::Int, s::Real)
 end
 
 """
-```julia
-pois_rand(λ)
-pois_rand(rng::AbstractRNG, λ)
-```
+    pois_rand(λ::Real)
+    pois_rand(rng::AbstractRNG, λ::Real)
+
+Draw one random variate from the Poisson distribution with rate `λ`.
+
+For small `λ`, `pois_rand` uses an exponential-counting method. For larger `λ`,
+it switches to the Ahrens-Dieter modified normal algorithm.
+
+# Arguments
 
-Generates Poisson(λ) distributed random numbers using a fast polyalgorithm.
+- `λ`: Poisson rate parameter. It should be nonnegative.
+- `rng`: optional random number generator. Defaults to `Random.default_rng()`.
 
-## Examples
+# Examples
 
 ```julia
-# Simple Poisson random
-pois_rand(λ)
+using PoissonRandom
+using Random
 
-# Using another RNG
-using RandomNumbers
-rng = Xorshifts.Xoroshiro128Plus()
-pois_rand(rng, λ)
+rng = MersenneTwister(1234)
+x = pois_rand(rng, 4.0)
+x isa Integer
 
-# Simple Poisson random on GPU
-pois_rand(PoissonRandom.PassthroughRNG(), λ)
+y = pois_rand(PassthroughRNG(), 4.0)
+y isa Integer
 ```
 """
 pois_rand(λ::Real) = pois_rand(Random.default_rng(), λ)
diff --git a/test/qa/public_api_docs.jl b/test/qa/public_api_docs.jl
new file mode 100644
index 0000000..ee5beab
--- /dev/null
+++ b/test/qa/public_api_docs.jl
@@ -0,0 +1,17 @@
+using PoissonRandom
+using Test
+
+@testset "public API documentation" begin
+    public_names = filter(!=(:PoissonRandom), names(PoissonRandom; all = false, imported = false))
+    @test Set(public_names) == Set([:PassthroughRNG, :pois_rand])
+
+    for name in public_names
+        binding = Docs.Binding(PoissonRandom, name)
+        @test Docs.hasdoc(binding)
+    end
+
+    api_page = read(joinpath(pkgdir(PoissonRandom), "docs", "src", "pois_rand.md"), String)
+    for name in public_names
+        @test occursin(string(name), api_page)
+    end
+end
diff --git a/test/qa/qa.jl b/test/qa/qa.jl
index af96b2c..2b749a9 100644
--- a/test/qa/qa.jl
+++ b/test/qa/qa.jl
@@ -1,5 +1,7 @@
 using SciMLTesting, PoissonRandom, JET, Test
 
+include("public_api_docs.jl")
+
 run_qa(
     PoissonRandom;
     explicit_imports = true,