Polishing.

Author: mp911de

src/main/java/org/springframework/data/domain/Range.java

@@ -223,7 +223,7 @@ public boolean contains(T value, Comparator<T> comparator) {
 	/**
 	 * Apply a mapping {@link Function} to the lower and upper boundary values.
 	 *
-	 * @param mapper must not be {@literal null}. If the mapper returns {@code null}, then the corresponding boundary
+	 * @param mapper must not be {@literal null}. If the mapper returns {@literal null}, then the corresponding boundary
 	 *          value represents an {@link Bound#unbounded()} boundary.
 	 * @return a new {@link Range} after applying the value to the mapper.
 	 * @param <R> target type of the mapping function.
@@ -430,7 +430,7 @@ public boolean isInclusive() {
 		/**
 		 * Apply a mapping {@link Function} to the boundary value.
 		 *
-		 * @param mapper must not be {@literal null}. If the mapper returns {@code null}, then the boundary value
+		 * @param mapper must not be {@literal null}. If the mapper returns {@literal null}, then the boundary value
 		 *          corresponds with {@link Bound#unbounded()}.
 		 * @return a new {@link Bound} after applying the value to the mapper.
 		 * @param <R>

src/main/java/org/springframework/data/domain/Score.java

@@ -20,11 +20,18 @@
 import org.springframework.util.ObjectUtils;
 
 /**
- * Value object to represent search result scores determined by a {@link ScoringFunction}. Scores are used to rank
- * search results and typically, a higher score indicates a more relevant result.
+ * Value object representing a search result score computed via a {@link ScoringFunction}.
+ * <p>
+ * Encapsulates the numeric score and the scoring function used to derive it. Scores are primarily used to rank search
+ * results. Depending on the used {@link ScoringFunction} higher scores can indicate either a higher distance or a
+ * higher similarity. Use the {@link Similarity} class to indicate usage of a normalized score across representing
+ * effectively the similarity.
+ * <p>
+ * Instances of this class are immutable and suitable for use in comparison, sorting, and range operations.
  *
  * @author Mark Paluch
  * @since 4.0
+ * @see Similarity
  */
 public sealed class Score implements Serializable permits Similarity {
 
@@ -37,13 +44,13 @@ public sealed class Score implements Serializable permits Similarity {
 	}
 
 	/**
-	 * Creates a new {@link Score} from a plain {@code score} value using {@link ScoringFunction#UNSPECIFIED}.
+	 * Creates a new {@link Score} from a plain {@code score} value using {@link ScoringFunction#unspecified()}.
 	 *
 	 * @param score the score value without a specific {@link ScoringFunction}.
 	 * @return the new {@link Score}.
 	 */
 	public static Score of(double score) {
-		return of(score, ScoringFunction.UNSPECIFIED);
+		return of(score, ScoringFunction.unspecified());
 	}
 
 	/**
@@ -58,20 +65,30 @@ public static Score of(double score, ScoringFunction function) {
 	}
 
 	/**
-	 * Creates a {@link Range} between the given {@link Score}.
+	 * Creates a {@link Range} from the given minimum and maximum {@code Score} values.
 	 *
-	 * @param min can be {@literal null}.
-	 * @param max can be {@literal null}.
-	 * @return will never be {@literal null}.
+	 * @param min the lower score value, must not be {@literal null}.
+	 * @param max the upper score value, must not be {@literal null}.
+	 * @return a {@link Range} over {@link Score} bounds.
 	 */
 	public static Range<Score> between(Score min, Score max) {
 		return Range.from(Range.Bound.inclusive(min)).to(Range.Bound.inclusive(max));
 	}
 
+	/**
+	 * Returns the raw numeric value of the score.
+	 *
+	 * @return the score value.
+	 */
 	public double getValue() {
 		return value;
 	}
 
+	/**
+	 * Returns the {@link ScoringFunction} that was used to compute this score.
+	 *
+	 * @return the associated scoring function.
+	 */
 	public ScoringFunction getFunction() {
 		return function;
 	}

src/main/java/org/springframework/data/domain/ScoringFunction.java

@@ -16,15 +16,72 @@
 package org.springframework.data.domain;
 
 /**
+ * Strategy interface for scoring functions.
+ * <p>
+ * Implementations define how score (distance or similarity) between two vectors is computed, allowing control over
+ * ranking behavior in search queries.
+ * <p>
+ * Provides commonly used scoring variants via static factory methods. See {@link VectorScoringFunctions} for the
+ * concrete implementations.
+ *
  * @author Mark Paluch
  * @since 4.0
+ * @see Score
+ * @see Similarity
  */
 public interface ScoringFunction {
 
 	/**
-	 * The default {@link ScoringFunction} when none is specified.
+	 * Returns the default {@code ScoringFunction} to be used when none is explicitly specified.
+	 * <p>
+	 * This is typically used to indicate the absence of a scoring definition.
+	 *
+	 * @return the default {@code ScoringFunction} instance.
+	 */
+	static ScoringFunction unspecified() {
+		return UnspecifiedScoringFunction.INSTANCE;
+	}
+
+	/**
+	 * Return the Euclidean distance scoring function.
+	 * <p>
+	 * Calculates the L2 norm (straight-line distance) between two vectors.
+	 *
+	 * @return the {@code ScoringFunction} based on Euclidean distance.
+	 */
+	static ScoringFunction euclidean() {
+		return VectorScoringFunctions.EUCLIDEAN;
+	}
+
+	/**
+	 * Return the cosine similarity scoring function.
+	 * <p>
+	 * Measures the cosine of the angle between two vectors, independent of magnitude.
+	 *
+	 * @return the {@code ScoringFunction} based on cosine similarity.
 	 */
-	ScoringFunction UNSPECIFIED = UnspecifiedScoringFunction.INSTANCE;
+	static ScoringFunction cosine() {
+		return VectorScoringFunctions.COSINE;
+	}
 
+	/**
+	 * Return the dot product (inner product) scoring function.
+	 * <p>
+	 * Computes the algebraic product of two vectors, considering both direction and magnitude.
+	 *
+	 * @return the {@code ScoringFunction} based on dot product.
+	 */
+	static ScoringFunction dotProduct() {
+		return VectorScoringFunctions.DOT_PRODUCT;
+	}
+
+	/**
+	 * Return the name of the scoring function.
+	 * <p>
+	 * Typically used for display or configuration purposes.
+	 *
+	 * @return the identifying name of this scoring function.
+	 */
 	String getName();
+
 }

src/main/java/org/springframework/data/domain/SearchResult.java

@@ -25,10 +25,17 @@
 import org.springframework.util.ObjectUtils;
 
 /**
- * Value object capturing some arbitrary object plus a distance.
+ * Immutable value object representing a search result consisting of a content item and an associated {@link Score}.
+ * <p>
+ * Typically used in the context of similarity-based or vector search operations where each result carries a relevance
+ * {@link Score}. Provides accessor methods for the content and its score, along with transformation support via
+ * {@link #map(Function)}.
  *
+ * @param <T> the type of the content object
  * @author Mark Paluch
  * @since 4.0
+ * @see Score
+ * @see Similarity
  */
 public final class SearchResult<T> implements Serializable {
 
@@ -37,6 +44,12 @@ public final class SearchResult<T> implements Serializable {
 	private final T content;
 	private final Score score;
 
+	/**
+	 * Creates a new {@link SearchResult} with the given content and {@link Score}.
+	 *
+	 * @param content the result content, must not be {@literal null}.
+	 * @param score the result score, must not be {@literal null}.
+	 */
 	public SearchResult(T content, Score score) {
 
 		Assert.notNull(content, "Content must not be null");
@@ -46,18 +59,44 @@ public SearchResult(T content, Score score) {
 		this.score = score;
 	}
 
+	/**
+	 * Create a new {@link SearchResult} with the given content and a raw score value.
+	 *
+	 * @param content the result content, must not be {@literal null}.
+	 * @param score the score value.
+	 */
 	public SearchResult(T content, double score) {
 		this(content, Score.of(score));
 	}
 
+	/**
+	 * Returns the content associated with this result.
+	 */
 	public T getContent() {
 		return this.content;
 	}
 
+	/**
+	 * Returns the {@link Score} associated with this result.
+	 */
 	public Score getScore() {
 		return this.score;
 	}
 
+	/**
+	 * Creates a new {@link SearchResult} by applying the given mapping {@link Function} to this result's content.
+	 *
+	 * @param converter the mapping function to apply to the content, must not be {@literal null}.
+	 * @return a new {@link SearchResult} instance with converted content.
+	 * @param <U> the target type of the mapped content.
+	 */
+	public <U> SearchResult<U> map(Function<? super T, ? extends U> converter) {
+
+		Assert.notNull(converter, "Function must not be null");
+
+		return new SearchResult<>(converter.apply(getContent()), getScore());
+	}
+
 	@Override
 	public boolean equals(@Nullable Object o) {
 
@@ -86,17 +125,4 @@ public String toString() {
 		return String.format("SearchResult [content: %s, score: %s]", content, score);
 	}
 
-	/**
-	 * Returns new {@link SearchResults} with the content of the current one mapped by the given {@link Function}.
-	 *
-	 * @param converter must not be {@literal null}.
-	 * @return a new {@link SearchResults} with the content of the current one mapped by the given {@link Function}.
-	 */
-	public <U> SearchResult<U> map(Function<? super T, ? extends U> converter) {
-
-		Assert.notNull(converter, "Function must not be null");
-
-		return new SearchResult<>(converter.apply(getContent()), getScore());
-	}
-
 }

src/main/java/org/springframework/data/domain/SearchResults.java

@@ -21,29 +21,39 @@
 import java.util.List;
 import java.util.function.Function;
 import java.util.stream.Collectors;
+import java.util.stream.Stream;
 
+import org.springframework.data.util.Streamable;
 import org.springframework.util.Assert;
 import org.springframework.util.ObjectUtils;
 import org.springframework.util.StringUtils;
 
 /**
- * Value object to capture {@link SearchResult}s.
+ * Value object encapsulating a collection of {@link SearchResult} instances.
+ * <p>
+ * Typically used as the result type for search or similarity queries, exposing access to the result content and
+ * supporting mapping operations to transform the result content type.
  *
+ * @param <T> the type of content contained within each {@link SearchResult}.
  * @author Mark Paluch
  * @since 4.0
+ * @see SearchResult
  */
 public class SearchResults<T> implements Iterable<SearchResult<T>>, Serializable {
 
 	private final List<? extends SearchResult<T>> results;
 
-	public SearchResults(List<SearchResult<T>> results) {
+	/**
+	 * Creates a new {@link SearchResults} instance from the given list of {@link SearchResult} items.
+	 *
+	 * @param results the search results to encapsulate, must not be {@code null}
+	 */
+	public SearchResults(List<? extends SearchResult<T>> results) {
 		this.results = results;
 	}
 
 	/**
-	 * Returns the actual content of the {@link SearchResult}s.
-	 *
-	 * @return the actual content.
+	 * Return the actual content of the {@link SearchResult} items as an unmodifiable list.
 	 */
 	public List<SearchResult<T>> getContent() {
 		return Collections.unmodifiableList(results);
@@ -56,10 +66,33 @@ public Iterator<SearchResult<T>> iterator() {
 	}
 
 	/**
-	 * Returns new {@link SearchResults} with the content of the current one mapped by the given {@link Function}.
+	 * Returns a sequential {@link Stream} containing {@link SearchResult} items in this {@code SearchResults} instance.
+	 *
+	 * @return a sequential {@link Stream} containing {@link SearchResult} items in this {@code SearchResults} instance.
+	 */
+	public Stream<SearchResult<T>> stream() {
+		return Streamable.of(this).stream();
+	}
+
+	/**
+	 * Returns a sequential {@link Stream} containing {@link #getContent() unwrapped content} items in this
+	 * {@code SearchResults} instance.
+	 *
+	 * @return a sequential {@link Stream} containing {@link #getContent() unwrapped content} items in this
+	 *         {@code SearchResults} instance.
+	 */
+	public Stream<T> contentStream() {
+		return getContent().stream().map(SearchResult::getContent);
+	}
+
+	/**
+	 * Creates a new {@code SearchResults} instance with the content of the current results mapped via the given
+	 * {@link Function}.
 	 *
-	 * @param converter must not be {@literal null}.
-	 * @return a new {@link SearchResults} with the content of the current one mapped by the given {@link Function}.
+	 * @param converter the mapping function to apply to the content of each {@link SearchResult}, must not be
+	 *          {@literal null}.
+	 * @param <U> the target type of the mapped content.
+	 * @return a new {@code SearchResults} instance containing mapped result content.
 	 */
 	public <U> SearchResults<U> map(Function<? super T, ? extends U> converter) {