--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/make/nashorn/buildtools/nasgen/README	Tue Sep 12 19:03:39 2017 +0200
@@ -0,0 +1,34 @@
+Nasgen is a tool for processing Java classes that implement native
+JavaScript objects. It does so by looking for the
+com.oracle.nashorn.objects.annotations.ScriptClass annotation and other
+annotations in that package.
+
+For each  class "C", nasgen instruments the original class and generates
+two additional classes: a "C$Prototype" class for the JavaScript
+prototype object, and a "C$Constructor" class for the JavaScript
+constructor function.
+
+Each class instrumented or generated by nasgen contains a private static
+"$nasgenmap$" field of type com.oracle.nashorn.runtime.PropertyMap and
+static initializer block to initialize the field to the object's
+JavaScript properties.
+
+Members annotated with @Function, @Property, @Getter, and @Setter are
+mapped to the $Constructor, $Prototype, or main class, depending on the
+value of the annotation's 'where' field. By default, @Property, @Getter,
+and @Setter belong to the main class while @Function methods without
+explicit 'where' field belong to the $Prototype class. The @Constructor
+annotation marks a method to be invoked as JavaScript constructor.
+
+Nasgen enforces all @Function/@Getter/@Setter/@Constructor annotated
+methods to be declared as static. Static final @Property fields remain
+in the main class while other @Property fields are moved to respective
+classes depending on the annotation's 'where' value. For functions
+mapped to the $Prototype or $Constructor class, nasgen also generates
+getters and setters prefixed by G$ and S$, respectively.
+
+Nasgen-generated classes are hidden from normal ClassLoaders by giving
+them a ".clazz" file name extension instead of the standard ".class"
+extension. This allows script classes to be loaded independently by each
+Nashorn context through the com.oracle.nashorn.runtime.StructureLoader
+class loader.