[mahout] branch trunk updated: MAHOUT-2148 Add scaladocs to distance metrics

[ra...@apache.org]

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

rawkintrevo pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/mahout.git


The following commit(s) were added to refs/heads/trunk by this push:
     new 608fc0784 MAHOUT-2148 Add scaladocs to distance metrics
     new d4d35dc8b Merge pull request #422 from rawkintrevo/2148
608fc0784 is described below

commit 608fc07846108186f302a3c8a6a5bd05bf29d7c4
Author: Trevor Grant <ra...@apache.org>
AuthorDate: Mon Feb 6 12:35:48 2023 -0600

    MAHOUT-2148 Add scaladocs to distance metrics
---
 .../common/distance/DistanceMetrics.scala          | 52 +++++++++++++++++++++-
 1 file changed, 51 insertions(+), 1 deletion(-)

diff --git a/core/src/main/scala/org/apache/mahout/math/algorithms/common/distance/DistanceMetrics.scala b/core/src/main/scala/org/apache/mahout/math/algorithms/common/distance/DistanceMetrics.scala
index 00495fddf..1b5aae76d 100644
--- a/core/src/main/scala/org/apache/mahout/math/algorithms/common/distance/DistanceMetrics.scala
+++ b/core/src/main/scala/org/apache/mahout/math/algorithms/common/distance/DistanceMetrics.scala
@@ -19,15 +19,41 @@ package org.apache.mahout.math.algorithms.common.distance
 import org.apache.mahout.math.function.Functions
 import org.apache.mahout.math.{CardinalityException, Vector}
 
+/**
+ * Trait representing a distance metric.
+ *
+ * @tparam Vector A vector class with properties such as `size` and `aggregate`.
+ */
 trait DistanceMetric extends Serializable {
+    /**
+       * Computes the distance between two vectors.
+       *
+       * @param v1 The first vector.
+       * @param v2 The second vector.
+       *
+       * @return The distance between `v1` and `v2`.
+       *
+   */
   def distance(v1: Vector, v2: Vector): Double
 }
 
-
+/**
+ * Object for selecting a distance metric based on a given name.
+ */
 object DistanceMetricSelector extends Serializable{
 
+    /**
+       * A map of named distance metrics and their associated values.
+   */
   val namedMetricLookup = Map('Chebyshev -> 1.0, 'Cosine -> 2.0)
 
+    /**
+      * Selects a distance metric based on the provided value.
+      *
+      * @param dm The value associated with the desired distance metric.
+      *
+      * @return The distance metric associated with `dm`.
+      */
   def select(dm: Double): DistanceMetric = {
     dm match {
       case 1.0 => Chebyshev
@@ -36,13 +62,37 @@ object DistanceMetricSelector extends Serializable{
   }
 }
 
+/**
+ * Object representing the Chebyshev distance metric.
+ */
 object Chebyshev extends DistanceMetric {
+/**
+   * Computes the Chebyshev distance between two vectors.
+   *
+   * @param v1 The first vector.
+   * @param v2 The second vector.
+   *
+   * @return The Chebyshev distance between `v1` and `v2`.
+   *
+   * @throws CardinalityException If `v1` and `v2` have different dimensions.
+   */
   def distance(v1: Vector, v2: Vector): Double =  {
     if (v1.size != v2.size) throw new CardinalityException(v1.size, v2.size)
     v1.aggregate(v2, Functions.MAX_ABS, Functions.MINUS)
   }
 }
 
+/**
+ * Object representing the Cosine distance metric.
+ */
 object Cosine extends DistanceMetric {
+    /**
+       * Computes the Cosine distance between two vectors.
+       *
+       * @param v1 The first vector.
+       * @param v2 The second vector.
+       *
+       * @return The Cosine distance between `v1` and `v2`.
+       */
   def distance(v1: Vector, v2: Vector): Double = 1.0 - v1.dot(v2) / (Math.sqrt(v1.getLengthSquared) * Math.sqrt(v2.getLengthSquared))
 }