Deep JavaDoc polish for algorithm alias drivers. Added mini-formulas and primary references directly in class-level JavaDocs.

Author: KarloKnezevic

README.md

@@ -32,6 +32,7 @@ Documentation portal: [https://edaf.readthedocs.io/](https://edaf.readthedocs.io
 - [Docker Usage](#docker-usage)
 - [Extending the Framework](#extending-the-framework)
 - [Using EDAF as Package](#using-edaf-as-package)
+- [API JavaDoc](#api-javadoc)
 - [Release and Publishing](#release-and-publishing)
 - [Testing and Quality](#testing-and-quality)
 - [Complexity and Performance](#complexity-and-performance)
@@ -826,6 +827,26 @@ For a concrete external Maven project example (custom plugin + run + web monitor
 - [docs/using-edaf-as-package.md](docs/using-edaf-as-package.md)
 - [examples/external-package-sample/README.md](examples/external-package-sample/README.md)
 
+## API JavaDoc
+
+EDAF includes package-level JavaDoc across core, algorithms, models, problems, persistence, CLI and web modules, plus expanded mathematical docs for key probabilistic models and algorithm drivers.
+
+Generate aggregated API docs locally:
+
+```bash
+./scripts/docs/build-javadocs.sh
+```
+
+Alternative direct Maven command:
+
+```bash
+mvn -q -P apidocs -DskipTests verify
+```
+
+Generated entrypoint:
+
+- `target/site/apidocs/index.html`
+
 ## Release and Publishing
 
 For GitHub release, Maven Central (mvnrepository visibility), and Read the Docs publishing:
@@ -911,6 +932,7 @@ Full EDA/baseline/statistical bibliography:
 - [docs/benchmark-comparisons.md](docs/benchmark-comparisons.md) - reproducible side-by-side benchmark outputs
 - [docs/complexity-and-performance.md](docs/complexity-and-performance.md) - asymptotic complexity + measured runtime snapshot
 - [docs/testing-and-release.md](docs/testing-and-release.md) - release hardening checklist and validation pipeline
+- [docs/javadoc-api.md](docs/javadoc-api.md) - aggregated API docs generation and navigation guide
 - [docs/bibliography.md](docs/bibliography.md) - exhaustive EDA literature and benchmarking references
 - [docs/cli-reference.md](docs/cli-reference.md) - exhaustive command reference
 - [docs/docker.md](docs/docker.md) - containerized workflows

docs/index.md

@@ -50,6 +50,7 @@ flowchart TD
 - [Benchmark Comparisons](./benchmark-comparisons.md)
 - [Complexity and Performance](./complexity-and-performance.md)
 - [Testing and Release Hardening](./testing-and-release.md)
+- [API JavaDoc](./javadoc-api.md)
 - [Bibliography](./bibliography.md)
 
 ## Operations

docs/javadoc-api.md

@@ -0,0 +1,74 @@
+<p align="right"><img src="./assets/branding/edaf_logo2.png" alt="EDAF logo" width="180" /></p>
+
+# API JavaDoc
+
+This page describes how EDAF Java API documentation is generated and how to navigate it efficiently.
+
+## Scope
+
+EDAF v3 JavaDoc now includes:
+
+- package-level docs (`package-info.java`) for core, algorithms, models, problems, persistence, CLI, web, reporting, representations and COCO modules
+- expanded class-level docs for key algorithm drivers and probabilistic model implementations
+- mathematical descriptions for core update equations in discrete/continuous/permutation model families
+
+## Documentation Standard Used
+
+EDAF JavaDoc uses the following conventions across classes and public methods:
+
+- Class JavaDoc:
+  - complete sentence description ending with a period
+  - `@author Karlo Knezevic`
+  - `@version EDAF 3.0.0`
+- Method JavaDoc:
+  - one-sentence (or longer) behavior description ending with a period
+  - one `@param` entry per parameter
+  - `@return` phrase for non-`void` methods
+- `@param` / `@return` descriptions are concise phrases without trailing punctuation
+- avoid type names and variable names inside `@return` description
+- avoid dash-based parameter format (for example, no `@param x - ...`)
+
+## Generate Local API Docs
+
+From repository root:
+
+```bash
+./scripts/docs/build-javadocs.sh
+```
+
+Equivalent Maven command:
+
+```bash
+mvn -q -P apidocs -DskipTests verify
+```
+
+Output entrypoint:
+
+- `target/site/apidocs/index.html`
+
+## Where JavaDoc Configuration Lives
+
+- Root Maven profile: `apidocs` in `pom.xml`
+- Helper script: `scripts/docs/build-javadocs.sh`
+
+`apidocs` profile runs Maven Javadoc aggregate goal over the whole reactor, so cross-module links are preserved.
+
+## Recommended Navigation
+
+1. Start at package summary pages to understand module boundaries and responsibilities.
+2. Open model classes under:
+   - `com.knezevic.edaf.v3.models.discrete`
+   - `com.knezevic.edaf.v3.models.continuous`
+   - `com.knezevic.edaf.v3.models.permutation`
+3. Review algorithm drivers under `com.knezevic.edaf.v3.algorithms*`.
+4. Cross-check runtime orchestration in `com.knezevic.edaf.v3.experiments.runner`.
+
+## CI/Release Usage
+
+For release validation, include API doc generation in your local pre-release checklist:
+
+```bash
+mvn -q -P apidocs -DskipTests verify
+```
+
+If this succeeds, JavaDoc structure and symbol resolution are healthy across modules.

docs/testing-and-release.md

@@ -23,7 +23,8 @@ Gate criteria:
 2. Spotless check passes.
 3. `edaf-web` packages successfully.
 4. Docker runner and web images build from clean context.
-5. No generated artifacts pollute root directory.
+5. Aggregated JavaDoc generation succeeds.
+6. No generated artifacts pollute root directory.
 
 ## 2) Full test commands
 
@@ -50,6 +51,12 @@ mvn -q -pl edaf-core,edaf-experiments -am test
 ./edaf run -c configs/umda-onemax-v3.yml --verbosity quiet
 ```
 
+## 2.4 API JavaDoc generation
+
+```bash
+./scripts/docs/build-javadocs.sh
+```
+
 ## 3) Parallelism validation
 
 EDAF has two concurrency layers:

edaf-algorithms/src/main/java/com/knezevic/edaf/v3/algorithms/EhmPermutationEdaAlgorithm.java

@@ -8,10 +8,31 @@
 import com.knezevic.edaf.v3.repr.types.PermutationVector;
 
 /**
- * EHM permutation EDA driver.
+ * Dedicated EHM/EHBSA-style permutation driver based on edge-histogram modeling.
+ *
+ * <p>Typical paired model represents adjacency probabilities:
+ * <pre>
+ *   P(next = j | current = i)
+ * </pre>
+ * and samples permutations by traversing unused nodes according to transition rows.
+ *
+ * <p>References:
+ * <ol>
+ *   <li>M. Tsutsui, "Probabilistic model-building genetic algorithms in permutation domains,"
+ *   GECCO Workshop, 2006.</li>
+ *   <li>P. Larranaga and J. A. Lozano (eds.), "Estimation of Distribution Algorithms,"
+ *   Kluwer, 2001.</li>
+ * </ol>
+ * @author Karlo Knezevic
+ * @version EDAF 3.0.0
  */
 public final class EhmPermutationEdaAlgorithm extends RatioBasedEdaAlgorithm<PermutationVector> {
 
+    /**
+     * Creates a new EhmPermutationEdaAlgorithm instance.
+     *
+     * @param selectionRatio fraction of population used for model fitting
+     */
     public EhmPermutationEdaAlgorithm(double selectionRatio) {
         super("ehm-eda", selectionRatio);
     }

edaf-algorithms/src/main/java/com/knezevic/edaf/v3/algorithms/FlowEdaAlgorithm.java

@@ -8,10 +8,30 @@
 import com.knezevic.edaf.v3.repr.types.RealVector;
 
 /**
- * Flow-based continuous EDA driver.
+ * Dedicated flow-inspired continuous EDA driver using non-linear density transforms.
+ *
+ * <p>Typical paired model draws latent Gaussian samples and applies a parameterized map:
+ * <pre>
+ *   z ~ N(0, I),   x = f_θ(z)
+ * </pre>
+ * where {@code f_θ} is updated from elite statistics.
+ *
+ * <p>References:
+ * <ol>
+ *   <li>D. J. Rezende and S. Mohamed, "Variational inference with normalizing flows,"
+ *   ICML, 2015.</li>
+ *   <li>D. Wierstra et al., "Natural evolution strategies," JMLR, 2014.</li>
+ * </ol>
+ * @author Karlo Knezevic
+ * @version EDAF 3.0.0
  */
 public final class FlowEdaAlgorithm extends RatioBasedEdaAlgorithm<RealVector> {
 
+    /**
+     * Creates a new FlowEdaAlgorithm instance.
+     *
+     * @param selectionRatio fraction of population used for model fitting
+     */
     public FlowEdaAlgorithm(double selectionRatio) {
         super("flow-eda", selectionRatio);
     }

edaf-algorithms/src/main/java/com/knezevic/edaf/v3/algorithms/FullCovarianceEdaAlgorithm.java

@@ -8,10 +8,31 @@
 import com.knezevic.edaf.v3.repr.types.RealVector;
 
 /**
- * Full-covariance continuous EDA driver.
+ * Dedicated full-covariance Gaussian EDA driver for correlated real-valued search.
+ *
+ * <p>Typical paired model learns correlated Gaussian density:
+ * <pre>
+ *   p(x) = N(x; μ, Σ)
+ * </pre>
+ * and samples via Cholesky factorization {@code x = μ + Lz}, {@code LL^T = Σ}.
+ *
+ * <p>References:
+ * <ol>
+ *   <li>P. Larranaga, "Optimization in continuous domains by learning and simulation
+ *   of Gaussian networks," GECCO Workshop, 2000.</li>
+ *   <li>P. Larranaga and J. A. Lozano (eds.), "Estimation of Distribution Algorithms,"
+ *   Kluwer, 2001.</li>
+ * </ol>
+ * @author Karlo Knezevic
+ * @version EDAF 3.0.0
  */
 public final class FullCovarianceEdaAlgorithm extends RatioBasedEdaAlgorithm<RealVector> {
 
+    /**
+     * Creates a new FullCovarianceEdaAlgorithm instance.
+     *
+     * @param selectionRatio fraction of population used for model fitting
+     */
     public FullCovarianceEdaAlgorithm(double selectionRatio) {
         super("full-covariance-eda", selectionRatio);
     }

edaf-algorithms/src/main/java/com/knezevic/edaf/v3/algorithms/GaussianDiagEdaAlgorithm.java

@@ -8,10 +8,31 @@
 import com.knezevic.edaf.v3.repr.types.RealVector;
 
 /**
- * Gaussian diagonal EDA algorithm driver.
+ * Dedicated diagonal-Gaussian continuous EDA driver.
+ *
+ * <p>Typical paired model assumes independent marginals:
+ * <pre>
+ *   p(x) = Π_d N(x_d; μ_d, σ_d²)
+ * </pre>
+ * with {@code (μ, σ)} re-estimated from elite samples each iteration.
+ *
+ * <p>References:
+ * <ol>
+ *   <li>H. Muehlenbein, J. Bendisch, and H.-M. Voigt, "From recombination of genes to
+ *   the estimation of distributions II. Continuous parameters," PPSN IV, 1996.</li>
+ *   <li>P. Larranaga and J. A. Lozano (eds.), "Estimation of Distribution Algorithms,"
+ *   Kluwer, 2001.</li>
+ * </ol>
+ * @author Karlo Knezevic
+ * @version EDAF 3.0.0
  */
 public final class GaussianDiagEdaAlgorithm extends RatioBasedEdaAlgorithm<RealVector> {
 
+    /**
+     * Creates a new GaussianDiagEdaAlgorithm instance.
+     *
+     * @param selectionRatio fraction of population used for model fitting
+     */
     public GaussianDiagEdaAlgorithm(double selectionRatio) {
         super("gaussian-eda", selectionRatio);
     }

edaf-algorithms/src/main/java/com/knezevic/edaf/v3/algorithms/HBoaAlgorithm.java

@@ -8,10 +8,30 @@
 import com.knezevic.edaf.v3.repr.types.BitString;
 
 /**
- * Hierarchical BOA algorithm driver.
+ * Dedicated hierarchical BOA (hBOA) driver for binary dependency-heavy search.
+ *
+ * <p>Typical paired model is a sparse Bayesian network with conditional factorization:
+ * <pre>
+ *   p(x) = Π_i p(x_i | Pa_i)
+ * </pre>
+ * with hierarchical decomposition of variable interactions.
+ *
+ * <p>References:
+ * <ol>
+ *   <li>M. Pelikan and D. E. Goldberg, "Hierarchical Bayesian optimization algorithm,"
+ *   GECCO, 2001.</li>
+ *   <li>M. Pelikan, D. E. Goldberg, and E. Cantú-Paz, "BOA," GECCO, 1999.</li>
+ * </ol>
+ * @author Karlo Knezevic
+ * @version EDAF 3.0.0
  */
 public final class HBoaAlgorithm extends RatioBasedEdaAlgorithm<BitString> {
 
+    /**
+     * Creates a new HBoaAlgorithm instance.
+     *
+     * @param selectionRatio fraction of population used for model fitting
+     */
     public HBoaAlgorithm(double selectionRatio) {
         super("hboa", selectionRatio);
     }

edaf-algorithms/src/main/java/com/knezevic/edaf/v3/algorithms/RatioBasedEdaAlgorithm.java

@@ -10,23 +10,63 @@
 import com.knezevic.edaf.v3.core.api.Population;
 
 /**
- * Generic model-based EDA driver using ratio-based truncation for model fit selection size.
+ * Generic ratio-based EDA driver.
+ *
+ * <p>This base class implements the canonical EDA cycle from
+ * {@link AbstractEdaAlgorithm}: initialize population, evaluate, select elites,
+ * fit model, sample offspring, and apply replacement. The only strategy detail
+ * overridden here is elite size:
+ * <pre>
+ *   eliteCount = round(selectionRatio * populationSize)
+ * </pre>
+ * clipped to at least one individual.</p>
+ *
+ * <p>Dedicated algorithm aliases (UMDA, BOA, PBIL, etc.) inherit this behavior
+ * and express algorithm identity through plugin/model selection in configuration.</p>
+ *
+ * <p>References:
+ * <ul>
+ *     <li>Larrañaga and Lozano (2001) - Estimation of Distribution Algorithms</li>
+ *     <li>Mühlenbein and Paass (1996) - UMDA</li>
+ * </ul></p>
+ *
+ * @param <G> genotype type
+ * @author Karlo Knezevic
+ * @version EDAF 3.0.0
  */
 public class RatioBasedEdaAlgorithm<G> extends AbstractEdaAlgorithm<G> {
 
     private final String id;
     private final double selectionRatio;
 
+    /**
+     * Creates a ratio-based algorithm driver with bounded elite selection ratio.
+     *
+     * @param id stable algorithm identifier used in events, persistence and CLI
+     * @param selectionRatio fraction of population used for model fitting
+     */
     public RatioBasedEdaAlgorithm(String id, double selectionRatio) {
         this.id = id;
         this.selectionRatio = Math.max(0.01, Math.min(1.0, selectionRatio));
     }
 
+    /**
+     * Returns algorithm identifier.
+     *
+     * @return algorithm identifier
+     */
     @Override
     public String id() {
         return id;
     }
 
+    /**
+     * Returns number of selected individuals used for model fitting.
+     *
+     * @param context algorithm runtime context
+     * @param population current population
+     * @return elite count used for model fitting
+     */
     @Override
     protected int selectionSize(AlgorithmContext<G> context, Population<G> population) {
         return Math.max(1, (int) Math.round(population.size() * selectionRatio));