[Native Image] Inconsistent appending of "." in deprecation error messages.

[edburns]

Describe the Issue

See #11554 . Notice the error message there has two periods at the end:

Consider including proxy configuration in the reflection section of reachability-metadata.md instead.. 

The reason for this is inconsistency between the values of the deprecationMessage attribute and callsites that interpolate those values.

From Copilot:

Here is a list of all code locations in the Graal codebase that call getDeprecationMessage() on OptionDescriptor for the purpose of interpolating it into a message string. For each, I indicate whether a "." is prepended (inserted before or after the deprecation message), so you can decide if the period should be in the attribute or in the interpolation code.

---

1. substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/option/SubstrateOptionsParser.java

Location:
parseHostedOption method

Usage:

if (deprecationMessage != null && !deprecationMessage.isEmpty()) {
    message += ": " + deprecationMessage;
}
message += ". Please refer to the GraalVM release notes.";

• "." prepended or appended?: Appended after the deprecation message (always adds a period after, regardless of whether it's already in the message).

---

2. substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/option/RuntimeOptionParser.java

Location:
parseOptionAtRuntime method

Usage:

if (deprecationMessage != null && !deprecationMessage.isEmpty()) {
    log.string(": ").string(deprecationMessage);
}
log.newline();

• "." prepended or appended?: No period added by the code (the message is interpolated as-is).

---

3. sdk/src/org.graalvm.launcher/src/org/graalvm/launcher/Launcher.java

Location:
argument parsing logic

Usage:

String messageFormat = "Option '%s' is deprecated and might be removed from future versions.";
String deprecationMessage = descriptor.getDeprecationMessage();
String message;
if (deprecationMessage != null) {
    message = String.format(messageFormat + "%n%s", descriptor.getName(), deprecationMessage);
} else {
    message = String.format(messageFormat, descriptor.getName());
}
warn(message);

• "." prepended or appended?: No period added before or after the deprecation message (since the format string already ends in a period, the deprecation message starts on a new line).

---

4. truffle/src/com.oracle.truffle.polyglot/src/com/oracle/truffle/polyglot/PolyglotEngineImpl.java

Location:
printDeprecatedOptionsWarning method

Usage:

String.format("Option '%s' is deprecated: %s. Please update the option or suppress this warning using the option 'engine.WarnOptionDeprecation=false'.",
    key.getName(), key.getDeprecationMessage())

• "." prepended or appended?: A period is always appended after the deprecation message (regardless of whether the message already ends with a period).

---

5. substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/option/RuntimeOptionValues.java

Location:
asDescriptor helper method

Usage:

return new DescriptorImpl(descriptor.getName(), help, ..., descriptor.isDeprecated(), descriptor.getDeprecationMessage());

• "." prepended or appended?: N/A (just stores the value, not for message printing).

---

Summary Table

File/Method	Appends/prepends "." to deprecation message?
SubstrateOptionsParser.parseHostedOption	Yes, always appends a period after
RuntimeOptionParser.parseOptionAtRuntime	No period added
Launcher.java (argument parsing)	No period added
PolyglotEngineImpl.printDeprecatedOptionsWarning	Yes, always appends a period after
RuntimeOptionValues (DescriptorImpl record)	N/A (not message interpolation)

---

Conclusion:

• Some places (SubstrateOptionsParser, PolyglotEngineImpl) always append a period after the deprecation message, even if one is already present.
• Others (RuntimeOptionParser, Launcher) do not add a period, and print the deprecation message as-is.
• There is inconsistency, so it's best to ensure the code that interpolates the deprecation message is responsible for punctuation, NOT the message itself, to avoid double periods (". .").

View more results in GitHub code search.

Let me know if you need the result for additional files or more details!

Using the latest version of GraalVM can resolve many issues.

• I tried with the latest version of GraalVM.

GraalVM Version

See #11554.

Operating System and Version

See #11554.

Build Command

See #11554.

Expected Behavior

Error messages do not have "..".

Actual Behavior

Error messages do have ".."

Steps to Reproduce

See #11554.

Additional Context

No response

Build Log Output and Error Messages

No response

[edburns]

Fixed by #11557 .

[edburns]

Analysis of Option.deprecationMessage Usage and Punctuation

Based on examining the codebase, here's what I've found regarding whether Option.deprecationMessage should include closing punctuation:

1. In most real-world examples, deprecation messages do not include closing punctuation (period/full stop):

   • "Please use '--gc=serial' instead"
   • "Please use '--parallelism' instead"
   • "It no longer has any effect, and no replacement is available"
   • "Please use '-march=native' instead. See '--help' for details"
   • "This option disables a major feature of GraalVM Native Image and will be removed in a future release"

2. How the messages are displayed:

   • In SubstrateOptionsParser.java, the message is displayed with a colon prefix: message += ": " + deprecationMessage;
   • In RuntimeOptionParser.java, a period is explicitly added: log.string(": ").string(deprecationMessage).string(".");
   • This suggests that when the code handles displaying deprecation messages, it sometimes adds punctuation, so the message itself doesn't need to include it.

3. Formatting in context:

   • When these messages are displayed in the console, they typically appear after other text and are formatted by the code that shows them.
   • In Launcher.java, the deprecation message is inserted into a format string with messageFormat + "%n%s", where it appears on a new line after other text.

4. Mixed practice:

   • While most examples don't include closing punctuation, there are some that do (particularly in test code).
   • The presence of explicit code to add a period in RuntimeOptionParser.java suggests that messages should NOT include periods, since they're added by the code.

5. Consistency:

   • The majority of production examples follow the pattern of NOT including closing punctuation.
   • The most consistent approach across the codebase is to omit the closing punctuation.

Conclusion

The evidence suggests that Option.deprecationMessage values should not include closing punctuation (period/full stop) because:

1. Most examples in the codebase omit it
2. At least one part of the code explicitly adds a period after the message
3. Messages are formatted by the code that displays them, with appropriate punctuation added as needed

Following this convention will ensure consistency with the majority of existing deprecation messages in the GraalVM codebase.