[commons-math] 05/05: Javadoc.

[er...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

erans pushed a commit to branch feature__MATH-1563__genetic_algorithm
in repository https://gitbox.apache.org/repos/asf/commons-math.git

commit aa0d427dd6dd1b98a3bfc97896ddef30eb4077de
Author: Gilles Sadowski <gi...@gmail.com>
AuthorDate: Mon Jun 27 15:16:27 2022 +0200

    Javadoc.
---
 .../org/apache/commons/math4/ga2/Population.java   | 24 +++++++++++++++---
 .../commons/math4/ga2/gene/package-info.java       | 29 ++++++++++++++++++++++
 2 files changed, 50 insertions(+), 3 deletions(-)

diff --git a/commons-math-ga2/src/main/java/org/apache/commons/math4/ga2/Population.java b/commons-math-ga2/src/main/java/org/apache/commons/math4/ga2/Population.java
index a75979acc..f8cf7639b 100644
--- a/commons-math-ga2/src/main/java/org/apache/commons/math4/ga2/Population.java
+++ b/commons-math-ga2/src/main/java/org/apache/commons/math4/ga2/Population.java
@@ -29,7 +29,23 @@ import org.apache.commons.rng.UniformRandomProvider;
 /**
  * Collection of chromosomes and associated fitness.
  *
- * Class is <em>not</em> thread-safe.
+ * <p>
+ * Notes:
+ * <ul>
+ *  <li>
+ *   Class is <em>not</em> thread-safe.
+ *  </li>
+ *  <li>
+ *   Class assumes that each chromosome instance (of type {@code <G>})
+ *   identifies a unique individual, irrespective of whether other
+ *   individuals share the same sequence of genes; hence type {@code <G>}
+ *   must <em>not</em> override method {@link Object#equals(Object)
+ *   equals(Object o)}.
+ *   In other words, if an overridden {@code equals} compares equality of
+ *   gene sequences, the current implementation of this class will only
+ *   contain individuals whose gene sequence is unique.
+ *  </li>
+ * </ul>
  *
  * @param <G> Genotype.
  * @param <P> Phenotype.
@@ -71,9 +87,13 @@ public class Population<G, P> {
 
     /**
      * Insert chromosomes into the population.
+     *
      * Fitness and rank are calculated.
      * If the fitness is {@code NaN}, the corresponding chromosome is
      * <em>not</em> added to the population.
+     * <p>
+     * Note: All the {@code chromosomes} are passed in a single call to the
+     * {@link FitnessService#apply(Function,Collection) fitness calculator}.
      *
      * @param chromosomes Chromosomes.
      */
@@ -102,8 +122,6 @@ public class Population<G, P> {
         }
     }
 
-    /**
-     *
     /**
      * Retrieves the rank.
      * Ranks are attributed in the range [0, N - 1] (where N is the
diff --git a/commons-math-ga2/src/main/java/org/apache/commons/math4/ga2/gene/package-info.java b/commons-math-ga2/src/main/java/org/apache/commons/math4/ga2/gene/package-info.java
new file mode 100644
index 000000000..2a10d7c27
--- /dev/null
+++ b/commons-math-ga2/src/main/java/org/apache/commons/math4/ga2/gene/package-info.java
@@ -0,0 +1,29 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Chromosome types (and operators that can be applied to them) are
+ * defined in sub-packages of this package.
+ *
+ * Note about implementing a specific representation (genotype):
+ * <ul>
+ *  <li>
+ *   Implementation must <em>not</em> override {@link Object#equals(Object)}
+ *   (cf. {@link org.apache.commons.math4.ga2.Population Population}).
+ *  </li>
+ * </ul>
+ */
+package org.apache.commons.math4.ga2.gene;