add explanations about status of module UnicodeNormalize

In lib/unicode_normalize/normalize.rb, add explanations and clarifications
about the status of the files and the module. [ci skip]
This is in response to discussions at https://github.com/ruby/spec/pull/433
and https://bugs.ruby-lang.org/issues/5481#note-58.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@58617 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 15 insertions, 0 deletions

diff --git a/lib/unicode_normalize/normalize.rb b/lib/unicode_normalize/normalize.rb
index 90579a3212..a2f7a29c88 100644
--- a/lib/unicode_normalize/normalize.rb
+++ b/lib/unicode_normalize/normalize.rb
@@ -3,6 +3,21 @@
 
 # Copyright Ayumu Nojima (野島 歩) and Martin J. Dürst (duerst@it.aoyama.ac.jp)
 
+# This file, the companion file tables.rb (autogenerated), and the module,
+# constants, and method defined herein are part of the implementation of the
+# built-in String class, not part of the standard library. They should
+# therefore never be gemified. They implement the methods
+# String#unicode_normalize, String#unicode_normalize!, and String#unicode_normalized?.
+#
+# They are placed here because they are written in Ruby. They are loaded on
+# demand when any of the three methods mentioned above is executed for the
+# first time. This reduces the memory footprint and startup time for scripts
+# and applications that do not use those methods.
+#
+# The name and even the existence of the module UnicodeNormalize and all of its
+# content are purely an implementation detail, and should not be exposed in
+# any test or spec or otherwise.
+
 require 'unicode_normalize/tables.rb'