clarify the warning of the unboxable-type-in-primitive warning

A discussion in a forum thread
  https://discuss.ocaml.org/t/primitive-declaration-is-unannotated-and-unboxable/4306
points out that 'unboxable' is ambiguous as it can be read as either
un-boxable or unbox-able.

This commit reformulates the warning to avoid using 'unboxable', but
the very explicit 'may be either boxed or unboxed', along with a more
detailed explanation of the issue that the warning is about.

Changes

@@ -175,6 +175,9 @@ Working version
   pretty-printing boxes.
   (Oxana Kostikova, review by Gabriel Scherer)
 
+- #8914: clarify the warning on unboxable types used in external primitives (61)
+  (Gabriel Scherer, review by Florian Angeletti, report on the Discourse forum)
+
 ### Bug fixes:
 
 - #8622: Don't generate #! headers over 127 characters.

testsuite/tests/typing-unboxed/test.ml

@@ -413,10 +413,14 @@ type i = I of int
 Line 2, characters 0-34:
 2 | external id : i -> i = "%identity";;
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Warning 61: This primitive declaration uses type i, which is unannotated and
-unboxable. The representation of such types may change in future
-versions. You should annotate the declaration of i with [@@boxed]
-or [@@unboxed].
+Warning 61: This primitive declaration uses type i, whose representation
+may be either boxed or unboxed. Without an annotation to indicate
+which representation is intended, the boxed representation has been
+selected by default, but this default choice may change in future
+versions of the compiler, breaking the primitive implementation.
+You should explicitly annotate the declaration of i
+with [@@boxed] or [@@unboxed], so that its external interface
+remains stable in the future.
 external id : i -> i = "%identity"
 |}];;
 
@@ -429,17 +433,25 @@ type j = J of int
 Line 3, characters 0-34:
 3 | external id : i -> j = "%identity";;
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Warning 61: This primitive declaration uses type i, which is unannotated and
-unboxable. The representation of such types may change in future
-versions. You should annotate the declaration of i with [@@boxed]
-or [@@unboxed].
+Warning 61: This primitive declaration uses type i, whose representation
+may be either boxed or unboxed. Without an annotation to indicate
+which representation is intended, the boxed representation has been
+selected by default, but this default choice may change in future
+versions of the compiler, breaking the primitive implementation.
+You should explicitly annotate the declaration of i
+with [@@boxed] or [@@unboxed], so that its external interface
+remains stable in the future.
 Line 3, characters 0-34:
 3 | external id : i -> j = "%identity";;
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Warning 61: This primitive declaration uses type j, which is unannotated and
-unboxable. The representation of such types may change in future
-versions. You should annotate the declaration of j with [@@boxed]
-or [@@unboxed].
+Warning 61: This primitive declaration uses type j, whose representation
+may be either boxed or unboxed. Without an annotation to indicate
+which representation is intended, the boxed representation has been
+selected by default, but this default choice may change in future
+versions of the compiler, breaking the primitive implementation.
+You should explicitly annotate the declaration of j
+with [@@boxed] or [@@unboxed], so that its external interface
+remains stable in the future.
 external id : i -> j = "%identity"
 |}];;
 

utils/warnings.ml

@@ -604,10 +604,14 @@ let message = function
   | Unused_module s -> "unused module " ^ s ^ "."
   | Unboxable_type_in_prim_decl t ->
       Printf.sprintf
-        "This primitive declaration uses type %s, which is unannotated and\n\
-         unboxable. The representation of such types may change in future\n\
-         versions. You should annotate the declaration of %s with [@@boxed]\n\
-         or [@@unboxed]." t t
+        "This primitive declaration uses type %s, whose representation\n\
+         may be either boxed or unboxed. Without an annotation to indicate\n\
+         which representation is intended, the boxed representation has been\n\
+         selected by default, but this default choice may change in future\n\
+         versions of the compiler, breaking the primitive implementation.\n\
+         You should explicitly annotate the declaration of %s\n\
+         with [@@boxed] or [@@unboxed], so that its external interface\n\
+         remains stable in the future." t t
   | Constraint_on_gadt ->
       "Type constraints do not apply to GADT cases of variant types."
   | Erroneous_printed_signature s ->