Polish SimpleCommandLinePropertySource support

spring-core/src/main/java/org/springframework/core/env/CommandLineArgs.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 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.
@@ -26,8 +26,9 @@ import java.util.Set;
 import org.springframework.lang.Nullable;
 
 /**
- * A simple representation of command line arguments, broken into "option arguments" and
- * "non-option arguments".
+ * A simple representation of command line arguments, broken into
+ * {@linkplain #addOptionArg(String, String) option arguments} and
+ * {@linkplain #addNonOptionArg(String) non-option arguments}.
  *
  * @author Chris Beams
  * @since 3.1
@@ -39,10 +40,10 @@ class CommandLineArgs {
 	private final List<String> nonOptionArgs = new ArrayList<>();
 
 	/**
-	 * Add an option argument for the given option name and add the given value to the
+	 * Add an option argument for the given option name, and add the given value to the
 	 * list of values associated with this option (of which there may be zero or more).
-	 * The given value may be {@code null}, indicating that the option was specified
-	 * without an associated value (e.g. "--foo" vs. "--foo=bar").
+	 * <p>The given value may be {@code null}, indicating that the option was specified
+	 * without an associated value &mdash; for example, "--foo" vs. "--foo=bar".
 	 */
 	public void addOptionArg(String optionName, @Nullable String optionValue) {
 		if (!this.optionArgs.containsKey(optionName)) {
@@ -54,7 +55,7 @@ class CommandLineArgs {
 	}
 
 	/**
-	 * Return the set of all option arguments present on the command line.
+	 * Return the set of the names of all option arguments present on the command line.
 	 */
 	public Set<String> getOptionNames() {
 		return Collections.unmodifiableSet(this.optionArgs.keySet());
@@ -68,9 +69,9 @@ class CommandLineArgs {
 	}
 
 	/**
-	 * Return the list of values associated with the given option. {@code null} signifies
-	 * that the option was not present; empty list signifies that no values were associated
-	 * with this option.
+	 * Return the list of values associated with the given option.
+	 * <p>{@code null} signifies that the option was not present on the command
+	 * line. An empty list signifies that no values were associated with this option.
 	 */
 	@Nullable
 	public List<String> getOptionValues(String optionName) {

spring-core/src/main/java/org/springframework/core/env/SimpleCommandLineArgsParser.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.
@@ -30,13 +30,6 @@ package org.springframework.core.env;
  * <em>without spaces</em> by an equals sign ("="). The value may optionally be
  * an empty string.
  *
- * <p>This parser supports the POSIX "end of options" delimiter, meaning that
- * any {@code "--"} (empty option name) in the command signals that all remaining
- * arguments will non-optional. For example, here {@code "--opt=ignored"} is considered
- * as a non-optional argument.
- * <pre class="code">
- * --foo=bar -- --opt=ignored</pre>
- *
  * <h4>Valid examples of option arguments</h4>
  * <pre class="code">
  * --foo
@@ -53,15 +46,26 @@ package org.springframework.core.env;
  * --foo = bar
  * --foo=bar --foo=baz --foo=biz</pre>
  *
+ * <h3>End of option arguments</h3>
+ * <p>This parser supports the POSIX "end of options" delimiter, meaning that any
+ * {@code "--"} (empty option name) in the command line signals that all remaining
+ * arguments are non-option arguments. For example, {@code "--opt1=ignored"},
+ * {@code "--opt2"}, and {@code "filename"} in the following command line are
+ * considered non-option arguments.
+ * <pre class="code">
+ * --foo=bar -- --opt1=ignored -opt2 filename</pre>
+ *
  * <h3>Working with non-option arguments</h3>
- * <p>Any and all arguments specified at the command line without the "{@code --}"
- * option prefix will be considered as "non-option arguments" and made available
- * through the {@link CommandLineArgs#getNonOptionArgs()} method.
+ * <p>Any arguments following the "end of options" delimiter ({@code --}) or
+ * specified without the "{@code --}" option prefix will be considered as
+ * "non-option arguments" and made available through the
+ * {@link CommandLineArgs#getNonOptionArgs()} method.
  *
  * @author Chris Beams
  * @author Sam Brannen
  * @author Brian Clozel
  * @since 3.1
+ * @see SimpleCommandLinePropertySource
  */
 class SimpleCommandLineArgsParser {
 
@@ -90,7 +94,7 @@ class SimpleCommandLineArgsParser {
 					commandLineArgs.addOptionArg(optionText, null);
 				}
 				else {
-					// '--' End of options delimiter, all remaining args must be non-optional
+					// '--' End of options delimiter, all remaining args are non-option arguments
 					endOfOptions = true;
 				}
 			}

spring-core/src/main/java/org/springframework/core/env/SimpleCommandLinePropertySource.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.
@@ -58,10 +58,20 @@ import org.springframework.util.StringUtils;
  * --foo = bar
  * --foo=bar --foo=baz --foo=biz</pre>
  *
+ * <h3>End of option arguments</h3>
+ * <p>The underlying parser supports the POSIX "end of options" delimiter, meaning
+ * that any {@code "--"} (empty option name) in the command line signals that all
+ * remaining arguments are non-option arguments. For example, {@code "--opt1=ignored"},
+ * {@code "--opt2"}, and {@code "filename"} in the following command line are
+ * considered non-option arguments.
+ * <pre class="code">
+ * --foo=bar -- --opt1=ignored -opt2 filename</pre>
+ *
  * <h3>Working with non-option arguments</h3>
- * <p>Any and all arguments specified at the command line without the "{@code --}"
- * option prefix will be considered as "non-option arguments" and made available
- * through the {@link CommandLineArgs#getNonOptionArgs()} method.
+ * <p>Any arguments following the "end of options" delimiter ({@code --}) or
+ * specified without the "{@code --}" option prefix will be considered as
+ * "non-option arguments" and made available through the
+ * {@link CommandLineArgs#getNonOptionArgs()} method.
  *
  * <h3>Typical usage</h3>
  * <pre class="code">