diff --git a/xml/src/main/java/org/springframework/xml/xpath/XPathExpression.java b/xml/src/main/java/org/springframework/xml/xpath/XPathExpression.java
index eece0bc4..e0d88ace 100644
--- a/xml/src/main/java/org/springframework/xml/xpath/XPathExpression.java
+++ b/xml/src/main/java/org/springframework/xml/xpath/XPathExpression.java
@@ -35,11 +35,18 @@ public interface XPathExpression {
/**
* Evaluates the given expression as a boolean. Returns the boolean evaluation of the expression, or
* false if it is invalid.
+ *
double). Returns the numeric evaluation of the
* expression, or {@link Double#NaN} if it is invalid.
+ *
+ * The return value is determined per the {@code number()} function as defined in the XPath specification.
+ * This means that if the expression selects multiple nodes, it will return the number value of the first node.
*
* @param node the starting point
* @return the result of the evaluation
* @throws XPathException in case of XPath errors
- * @see XPath specification
+ * @see XPath specification - number() function
*/
double evaluateAsNumber(Node node) throws XPathException;
/**
* Evaluates the given expression as a String. Returns null if no result could be found.
+ *
+ * The return value is determined per the {@code string()} function as defined in the XPath specification.
+ * This means that if the expression selects multiple nodes, it will return the string value of the first node.
*
* @param node the starting point
* @return the result of the evaluation
* @throws XPathException in case of XPath errors
- * @see XPath specification
+ * @see XPath specification - string() function
*/
String evaluateAsString(Node node) throws XPathException;
diff --git a/xml/src/main/java/org/springframework/xml/xpath/XPathOperations.java b/xml/src/main/java/org/springframework/xml/xpath/XPathOperations.java
index 32086c4d..beadd7f2 100644
--- a/xml/src/main/java/org/springframework/xml/xpath/XPathOperations.java
+++ b/xml/src/main/java/org/springframework/xml/xpath/XPathOperations.java
@@ -38,12 +38,19 @@ public interface XPathOperations {
/**
* Evaluates the given expression as a boolean. Returns the boolean evaluation of the expression, or
* false if it is invalid.
+ *
+ * The return value is determined per the {@code boolean()} function defined in the XPath specification.
+ * This means that an expression that selects zero nodes will return {@code false}, while an expression that
+ * selects one or more nodes will return {@code true}.
+ * An expression that returns a string returns {@code false} for empty strings and {@code true} for all other
+ * strings.
+ * An expression that returns a number returns {@code false} for zero and {@code true} for non-zero numbers.
*
* @param expression the XPath expression
* @param context the context starting point
* @return the result of the evaluation
* @throws XPathException in case of XPath errors
- * @see XPath specification
+ * @see XPath specification - boolean() function
*/
boolean evaluateAsBoolean(String expression, Source context) throws XPathException;
@@ -74,24 +81,30 @@ public interface XPathOperations {
/**
* Evaluates the given expression as a double. Returns the evaluation of the expression, or {@link
* Double#NaN} if it is invalid.
- *
+ *
+ * The return value is determined per the {@code number()} function as defined in the XPath specification.
+ * This means that if the expression selects multiple nodes, it will return the number value of the first node.
+ *
* @param expression the XPath expression
* @param context the context starting point
* @return the result of the evaluation
* @throws XPathException in case of XPath errors
- * @see XPath specification
+ * @see XPath specification - number() function
*/
double evaluateAsDouble(String expression, Source context) throws XPathException;
/**
* Evaluates the given expression as a {@link String}. Returns the evaluation of the expression, or
* null if it is invalid.
+ *
+ * The return value is determined per the {@code string()} function as defined in the XPath specification.
+ * This means that if the expression selects multiple nodes, it will return the string value of the first node.
*
* @param expression the XPath expression
* @param context the context starting point
* @return the result of the evaluation
* @throws XPathException in case of XPath errors
- * @see XPath specification
+ * @see XPath specification - string() function
*/
String evaluateAsString(String expression, Source context) throws XPathException;