src/jdk.dynalink/share/classes/module-info.java

@@ -22,11 +22,46 @@
  * or visit www.oracle.com if you need additional information or have any
  * questions.
  */
 
 /**
- * Dynalink
+ * <p>
+ * Dynalink is a library for dynamic linking of high-level operations on objects.
+ * These operations include "read a property",
+ * "write a property", "invoke a function" and so on. Dynalink is primarily
+ * useful for implementing programming languages where at least some expressions
+ * have dynamic types (that is, types that can not be decided statically), and
+ * the operations on dynamic types are expressed as
+ * {@link java.lang.invoke.CallSite call sites}. These call sites will be
+ * linked to appropriate target {@link java.lang.invoke.MethodHandle method handles}
+ * at run time based on actual types of the values the expressions evaluated to.
+ * These can change between invocations, necessitating relinking the call site
+ * multiple times to accommodate new types; Dynalink handles all that and more.
+ * <p>
+ * Dynalink supports implementation of programming languages with object models
+ * that differ (even radically) from the JVM's class-based model and have their
+ * custom type conversions.
+ * <p>
+ * Dynalink is closely related to, and relies on, the {@link java.lang.invoke}
+ * package.
+ * <p>
+ *
+ * While {@link java.lang.invoke} provides a low level API for dynamic linking
+ * of {@code invokedynamic} call sites, it does not provide a way to express
+ * higher level operations on objects, nor methods that implement them. These
+ * operations are the usual ones in object-oriented environments: property
+ * access, access of elements of collections, invocation of methods and
+ * constructors (potentially with multiple dispatch, e.g. link- and run-time
+ * equivalents of Java overloaded method resolution). These are all functions
+ * that are normally desired in a language on the JVM. If a language is
+ * statically typed and its type system matches that of the JVM, it can
+ * accomplish this with use of the usual invocation, field access, etc.
+ * instructions (e.g. {@code invokevirtual}, {@code getfield}). However, if the
+ * language is dynamic (hence, types of some expressions are not known until
+ * evaluated at run time), or its object model or type system don't match
+ * closely that of the JVM, then it should use {@code invokedynamic} call sites
+ * instead and let Dynalink manage them.
  */
 module jdk.dynalink {
     requires java.logging;
 
     exports jdk.dynalink;