Summary

Make well-behaved return value of Object.toString() explicit in the javadoc of that method.

Problem

In some contexts, it would be helpful to know that Object.toString() returning null was out of the interface contract for that method.

Solution

Add an explicit statement to Object.toString() prohibiting returning null.

Specification

diff --git a/src/java.base/share/classes/java/lang/Object.java b/src/java.base/share/classes/java/lang/Object.java
index b8bfdc3e3f9..affc94479ca 100644
--- a/src/java.base/share/classes/java/lang/Object.java
+++ b/src/java.base/share/classes/java/lang/Object.java
@@ -237,6 +242,10 @@ public boolean equals(Object obj) {

     /**
      * {@return a string representation of the object}
+     *
+     * Satisfying this method's contract implies a non-{@code null}
+     * result must be returned.
+     *
      * @apiNote
      * In general, the
      * {@code toString} method returns a string that