Improve Javadoc for core SpEL APIs

Author: sbrannen

spring-expression/src/main/java/org/springframework/expression/ExpressionParser.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2009 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,7 +18,8 @@
 
 /**
  * Parses expression strings into compiled expressions that can be evaluated.
- * Supports parsing templates as well as standard expression strings.
+ *
+ * <p>Supports parsing template expressions as well as standard expression strings.
  *
  * @author Keith Donald
  * @author Andy Clement
@@ -27,29 +28,31 @@
 public interface ExpressionParser {
 
 	/**
-	 * Parse the expression string and return an Expression object you can use for repeated evaluation.
-	 * <p>Some examples:
+	 * Parse the expression string and return an {@link Expression} object that
+	 * can be used for repeated evaluation.
+	 * <p>Examples:
 	 * <pre class="code">
 	 *     3 + 4
 	 *     name.firstName
 	 * </pre>
 	 * @param expressionString the raw expression string to parse
-	 * @return an evaluator for the parsed expression
-	 * @throws ParseException an exception occurred during parsing
+	 * @return an {@code Expression} for the parsed expression
+	 * @throws ParseException if an exception occurred during parsing
 	 */
 	Expression parseExpression(String expressionString) throws ParseException;
 
 	/**
-	 * Parse the expression string and return an Expression object you can use for repeated evaluation.
-	 * <p>Some examples:
+	 * Parse the expression string and return an {@link Expression} object that
+	 * can be used for repeated evaluation.
+	 * <p>Examples:
 	 * <pre class="code">
 	 *     3 + 4
 	 *     name.firstName
 	 * </pre>
 	 * @param expressionString the raw expression string to parse
-	 * @param context a context for influencing this expression parsing routine (optional)
-	 * @return an evaluator for the parsed expression
-	 * @throws ParseException an exception occurred during parsing
+	 * @param context a context for influencing the expression parsing routine
+	 * @return an {@code Expression} for the parsed expression
+	 * @throws ParseException if an exception occurred during parsing
 	 */
 	Expression parseExpression(String expressionString, ParserContext context) throws ParseException;
 

spring-expression/src/main/java/org/springframework/expression/ParserContext.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -47,16 +47,17 @@ public interface ParserContext {
 	String getExpressionPrefix();
 
 	/**
-	 * For template expressions, return the prefix that identifies the end of an
+	 * For template expressions, returns the prefix that identifies the end of an
 	 * expression block within a string. For example: "}"
 	 * @return the suffix that identifies the end of an expression
 	 */
 	String getExpressionSuffix();
 
 
 	/**
-	 * The default ParserContext implementation that enables template expression
-	 * parsing mode. The expression prefix is "#{" and the expression suffix is "}".
+	 * The default {@link ParserContext} implementation that enables template
+	 * expression parsing.
+	 * <p>The expression prefix is "#{", and the expression suffix is "}".
 	 * @see #isTemplate()
 	 */
 	ParserContext TEMPLATE_EXPRESSION = new ParserContext() {

spring-expression/src/main/java/org/springframework/expression/common/TemplateAwareExpressionParser.java

@@ -29,8 +29,11 @@
 import org.springframework.util.Assert;
 
 /**
- * An expression parser that understands templates. It can be subclassed by expression
- * parsers that do not offer first class support for templating.
+ * Abstract base class for {@linkplain ExpressionParser expression parsers} that
+ * support templates.
+ *
+ * <p>Can be subclassed by expression parsers that offer first class support for
+ * templating.
  *
  * @author Keith Donald
  * @author Juergen Hoeller
@@ -88,7 +91,7 @@ private Expression parseTemplate(String expressionString, ParserContext context)
 	 * single quote '.
 	 * @param expressionString the expression string
 	 * @return the parsed expressions
-	 * @throws ParseException when the expressions cannot be parsed
+	 * @throws ParseException if the expressions cannot be parsed
 	 */
 	private Expression[] parseExpressions(String expressionString, ParserContext context) throws ParseException {
 		List<Expression> expressions = new ArrayList<>();
@@ -229,7 +232,7 @@ private int skipToCorrectEndSuffix(String suffix, String expressionString, int a
 	 * @param expressionString the raw expression string to parse
 	 * @param context a context for influencing this expression parsing routine (optional)
 	 * @return an evaluator for the parsed expression
-	 * @throws ParseException an exception occurred during parsing
+	 * @throws ParseException if an exception occurred during parsing
 	 */
 	protected abstract Expression doParseExpression(String expressionString, @Nullable ParserContext context)
 			throws ParseException;