8085885: address Javadoc warnings in Nashorn source code
authormhaupt
Mon, 08 Jun 2015 10:28:04 +0200
changeset 31097 996397e0a35c
parent 31096 a3a697c1edd5
child 31098 e98a3ba5d5da
8085885: address Javadoc warnings in Nashorn source code Reviewed-by: hannesw, lagergren
nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/DynamicLinker.java
nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/codegen/ClassEmitter.java
nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/ir/LexicalContext.java
nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/annotations/Constructor.java
nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/annotations/Function.java
nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/annotations/Getter.java
nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/annotations/ScriptClass.java
nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/annotations/Setter.java
nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/annotations/SpecializedFunction.java
nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/parser/JSONParser.java
nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/parser/TokenType.java
nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/runtime/linker/JavaAdapterFactory.java
nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/runtime/regexp/joni/EncodingHelper.java
nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/runtime/regexp/joni/Syntax.java
--- a/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/DynamicLinker.java	Mon Jun 08 14:10:39 2015 +0530
+++ b/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/DynamicLinker.java	Mon Jun 08 10:28:04 2015 +0200
@@ -99,10 +99,12 @@
 import jdk.internal.dynalink.support.RuntimeContextLinkRequestImpl;
 
 /**
- * The linker for {@link RelinkableCallSite} objects. Users of it (scripting frameworks and language runtimes) have to
- * create a linker using the {@link DynamicLinkerFactory} and invoke its link method from the invokedynamic bootstrap
- * methods to set the target of all the call sites in the code they generate. Usual usage would be to create one class
- * per language runtime to contain one linker instance as:
+ * The linker for {@link RelinkableCallSite} objects. Users of it (scripting
+ * frameworks and language runtimes) have to create a linker using the
+ * {@link DynamicLinkerFactory} and invoke its link method from the invokedynamic
+ * bootstrap methods to set the target of all the call sites in the code they
+ * generate. Usual usage would be to create one class per language runtime to
+ * contain one linker instance as:
  *
  * <pre>
  * class MyLanguageRuntime {
@@ -123,19 +125,27 @@
  *
  * Note how there are three components you will need to provide here:
  * <ul>
- * <li>You're expected to provide a {@link GuardingDynamicLinker} for your own language. If your runtime doesn't
- * have its own language and/or object model (i.e. it's a generic scripting shell), you don't need to implement a
- * dynamic linker; you would simply not invoke the {@code setPrioritizedLinker} method on the factory, or even better,
- * simply use {@link DefaultBootstrapper}.</li>
- * <li>The performance of the programs can depend on your choice of the class to represent call sites. The above
- * example used {@link MonomorphicCallSite}, but you might want to use {@link ChainedCallSite} instead. You'll need to
- * experiment and decide what fits your language runtime the best. You can subclass either of these or roll your own if
- * you need to.</li>
- * <li>You also need to provide {@link CallSiteDescriptor}s to your call sites. They are immutable objects that contain
- * all the information about the call site: the class performing the lookups, the name of the method being invoked, and
- * the method signature. The library has a default {@link CallSiteDescriptorFactory} for descriptors that you can use,
- * or you can create your own descriptor classes, especially if you need to add further information (values passed in
+ *
+ * <li>You're expected to provide a {@link GuardingDynamicLinker} for your own
+ * language. If your runtime doesn't have its own language and/or object model
+ * (i.e., it's a generic scripting shell), you don't need to implement a dynamic
+ * linker; you would simply not invoke the {@code setPrioritizedLinker} method
+ * on the factory, or even better, simply use {@link DefaultBootstrapper}.</li>
+ *
+ * <li>The performance of the programs can depend on your choice of the class to
+ * represent call sites. The above example used {@link MonomorphicCallSite}, but
+ * you might want to use {@link ChainedCallSite} instead. You'll need to
+ * experiment and decide what fits your language runtime the best. You can
+ * subclass either of these or roll your own if you need to.</li>
+ *
+ * <li>You also need to provide {@link CallSiteDescriptor}s to your call sites.
+ * They are immutable objects that contain all the information about the call
+ * site: the class performing the lookups, the name of the method being invoked,
+ * and the method signature. The library has a default {@link CallSiteDescriptorFactory}
+ * for descriptors that you can use, or you can create your own descriptor
+ * classes, especially if you need to add further information (values passed in
  * additional parameters to the bootstrap method) to them.</li>
+ *
  * </ul>
  *
  * @author Attila Szegedi
@@ -176,11 +186,15 @@
     }
 
     /**
-     * Links an invokedynamic call site. It will install a method handle into the call site that invokes the relinking
-     * mechanism of this linker. Next time the call site is invoked, it will be linked for the actual arguments it was
-     * invoked with.
+     * Links an invokedynamic call site. It will install a method handle into
+     * the call site that invokes the relinking mechanism of this linker. Next
+     * time the call site is invoked, it will be linked for the actual arguments
+     * it was invoked with.
      *
+     * @param <T> the particular subclass of {@link RelinkableCallSite} for
+     *        which to create a link.
      * @param callSite the call site to link.
+     *
      * @return the callSite, for easy call chaining.
      */
     public <T extends RelinkableCallSite> T link(final T callSite) {
@@ -189,10 +203,13 @@
     }
 
     /**
-     * Returns the object representing the lower level linker services of this class that are normally exposed to
-     * individual language-specific linkers. While as a user of this class you normally only care about the
-     * {@link #link(RelinkableCallSite)} method, in certain circumstances you might want to use the lower level services
-     * directly; either to lookup specific method handles, to access the type converters, and so on.
+     * Returns the object representing the lower level linker services of this
+     * class that are normally exposed to individual language-specific linkers.
+     * While as a user of this class you normally only care about the
+     * {@link #link(RelinkableCallSite)} method, in certain circumstances you
+     * might want to use the lower level services directly; either to lookup
+     * specific method handles, to access the type converters, and so on.
+     *
      * @return the object representing the linker services of this class.
      */
     public LinkerServices getLinkerServices() {
@@ -218,7 +235,9 @@
      *
      * @param callSite the call site itself
      * @param arguments arguments to the invocation
+     *
      * @return return the method handle for the invocation
+     *
      * @throws Exception rethrows any exception thrown by the linkers
      */
     @SuppressWarnings("unused")
@@ -272,11 +291,15 @@
     }
 
     /**
-     * Returns a stack trace element describing the location of the call site currently being linked on the current
-     * thread. The operation internally creates a Throwable object and inspects its stack trace, so it's potentially
-     * expensive. The recommended usage for it is in writing diagnostics code.
-     * @return a stack trace element describing the location of the call site currently being linked, or null if it is
-     * not invoked while a call site is being linked.
+     * Returns a stack trace element describing the location of the call site
+     * currently being linked on the current thread. The operation internally
+     * creates a Throwable object and inspects its stack trace, so it's
+     * potentially expensive. The recommended usage for it is in writing
+     * diagnostics code.
+     *
+     * @return a stack trace element describing the location of the call site
+     *         currently being linked, or null if it is not invoked while a call
+     *         site is being linked.
      */
     public static StackTraceElement getLinkedCallSiteLocation() {
         final StackTraceElement[] trace = new Throwable().getStackTrace();
@@ -290,8 +313,10 @@
     }
 
     /**
-     * Deprecated because of not precise name.
+     * Deprecated because of imprecise name.
+     *
      * @deprecated Use {@link #getLinkedCallSiteLocation()} instead.
+     *
      * @return see non-deprecated method
      */
     @Deprecated
@@ -300,20 +325,26 @@
     }
 
     /**
-     * Returns true if the frame represents {@code MethodHandleNatives.linkCallSite()}, the frame immediately on top of
-     * the call site frame when the call site is being linked for the first time.
+     * Returns {@code true} if the frame represents {@code MethodHandleNatives.linkCallSite()},
+     * the frame immediately on top of the call site frame when the call site is
+     * being linked for the first time.
+     *
      * @param frame the frame
-     * @return true if this frame represents {@code MethodHandleNatives.linkCallSite()}
+     *
+     * @return {@code true} if this frame represents {@code MethodHandleNatives.linkCallSite()}.
      */
     private static boolean isInitialLinkFrame(final StackTraceElement frame) {
         return testFrame(frame, INITIAL_LINK_METHOD_NAME, INITIAL_LINK_CLASS_NAME);
     }
 
     /**
-     * Returns true if the frame represents {@code DynamicLinker.relink()}, the frame immediately on top of the call
-     * site frame when the call site is being relinked (linked for second and subsequent times).
+     * Returns {@code true} if the frame represents {@code DynamicLinker.relink()},
+     * the frame immediately on top of the call site frame when the call site is
+     * being relinked (linked for second and subsequent times).
+     *
      * @param frame the frame
-     * @return true if this frame represents {@code DynamicLinker.relink()}
+     *
+     * @return {@code true} if this frame represents {@code DynamicLinker.relink()}.
      */
     private static boolean isRelinkFrame(final StackTraceElement frame) {
         return testFrame(frame, RELINK_METHOD_NAME, CLASS_NAME);
--- a/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/codegen/ClassEmitter.java	Mon Jun 08 14:10:39 2015 +0530
+++ b/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/codegen/ClassEmitter.java	Mon Jun 08 10:28:04 2015 +0200
@@ -100,7 +100,6 @@
  * There is also a very nice debug interface that can emit formatted
  * bytecodes that have been written. This is enabled by setting the
  * environment "nashorn.codegen.debug" to true, or --log=codegen:{@literal <level>}
- * <p>
  *
  * @see Compiler
  */
@@ -144,7 +143,7 @@
 
     /**
      * Constructor - only used internally in this class as it breaks
-     * abstraction towards ASM or other code generator below
+     * abstraction towards ASM or other code generator below.
      *
      * @param env script environment
      * @param cw  ASM classwriter
@@ -157,7 +156,8 @@
     }
 
     /**
-     * Return the method names encountered
+     * Return the method names encountered.
+     *
      * @return method names
      */
     public Set<String> getMethodNames() {
@@ -165,12 +165,13 @@
     }
 
     /**
-     * Constructor
+     * Constructor.
      *
      * @param env             script environment
      * @param className       name of class to weave
      * @param superClassName  super class name for class
-     * @param interfaceNames  names of interfaces implemented by this class, or null if none
+     * @param interfaceNames  names of interfaces implemented by this class, or
+     *        {@code null} if none
      */
     ClassEmitter(final Context context, final String className, final String superClassName, final String... interfaceNames) {
         this(context, new ClassWriter(ClassWriter.COMPUTE_FRAMES | ClassWriter.COMPUTE_MAXS));
@@ -178,7 +179,7 @@
     }
 
     /**
-     * Constructor from the compiler
+     * Constructor from the compiler.
      *
      * @param env           Script environment
      * @param sourceName    Source name
@@ -217,7 +218,6 @@
     }
 
     /**
-     * Returns the name of the compile unit class name.
      * @return the name of the compile unit class name.
      */
     String getUnitClassName() {
@@ -225,7 +225,8 @@
     }
 
     /**
-     * Get the method count, including init and clinit methods
+     * Get the method count, including init and clinit methods.
+     *
      * @return method count
      */
     public int getMethodCount() {
@@ -233,7 +234,8 @@
     }
 
     /**
-     * Get the clinit count
+     * Get the clinit count.
+     *
      * @return clinit count
      */
     public int getClinitCount() {
@@ -241,7 +243,8 @@
     }
 
     /**
-     * Get the init count
+     * Get the init count.
+     *
      * @return init count
      */
     public int getInitCount() {
@@ -249,7 +252,8 @@
     }
 
     /**
-     * Get the field count
+     * Get the field count.
+     *
      * @return field count
      */
     public int getFieldCount() {
@@ -260,6 +264,7 @@
      * Convert a binary name to a package/class name.
      *
      * @param name Binary name.
+     *
      * @return Package/class name.
      */
     private static String pathName(final String name) {
@@ -268,6 +273,7 @@
 
     /**
      * Define the static fields common in all scripts.
+     *
      * @param strictMode Should we generate this method in strict mode
      */
     private void defineCommonStatics(final boolean strictMode) {
@@ -284,8 +290,8 @@
     }
 
     /**
-     * Define static utilities common needed in scripts.  These are per compile unit
-     * and therefore have to be defined here and not in code gen.
+     * Define static utilities common needed in scripts. These are per compile
+     * unit and therefore have to be defined here and not in code gen.
      */
     private void defineCommonUtilities() {
         assert unitClassName != null;
@@ -333,7 +339,9 @@
     }
 
     /**
-     * Constructs a primitive specific method for getting the ith entry from the constants table as an array.
+     * Constructs a primitive specific method for getting the ith entry from the
+     * constants table as an array.
+     *
      * @param clazz Array class.
      */
     private void defineGetArrayMethod(final Class<?> clazz) {
@@ -356,7 +364,9 @@
 
     /**
      * Generate the name of a get array from constant pool method.
+     *
      * @param clazz Name of array class.
+     *
      * @return Method name.
      */
     static String getArrayMethodName(final Class<?> clazz) {
@@ -366,6 +376,7 @@
 
     /**
      * Ensure a get constant method is issued for the class.
+     *
      * @param clazz Class of constant.
      */
     void needGetConstantMethod(final Class<?> clazz) {
@@ -373,12 +384,12 @@
     }
 
     /**
-     * Inspect class name and decide whether we are generating a ScriptObject class
+     * Inspect class name and decide whether we are generating a ScriptObject class.
      *
      * @param scriptPrefix the script class prefix for the current script
      * @param type         the type to check
      *
-     * @return true if type is ScriptObject
+     * @return {@code true} if type is ScriptObject
      */
     private static boolean isScriptObject(final String scriptPrefix, final String type) {
         if (type.startsWith(scriptPrefix)) {
@@ -393,14 +404,14 @@
     }
 
     /**
-     * Call at beginning of class emission
+     * Call at beginning of class emission.
      */
     public void begin() {
         classStarted = true;
     }
 
     /**
-     * Call at end of class emission
+     * Call at end of class emission.
      */
     public void end() {
         assert classStarted : "class not started for " + unitClassName;
@@ -424,7 +435,9 @@
 
     /**
      * Disassemble an array of byte code.
+     *
      * @param bytecode  byte array representing bytecode
+     *
      * @return disassembly as human readable string
      */
     static String disassemble(final byte[] bytecode) {
@@ -446,7 +459,7 @@
     }
 
     /**
-     * Call back from MethodEmitter for method start
+     * Call back from MethodEmitter for method start.
      *
      * @see MethodEmitter
      *
@@ -458,7 +471,7 @@
     }
 
     /**
-     * Call back from MethodEmitter for method end
+     * Call back from MethodEmitter for method end.
      *
      * @see MethodEmitter
      *
@@ -470,7 +483,7 @@
     }
 
     /**
-     * Add a new method to the class - defaults to public method
+     * Add a new method to the class - defaults to public method.
      *
      * @param methodName name of method
      * @param rtype      return type of the method
@@ -483,7 +496,7 @@
     }
 
     /**
-     * Add a new method to the class - defaults to public method
+     * Add a new method to the class - defaults to public method.
      *
      * @param methodFlags access flags for the method
      * @param methodName  name of method
@@ -499,7 +512,7 @@
     }
 
     /**
-     * Add a new method to the class - defaults to public method
+     * Add a new method to the class - defaults to public method.
      *
      * @param methodName name of method
      * @param descriptor descriptor of method
@@ -511,7 +524,7 @@
     }
 
     /**
-     * Add a new method to the class - defaults to public method
+     * Add a new method to the class - defaults to public method.
      *
      * @param methodFlags access flags for the method
      * @param methodName  name of method
@@ -526,9 +539,10 @@
     }
 
     /**
-     * Add a new method to the class, representing a function node
+     * Add a new method to the class, representing a function node.
      *
      * @param functionNode the function node to generate a method for
+     *
      * @return method emitter to use for weaving this method
      */
     MethodEmitter method(final FunctionNode functionNode) {
@@ -546,9 +560,11 @@
     }
 
     /**
-     * Add a new method to the class, representing a rest-of version of the function node
+     * Add a new method to the class, representing a rest-of version of the
+     * function node.
      *
      * @param functionNode the function node to generate a method for
+     *
      * @return method emitter to use for weaving this method
      */
     MethodEmitter restOfMethod(final FunctionNode functionNode) {
@@ -566,7 +582,7 @@
 
 
     /**
-     * Start generating the <clinit> method in the class
+     * Start generating the <clinit> method in the class.
      *
      * @return method emitter to use for weaving <clinit>
      */
@@ -576,7 +592,7 @@
     }
 
     /**
-     * Start generating an <init>()V method in the class
+     * Start generating an <init>()V method in the class.
      *
      * @return method emitter to use for weaving <init>()V
      */
@@ -586,7 +602,7 @@
     }
 
     /**
-     * Start generating an <init>()V method in the class
+     * Start generating an <init>()V method in the class.
      *
      * @param ptypes parameter types for constructor
      * @return method emitter to use for weaving <init>()V
@@ -597,7 +613,7 @@
     }
 
     /**
-     * Start generating an <init>(...)V method in the class
+     * Start generating an <init>(...)V method in the class.
      *
      * @param flags  access flags for the constructor
      * @param ptypes parameter types for the constructor
@@ -610,7 +626,7 @@
     }
 
     /**
-     * Add a field to the class, initialized to a value
+     * Add a field to the class, initialized to a value.
      *
      * @param fieldFlags flags, e.g. should it be static or public etc
      * @param fieldName  name of field
@@ -625,7 +641,7 @@
     }
 
     /**
-     * Add a field to the class
+     * Add a field to the class.
      *
      * @param fieldFlags access flags for the field
      * @param fieldName  name of field
@@ -638,7 +654,7 @@
     }
 
     /**
-     * Add a field to the class - defaults to public
+     * Add a field to the class - defaults to public.
      *
      * @param fieldName  name of field
      * @param fieldType  type of field
@@ -651,7 +667,8 @@
      * Return a bytecode array from this ClassEmitter. The ClassEmitter must
      * have been ended (having its end function called) for this to work.
      *
-     * @return byte code array for generated class, null if class generation hasn't been ended with {@link ClassEmitter#end()}
+     * @return byte code array for generated class, {@code null} if class
+     *         generation hasn't been ended with {@link ClassEmitter#end()}.
      */
     byte[] toByteArray() {
         assert classEnded;
@@ -663,13 +680,9 @@
     }
 
     /**
-     * Abstraction for flags used in class emission
-     *
-     * We provide abstraction separating these from the underlying bytecode
-     * emitter.
-     *
-     * Flags are provided for method handles, protection levels, static/virtual
-     * fields/methods.
+     * Abstraction for flags used in class emission. We provide abstraction
+     * separating these from the underlying bytecode emitter. Flags are provided
+     * for method handles, protection levels, static/virtual fields/methods.
      */
     static enum Flag {
         /** method handle with static access */
@@ -707,10 +720,12 @@
         }
 
         /**
-         * Return the corresponding ASM flag value for an enum set of flags
+         * Return the corresponding ASM flag value for an enum set of flags.
          *
          * @param flags enum set of flags
-         * @return an integer value representing the flags intrinsic values or:ed together
+         *
+         * @return an integer value representing the flags intrinsic values
+         *         or:ed together
          */
         static int getValue(final EnumSet<Flag> flags) {
             int v = 0;
--- a/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/ir/LexicalContext.java	Mon Jun 08 14:10:39 2015 +0530
+++ b/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/ir/LexicalContext.java	Mon Jun 08 10:28:04 2015 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -31,11 +31,13 @@
 import jdk.nashorn.internal.runtime.Source;
 
 /**
- * A class that tracks the current lexical context of node visitation as a stack of {@link Block} nodes. Has special
- * methods to retrieve useful subsets of the context.
+ * A class that tracks the current lexical context of node visitation as a stack
+ * of {@link Block} nodes. Has special methods to retrieve useful subsets of the
+ * context.
  *
- * This is implemented with a primitive array and a stack pointer, because it really makes a difference
- * performance wise. None of the collection classes were optimal
+ * This is implemented with a primitive array and a stack pointer, because it
+ * really makes a difference performance-wise. None of the collection classes
+ * were optimal.
  */
 public class LexicalContext {
     private LexicalContextNode[] stack;
@@ -79,6 +81,7 @@
      * {@link Block#NEEDS_SCOPE} because it atomically also sets the
      * {@link FunctionNode#HAS_SCOPE_BLOCK} flag on the block's containing
      * function.
+     *
      * @param block the block that needs to be marked as creating a scope.
      */
     public void setBlockNeedsScope(final Block block) {
@@ -97,8 +100,10 @@
     }
 
     /**
-     * Get the flags for a lexical context node on the stack
+     * Get the flags for a lexical context node on the stack.
+     *
      * @param node node
+     *
      * @return the flags for the node
      */
     public int getFlags(final LexicalContextNode node) {
@@ -112,8 +117,10 @@
 
     /**
      * Get the function body of a function node on the lexical context
-     * stack. This will trigger an assertion if node isn't present
+     * stack. This will trigger an assertion if node isn't present.
+     *
      * @param functionNode function node
+     *
      * @return body of function node
      */
     public Block getFunctionBody(final FunctionNode functionNode) {
@@ -126,15 +133,16 @@
     }
 
     /**
-     * Return all nodes in the LexicalContext
-     * @return all nodes
+     * @return all nodes in the LexicalContext.
      */
     public Iterator<LexicalContextNode> getAllNodes() {
         return new NodeIterator<>(LexicalContextNode.class);
     }
 
     /**
-     * Returns the outermost function in this context. It is either the program, or a lazily compiled function.
+     * Returns the outermost function in this context. It is either the program,
+     * or a lazily compiled function.
+     *
      * @return the outermost function in this context.
      */
     public FunctionNode getOutermostFunction() {
@@ -142,8 +150,12 @@
     }
 
     /**
-     * Pushes a new block on top of the context, making it the innermost open block.
+     * Pushes a new block on top of the context, making it the innermost open
+     * block.
+     *
+     * @param <T> the type of the new node
      * @param node the new node
+     *
      * @return the node that was pushed
      */
     public <T extends LexicalContextNode> T push(final T node) {
@@ -168,25 +180,28 @@
 
     /**
      * Is the context empty?
-     * @return true if empty
+     *
+     * @return {@code true} if empty
      */
     public boolean isEmpty() {
         return sp == 0;
     }
 
     /**
-     * The depth of the lexical context
-     * @return depth
+     * @return the depth of the lexical context.
      */
     public int size() {
         return sp;
     }
 
     /**
-     * Pops the innermost block off the context and all nodes that has been contributed
-     * since it was put there
+     * Pops the innermost block off the context and all nodes that has been
+     * contributed since it was put there.
      *
-     * @param node the node expected to be popped, used to detect unbalanced pushes/pops
+     * @param <T> the type of the node to be popped
+     * @param node the node expected to be popped, used to detect unbalanced
+     *        pushes/pops
+     *
      * @return the node that was popped
      */
     @SuppressWarnings("unchecked")
@@ -202,11 +217,17 @@
     }
 
     /**
-     * Explicitly apply flags to the topmost element on the stack. This is only valid to use from a
-     * {@code NodeVisitor.leaveXxx()} method and only on the node being exited at the time. It is not mandatory to use,
-     * as {@link #pop(Node)} will apply the flags automatically, but this method can be used to apply them
-     * during the {@code leaveXxx()} method in case its logic depends on the value of the flags.
-     * @param node the node to apply the flags to. Must be the topmost node on the stack.
+     * Explicitly apply flags to the topmost element on the stack. This is only
+     * valid to use from a {@code NodeVisitor.leaveXxx()} method and only on the
+     * node being exited at the time. It is not mandatory to use, as
+     * {@link #pop(Node)} will apply the flags automatically, but this method
+     * can be used to apply them during the {@code leaveXxx()} method in case
+     * its logic depends on the value of the flags.
+     *
+     * @param <T> the type of the node to apply the flags to.
+     * @param node the node to apply the flags to. Must be the topmost node on
+     *        the stack.
+     *
      * @return the passed in node, or a modified node (if any flags were modified)
      */
     public <T extends LexicalContextNode & Flags<T>> T applyTopFlags(final T node) {
@@ -215,7 +236,8 @@
     }
 
     /**
-     * Return the top element in the context
+     * Return the top element in the context.
+     *
      * @return the node that was pushed last
      */
     public LexicalContextNode peek() {
@@ -223,9 +245,11 @@
     }
 
     /**
-     * Check if a node is in the lexical context
+     * Check if a node is in the lexical context.
+     *
      * @param node node to check for
-     * @return true if in the context
+     *
+     * @return {@code true} if in the context
      */
     public boolean contains(final LexicalContextNode node) {
         for (int i = 0; i < sp; i++) {
@@ -242,6 +266,7 @@
      *
      * @param oldNode old node
      * @param newNode new node
+     *
      * @return the new node
      */
     public LexicalContextNode replace(final LexicalContextNode oldNode, final LexicalContextNode newNode) {
@@ -256,7 +281,9 @@
     }
 
     /**
-     * Returns an iterator over all blocks in the context, with the top block (innermost lexical context) first.
+     * Returns an iterator over all blocks in the context, with the top block
+     * (innermost lexical context) first.
+     *
      * @return an iterator over all blocks in the context.
      */
     public Iterator<Block> getBlocks() {
@@ -264,7 +291,9 @@
     }
 
     /**
-     * Returns an iterator over all functions in the context, with the top (innermost open) function first.
+     * Returns an iterator over all functions in the context, with the top
+     * (innermost open) function first.
+     *
      * @return an iterator over all functions in the context.
      */
     public Iterator<FunctionNode> getFunctions() {
@@ -273,6 +302,7 @@
 
     /**
      * Get the parent block for the current lexical context block
+     *
      * @return parent block
      */
     public Block getParentBlock() {
@@ -283,7 +313,9 @@
 
     /**
      * Gets the label node of the current block.
-     * @return the label node of the current block, if it is labeled. Otherwise returns null.
+     *
+     * @return the label node of the current block, if it is labeled. Otherwise
+     *         returns {@code null}.
      */
     public LabelNode getCurrentBlockLabelNode() {
         assert stack[sp - 1] instanceof Block;
@@ -294,21 +326,12 @@
         return parent instanceof LabelNode ? (LabelNode)parent : null;
     }
 
-
-    /*
-    public FunctionNode getProgram() {
-        final Iterator<FunctionNode> iter = getFunctions();
-        FunctionNode last = null;
-        while (iter.hasNext()) {
-            last = iter.next();
-        }
-        assert last != null;
-        return last;
-    }*/
-
     /**
-     * Returns an iterator over all ancestors block of the given block, with its parent block first.
+     * Returns an iterator over all ancestors block of the given block, with its
+     * parent block first.
+     *
      * @param block the block whose ancestors are returned
+     *
      * @return an iterator over all ancestors block of the given block.
      */
     public Iterator<Block> getAncestorBlocks(final Block block) {
@@ -323,8 +346,11 @@
     }
 
     /**
-     * Returns an iterator over a block and all its ancestors blocks, with the block first.
+     * Returns an iterator over a block and all its ancestors blocks, with the
+     * block first.
+     *
      * @param block the block that is the starting point of the iteration.
+     *
      * @return an iterator over a block and all its ancestors.
      */
     public Iterator<Block> getBlocks(final Block block) {
@@ -352,7 +378,9 @@
 
     /**
      * Get the function for this block.
+     *
      * @param block block for which to get function
+     *
      * @return function for block
      */
     public FunctionNode getFunction(final Block block) {
@@ -373,7 +401,6 @@
     }
 
     /**
-     * Returns the innermost block in the context.
      * @return the innermost block in the context.
      */
     public Block getCurrentBlock() {
@@ -381,7 +408,6 @@
     }
 
     /**
-     * Returns the innermost function in the context.
      * @return the innermost function in the context.
      */
     public FunctionNode getCurrentFunction() {
@@ -394,9 +420,12 @@
     }
 
     /**
-     * Get the block in which a symbol is defined
+     * Get the block in which a symbol is defined.
+     *
      * @param symbol symbol
-     * @return block in which the symbol is defined, assert if no such block in context
+     *
+     * @return block in which the symbol is defined, assert if no such block in
+     *         context.
      */
     public Block getDefiningBlock(final Symbol symbol) {
         final String name = symbol.getName();
@@ -410,9 +439,12 @@
     }
 
     /**
-     * Get the function in which a symbol is defined
+     * Get the function in which a symbol is defined.
+     *
      * @param symbol symbol
-     * @return function node in which this symbol is defined, assert if no such symbol exists in context
+     *
+     * @return function node in which this symbol is defined, assert if no such
+     *         symbol exists in context.
      */
     public FunctionNode getDefiningFunction(final Symbol symbol) {
         final String name = symbol.getName();
@@ -433,7 +465,8 @@
 
     /**
      * Is the topmost lexical context element a function body?
-     * @return true if function body
+     *
+     * @return {@code true} if function body.
      */
     public boolean isFunctionBody() {
         return getParentBlock() == null;
@@ -441,16 +474,20 @@
 
     /**
      * Is the topmost lexical context element body of a SplitNode?
-     * @return true if it's the body of a split node.
+     *
+     * @return {@code true} if it's the body of a split node.
      */
     public boolean isSplitBody() {
         return sp >= 2 && stack[sp - 1] instanceof Block && stack[sp - 2] instanceof SplitNode;
     }
 
     /**
-     * Get the parent function for a function in the lexical context
+     * Get the parent function for a function in the lexical context.
+     *
      * @param functionNode function for which to get parent
-     * @return parent function of functionNode or null if none (e.g. if functionNode is the program)
+     *
+     * @return parent function of functionNode or {@code null} if none (e.g., if
+     *         functionNode is the program).
      */
     public FunctionNode getParentFunction(final FunctionNode functionNode) {
         final Iterator<FunctionNode> iter = new NodeIterator<>(FunctionNode.class);
@@ -465,12 +502,16 @@
     }
 
     /**
-     * Count the number of scopes until a given node. Note that this method is solely used to figure out the number of
-     * scopes that need to be explicitly popped in order to perform a break or continue jump within the current bytecode
-     * method. For this reason, the method returns 0 if it encounters a {@code SplitNode} between the current location
-     * and the break/continue target.
-     * @param until node to stop counting at. Must be within the current function
-     * @return number of with scopes encountered in the context
+     * Count the number of scopes until a given node. Note that this method is
+     * solely used to figure out the number of scopes that need to be explicitly
+     * popped in order to perform a break or continue jump within the current
+     * bytecode method. For this reason, the method returns 0 if it encounters a
+     * {@code SplitNode} between the current location and the break/continue
+     * target.
+     *
+     * @param until node to stop counting at. Must be within the current function.
+     *
+     * @return number of with scopes encountered in the context.
      */
     public int getScopeNestingLevelTo(final LexicalContextNode until) {
         assert until != null;
@@ -500,16 +541,17 @@
     }
 
     /**
-     * Check whether the lexical context is currently inside a loop
-     * @return true if inside a loop
+     * Check whether the lexical context is currently inside a loop.
+     *
+     * @return {@code true} if inside a loop
      */
     public boolean inLoop() {
         return getCurrentLoop() != null;
     }
 
     /**
-     * Returns the loop header of the current loop, or null if not inside a loop
-     * @return loop header
+     * @return the loop header of the current loop, or {@code null} if not
+     *         inside a loop.
      */
     public LoopNode getCurrentLoop() {
         final Iterator<LoopNode> iter = new NodeIterator<>(LoopNode.class, getCurrentFunction());
@@ -518,9 +560,12 @@
 
     /**
      * Find the breakable node corresponding to this label.
-     * @param labelName name of the label to search for. If null, the closest breakable node will be returned
-     * unconditionally, e.g. a while loop with no label
-     * @return closest breakable node
+     *
+     * @param labelName name of the label to search for. If {@code null}, the
+     *        closest breakable node will be returned unconditionally, e.g., a
+     *        while loop with no label.
+     *
+     * @return closest breakable node.
      */
     public BreakableNode getBreakable(final String labelName) {
         if (labelName != null) {
@@ -544,9 +589,12 @@
 
     /**
      * Find the continue target node corresponding to this label.
-     * @param labelName label name to search for. If null the closest loop node will be returned unconditionally, e.g. a
-     * while loop with no label
-     * @return closest continue target node
+     *
+     * @param labelName label name to search for. If {@code null} the closest
+     *        loop node will be returned unconditionally, e.g., a while loop
+     *        with no label.
+     *
+     * @return closest continue target node.
      */
     public LoopNode getContinueTo(final String labelName) {
         if (labelName != null) {
@@ -566,8 +614,10 @@
 
     /**
      * Find the inlined finally block node corresponding to this label.
-     * @param labelName label name to search for. Must not be null.
-     * @return closest inlined finally block with the given label
+     *
+     * @param labelName label name to search for. Must not be {@code null}.
+     *
+     * @return closest inlined finally block with the given label.
      */
     public Block getInlinedFinally(final String labelName) {
         for (final NodeIterator<TryNode> iter = new NodeIterator<>(TryNode.class); iter.hasNext(); ) {
@@ -581,7 +631,9 @@
 
     /**
      * Find the try node for an inlined finally block corresponding to this label.
-     * @param labelName label name to search for. Must not be null.
+     *
+     * @param labelName label name to search for. Must not be {@code null}.
+     *
      * @return the try node to which the labelled inlined finally block belongs.
      */
     public TryNode getTryNodeForInlinedFinally(final String labelName) {
@@ -595,9 +647,11 @@
     }
 
     /**
-     * Check the lexical context for a given label node by name
-     * @param name name of the label
-     * @return LabelNode if found, null otherwise
+     * Check the lexical context for a given label node by name.
+     *
+     * @param name name of the label.
+     *
+     * @return LabelNode if found, {@code null} otherwise.
      */
     private LabelNode findLabel(final String name) {
         for (final Iterator<LabelNode> iter = new NodeIterator<>(LabelNode.class, getCurrentFunction()); iter.hasNext(); ) {
@@ -610,10 +664,13 @@
     }
 
     /**
-     * Checks whether a given target is a jump destination that lies outside a given split node
-     * @param splitNode the split node
-     * @param target the target node
-     * @return true if target resides outside the split node
+     * Checks whether a given target is a jump destination that lies outside a
+     * given split node.
+     *
+     * @param splitNode the split node.
+     * @param target the target node.
+     *
+     * @return {@code true} if target resides outside the split node.
      */
     public boolean isExternalTarget(final SplitNode splitNode, final BreakableNode target) {
         for (int i = sp; i-- > 0;) {
@@ -634,8 +691,10 @@
     }
 
     /**
-     * Checks whether the current context is inside a switch statement without explicit blocks (curly braces).
-     * @return true if in unprotected switch statement
+     * Checks whether the current context is inside a switch statement without
+     * explicit blocks (curly braces).
+     *
+     * @return {@code true} if in unprotected switch statement.
      */
     public boolean inUnprotectedSwitchContext() {
         for (int i = sp; i > 0; i--) {
--- a/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/annotations/Constructor.java	Mon Jun 08 14:10:39 2015 +0530
+++ b/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/annotations/Constructor.java	Mon Jun 08 10:28:04 2015 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -37,13 +37,15 @@
 @Target(ElementType.METHOD)
 public @interface Constructor {
     /**
-     * Name of the constructor function. If empty, the name is inferred.
+     * @return the name of the constructor function. If empty, the name is
+     *         inferred.
      */
     public String name() default "";
 
     /**
-     * The arity of the function. By default computed from the method signature.
-     * Note that -1 means varargs. So, -2 is used as invalid arity.
+     * @return the arity of the function. By default computed from the method
+     *         signature. Note that -1 means varargs. So, -2 is used as invalid
+     *         arity.
      */
     public int arity() default -2;
 }
--- a/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/annotations/Function.java	Mon Jun 08 14:10:39 2015 +0530
+++ b/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/annotations/Function.java	Mon Jun 08 10:28:04 2015 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -41,22 +41,23 @@
 @Target(ElementType.METHOD)
 public @interface Function {
     /**
-     * Name of the property. If empty, the name is inferred.
+     * @return the name of the property. If empty, the name is inferred.
      */
     public String name() default "";
 
     /**
-     * Attribute flags for this function.
+     * @return the attribute flags for this function.
      */
     public int attributes() default DEFAULT_ATTRIBUTES;
 
     /**
-     * The arity of the function. By default computed from the method signature
+     * @return the arity of the function. By default computed from the method
+     *         signature.
      */
     public int arity() default -2;
 
     /**
-     * where this function lives
+     * @return where this function lives.
      */
     public Where where() default Where.PROTOTYPE;
 }
--- a/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/annotations/Getter.java	Mon Jun 08 14:10:39 2015 +0530
+++ b/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/annotations/Getter.java	Mon Jun 08 10:28:04 2015 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -39,17 +39,17 @@
 @Target(ElementType.METHOD)
 public @interface Getter {
     /**
-     * Name of the property. If empty, the name is inferred.
+     * @return the name of the property. If empty, the name is inferred.
      */
     public String name() default "";
 
     /**
-     * Attribute flags for this setter.
+     * @return the attribute flags for this setter.
      */
     public int attributes() default DEFAULT_ATTRIBUTES;
 
     /**
-     * Where this getter lives?
+     * @return where this getter lives.
      */
     public Where where() default Where.INSTANCE;
 }
--- a/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/annotations/ScriptClass.java	Mon Jun 08 14:10:39 2015 +0530
+++ b/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/annotations/ScriptClass.java	Mon Jun 08 10:28:04 2015 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -37,8 +37,8 @@
 @Target(ElementType.TYPE)
 public @interface ScriptClass {
     /**
-     * Name of the script class. By default, the name is derived from
-     * the Java class name.
+     * @return the name of the script class. By default, the name is derived
+     *         from the Java class name.
      */
     public String value() default "";
 }
--- a/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/annotations/Setter.java	Mon Jun 08 14:10:39 2015 +0530
+++ b/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/annotations/Setter.java	Mon Jun 08 10:28:04 2015 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -39,17 +39,17 @@
 @Target(ElementType.METHOD)
 public @interface Setter {
     /**
-     * Name of the script property. If empty, the name is inferred.
+     * @return the name of the script property. If empty, the name is inferred.
      */
     public String name() default "";
 
     /**
-     * Attribute flags for this setter.
+     * @return the attribute flags for this setter.
      */
     public int attributes() default DEFAULT_ATTRIBUTES;
 
     /**
-     * Where this setter lives?
+     * @return where this setter lives.
      */
     public Where where() default Where.INSTANCE;
 }
--- a/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/annotations/SpecializedFunction.java	Mon Jun 08 14:10:39 2015 +0530
+++ b/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/annotations/SpecializedFunction.java	Mon Jun 08 10:28:04 2015 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -33,10 +33,11 @@
 import jdk.internal.dynalink.CallSiteDescriptor;
 import jdk.internal.dynalink.linker.LinkRequest;
 import jdk.nashorn.internal.runtime.ScriptFunction;
+import jdk.nashorn.internal.runtime.UnwarrantedOptimismException;
 
 /**
  * The SpecializedFunction annotation is used to flag more type specific
- * functions than the standard one in the native objects
+ * functions than the standard one in the native objects.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
@@ -45,23 +46,23 @@
     /**
      * Functionality for testing if we are allowed to link a specialized
      * function the first time we encounter it. Then the guard will handle the
-     * rest of the invocations
+     * rest of the invocations.
      *
-     * This is the same for all callsites in Nashorn, the first time callsite is
+     * This is the same for all callsites in Nashorn; the first time a callsite is
      * linked, we have to manually check that the linkage is OK. Even if we add
      * a guard and it fails upon the first try, this is not good enough.
-     * (Symmetrical to how it works everywhere else in the Nashorn runtime).
+     * (Symmetrical to how it works everywhere else in the Nashorn runtime.)
      *
      * Here we abstract out a few of the most common link guard checks.
      */
     public static abstract class LinkLogic {
         /**
-         * Empty link logic instance - this is the default
+         * Empty link logic instance - this is the default.
          * "no special linking or runtime guard behavior"
          */
         public static final LinkLogic EMPTY_INSTANCE = new Empty();
 
-        /** Empty link logic class - allow all linking, no guards */
+        /** Empty link logic class - allow all linking, no guards. */
         private static final class Empty extends LinkLogic {
             @Override
             public boolean canLink(final Object self, final CallSiteDescriptor desc, final LinkRequest request) {
@@ -75,7 +76,8 @@
         }
 
         /**
-         * Get the class representing the empty link logic
+         * Get the class representing the empty link logic.
+         *
          * @return class representing empty link logic
          */
         public static Class<? extends LinkLogic> getEmptyLinkLogicClass() {
@@ -83,31 +85,31 @@
         }
 
         /**
-         * Should this callsite relink when an exception is thrown
+         * Should this callsite relink when an exception is thrown?
          *
-         * @return the relink exception, or null if none
+         * @return the relink exception, or {@code null} if none
          */
         public Class<? extends Throwable> getRelinkException() {
             return null;
         }
 
         /**
-         * Is this link logic class empty - i.e. no special linking logic
-         * supplied
+         * Is this link logic class empty - i.e., no special linking logic
+         * supplied?
          *
          * @param clazz class to check
          *
-         * @return true if this link logic is empty
+         * @return {@code true} if this link logic is empty
          */
         public static boolean isEmpty(final Class<? extends LinkLogic> clazz) {
             return clazz == Empty.class;
         }
 
         /**
-         * Is this link logic instance empty - i.e. no special linking logic
-         * supplied
+         * Is this link logic instance empty - i.e., no special linking logic
+         * supplied?
          *
-         * @return true if this link logic instance is empty
+         * @return {@code true} if this link logic instance is empty
          */
         public boolean isEmpty() {
             return false;
@@ -121,7 +123,7 @@
          * @param desc    callsite descriptor
          * @param request link request
          *
-         * @return true if we can link this callsite at this time
+         * @return {@code true} if we can link this callsite at this time
          */
         public abstract boolean canLink(final Object self, final CallSiteDescriptor desc, final LinkRequest request);
 
@@ -131,7 +133,7 @@
          *
          * @param self receiver
          *
-         * @return true if a guard is to be woven into the callsite
+         * @return {@code true} if a guard is to be woven into the callsite
          */
         public boolean needsGuard(final Object self) {
             return true;
@@ -139,13 +141,13 @@
 
         /**
          * Given a callsite, and optional arguments, do we need an extra guard
-         * for specialization to go through - this guard can be a function of
-         * the arguments too
+         * for specialization to go through? This guard can be a function of
+         * the arguments too.
          *
          * @param self receiver
          * @param args arguments
          *
-         * @return true if a guard is to be woven into the callsite
+         * @return {@code true} if a guard is to be woven into the callsite
          */
         public boolean needsGuard(final Object self, final Object... args) {
             return true;
@@ -169,9 +171,9 @@
          * @param self receiver
          * @param desc callsite descriptor
          * @param request link request
-
-         * @return true if we can link, false otherwise - that means we have to
-         *         pick a non specialized target
+         *
+         * @return {@code true} if we can link, {@code false} otherwise - that
+         *         means we have to pick a non specialized target
          */
         public boolean checkLinkable(final Object self, final CallSiteDescriptor desc, final LinkRequest request) {
             // check the link guard, if it says we can link, go ahead
@@ -180,11 +182,11 @@
     }
 
     /**
-     * name override for return value polymorphism, for example we can't have
+     * Name override for return value polymorphism, for example we can't have
      * pop(V)I and pop(V)D in the same Java class, so they need to be named,
-     * e.g. popInt(V)I and popDouble(V)D for disambiguation, however, their
+     * e.g., popInt(V)I and popDouble(V)D for disambiguation, however, their
      * names still need to resolve to "pop" to JavaScript so we can still
-     * specialize on return values and so that the linker can find them
+     * specialize on return values and so that the linker can find them.
      *
      * @return name, "" means no override, use the Java function name, e.g.
      *         "push"
@@ -199,16 +201,18 @@
     Class<?> linkLogic() default LinkLogic.Empty.class;
 
     /**
-     * Is this a specialized constructor?
+     * @return whether this is a specialized constructor.
      */
     boolean isConstructor() default false;
 
     /**
-     * Can this function throw UnwarrantedOptimismExceptions? This works just
-     * like the normal functions, but we need the function to be
+     * Can this function throw {@link UnwarrantedOptimismException}s? This works
+     * just like the normal functions, but we need the function to be
      * immutable/non-state modifying, as we can't generate continuations for
      * native code. Luckily a lot of the methods we want to specialize have this
-     * property
+     * property.
+     *
+     * @return whether this function can throw {@link UnwarrantedOptimismException}.
      */
     boolean isOptimistic() default false;
 }
--- a/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/parser/JSONParser.java	Mon Jun 08 14:10:39 2015 +0530
+++ b/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/parser/JSONParser.java	Mon Jun 08 10:28:04 2015 +0200
@@ -47,7 +47,8 @@
 import static jdk.nashorn.internal.parser.TokenType.STRING;
 
 /**
- * Parses JSON text and returns the corresponding IR node. This is derived from the objectLiteral production of the main parser.
+ * Parses JSON text and returns the corresponding IR node. This is derived from
+ * the objectLiteral production of the main parser.
  *
  * See: 15.12.1.2 The JSON Syntactic Grammar
  */
@@ -70,9 +71,11 @@
     private static final int STATE_COMMA_PARSED   = 2;
 
     /**
-     * Constructor
-     * @param source  the source
-     * @param global the global object
+     * Constructor.
+     *
+     * @param source     the source
+     * @param global     the global object
+     * @param dualFields whether the parser should regard dual field representation
      */
     public JSONParser(final String source, final Global global, final boolean dualFields) {
         this.source = source;
@@ -82,8 +85,9 @@
     }
 
     /**
-     * Implementation of the Quote(value) operation as defined in the ECMA script spec
-     * It wraps a String value in double quotes and escapes characters within in
+     * Implementation of the Quote(value) operation as defined in the ECMAscript
+     * spec. It wraps a String value in double quotes and escapes characters
+     * within.
      *
      * @param value string to quote
      *
--- a/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/parser/TokenType.java	Mon Jun 08 14:10:39 2015 +0530
+++ b/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/parser/TokenType.java	Mon Jun 08 10:28:04 2015 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -222,9 +222,11 @@
 
     /**
      * Determines if the token has greater precedence than other.
+     *
      * @param other  Compare token.
      * @param isLeft Is to the left of the other.
-     * @return True if greater precedence.
+     *
+     * @return {@code true} if greater precedence.
      */
     public boolean needsParens(final TokenType other, final boolean isLeft) {
         return other.precedence != 0 &&
@@ -234,16 +236,16 @@
 
     /**
      * Determines if the type is a valid operator.
-     * @param noIn TRUE if IN operator should be ignored.
-     * @return TRUE if valid operator.
+     *
+     * @param noIn {@code true} if IN operator should be ignored.
+     *
+     * @return {@code true} if valid operator.
      */
     public boolean isOperator(final boolean noIn) {
         return kind == BINARY && (!noIn || this != IN) && precedence != 0;
     }
 
-    /**
-     * Accessors.
-     */
+
     public int getLength() {
         assert name != null : "Token name not set";
         return name.length();
--- a/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/runtime/linker/JavaAdapterFactory.java	Mon Jun 08 14:10:39 2015 +0530
+++ b/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/runtime/linker/JavaAdapterFactory.java	Mon Jun 08 10:28:04 2015 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -54,23 +54,28 @@
 import jdk.nashorn.internal.runtime.ScriptObject;
 
 /**
- * <p>A factory class that generates adapter classes. Adapter classes allow implementation of Java interfaces and
- * extending of Java classes from JavaScript. For every combination of a superclass to extend and interfaces to
- * implement (collectively: "original types"), exactly one adapter class is generated that extends the specified
- * superclass and implements the specified interfaces. (But see the discussion of class-based overrides for exceptions.)
- * </p><p>
- * The adapter class is generated in a new secure class loader that inherits Nashorn's protection domain, and has either
- * one of the original types' class loader or the Nashorn's class loader as its parent - the parent class loader
- * is chosen so that all the original types and the Nashorn core classes are visible from it (as the adapter will have
- * constant pool references to ScriptObject and ScriptFunction classes). In case none of the candidate class loaders has
- * visibility of all the required types, an error is thrown. The class uses {@link JavaAdapterBytecodeGenerator} to
- * generate the adapter class itself; see its documentation for details about the generated class.
- * </p><p>
- * You normally don't use this class directly, but rather either create adapters from script using
- * {@link jdk.nashorn.internal.objects.NativeJava#extend(Object, Object...)}, using the {@code new} operator on abstract classes and interfaces (see
- * {@link jdk.nashorn.internal.objects.NativeJava#type(Object, Object)}), or implicitly when passing script functions to Java methods expecting SAM
- * types.
- * </p>
+ * A factory class that generates adapter classes. Adapter classes allow
+ * implementation of Java interfaces and extending of Java classes from
+ * JavaScript. For every combination of a superclass to extend and interfaces to
+ * implement (collectively: "original types"), exactly one adapter class is
+ * generated that extends the specified superclass and implements the specified
+ * interfaces. (But see the discussion of class-based overrides for exceptions.)
+ * <p>
+ * The adapter class is generated in a new secure class loader that inherits
+ * Nashorn's protection domain, and has either one of the original types' class
+ * loader or the Nashorn's class loader as its parent - the parent class loader
+ * is chosen so that all the original types and the Nashorn core classes are
+ * visible from it (as the adapter will have constant pool references to
+ * ScriptObject and ScriptFunction classes). In case none of the candidate class
+ * loaders has visibility of all the required types, an error is thrown. The
+ * class uses {@link JavaAdapterBytecodeGenerator} to generate the adapter class
+ * itself; see its documentation for details about the generated class.
+ * <p>
+ * You normally don't use this class directly, but rather either create adapters
+ * from script using {@link jdk.nashorn.internal.objects.NativeJava#extend(Object, Object...)},
+ * using the {@code new} operator on abstract classes and interfaces (see
+ * {@link jdk.nashorn.internal.objects.NativeJava#type(Object, Object)}), or
+ * implicitly when passing script functions to Java methods expecting SAM types.
  */
 
 @SuppressWarnings("javadoc")
@@ -93,25 +98,39 @@
     };
 
     /**
-     * Returns an adapter class for the specified original types. The adapter class extends/implements the original
-     * class/interfaces.
-     * @param types the original types. The caller must pass at least one Java type representing either a public
-     * interface or a non-final public class with at least one public or protected constructor. If more than one type is
-     * specified, at most one can be a class and the rest have to be interfaces. The class can be in any position in the
-     * array. Invoking the method twice with exactly the same types in the same order will return the same adapter
-     * class, any reordering of types or even addition or removal of redundant types (i.e. interfaces that other types
-     * in the list already implement/extend, or {@code java.lang.Object} in a list of types consisting purely of
-     * interfaces) will result in a different adapter class, even though those adapter classes are functionally
-     * identical; we deliberately don't want to incur the additional processing cost of canonicalizing type lists.
-     * @param classOverrides a JavaScript object with functions serving as the class-level overrides and
-     * implementations. These overrides are defined for all instances of the class, and can be further overridden on a
-     * per-instance basis by passing additional objects in the constructor.
-     * @param lookup the lookup object identifying the caller class. The generated adapter class will have the
-     * protection domain of the caller class iff the lookup object is full-strength, otherwise it will be completely
-     * unprivileged.
-     * @return an adapter class. See this class' documentation for details on the generated adapter class.
-     * @throws ECMAException with a TypeError if the adapter class can not be generated because the original class is
-     * final, non-public, or has no public or protected constructors.
+     * Returns an adapter class for the specified original types. The adapter
+     * class extends/implements the original class/interfaces.
+     *
+     * @param types the original types. The caller must pass at least one Java
+     *        type representing either a public interface or a non-final public
+     *        class with at least one public or protected constructor. If more
+     *        than one type is specified, at most one can be a class and the
+     *        rest have to be interfaces. The class can be in any position in
+     *        the array. Invoking the method twice with exactly the same types
+     *        in the same order will return the same adapter class, any
+     *        reordering of types or even addition or removal of redundant types
+     *        (i.e., interfaces that other types in the list already
+     *        implement/extend, or {@code java.lang.Object} in a list of types
+     *        consisting purely of interfaces) will result in a different
+     *        adapter class, even though those adapter classes are functionally
+     *        identical; we deliberately don't want to incur the additional
+     *        processing cost of canonicalizing type lists.
+     * @param classOverrides a JavaScript object with functions serving as the
+     *        class-level overrides and implementations. These overrides are
+     *        defined for all instances of the class, and can be further
+     *        overridden on a per-instance basis by passing additional objects
+     *        in the constructor.
+     * @param lookup the lookup object identifying the caller class. The
+     *        generated adapter class will have the protection domain of the
+     *        caller class iff the lookup object is full-strength, otherwise it
+     *        will be completely unprivileged.
+     *
+     * @return an adapter class. See this class' documentation for details on
+     *         the generated adapter class.
+     *
+     * @throws ECMAException with a TypeError if the adapter class can not be
+     *         generated because the original class is final, non-public, or has
+     *         no public or protected constructors.
      */
     public static StaticClass getAdapterClassFor(final Class<?>[] types, final ScriptObject classOverrides, final MethodHandles.Lookup lookup) {
         return getAdapterClassFor(types, classOverrides, getProtectionDomain(lookup));
@@ -148,15 +167,23 @@
     }
 
     /**
-     * Returns a method handle representing a constructor that takes a single argument of the source type (which,
-     * really, should be one of {@link ScriptObject}, {@link ScriptFunction}, or {@link Object}, and returns an instance
-     * of the adapter for the target type. Used to implement the function autoconverters as well as the Nashorn's
-     * JSR-223 script engine's {@code getInterface()} method.
-     * @param sourceType the source type; should be either {@link ScriptObject}, {@link ScriptFunction}, or
-     * {@link Object}. In case of {@code Object}, it will return a method handle that dispatches to either the script
-     * object or function constructor at invocation based on the actual argument.
+     * Returns a method handle representing a constructor that takes a single
+     * argument of the source type (which, really, should be one of {@link ScriptObject},
+     * {@link ScriptFunction}, or {@link Object}, and returns an instance of the
+     * adapter for the target type. Used to implement the function autoconverters
+     * as well as the Nashorn JSR-223 script engine's {@code getInterface()}
+     * method.
+     *
+     * @param sourceType the source type; should be either {@link ScriptObject},
+     *        {@link ScriptFunction}, or {@link Object}. In case of {@code Object},
+     *        it will return a method handle that dispatches to either the script
+     *        object or function constructor at invocation based on the actual
+     *        argument.
      * @param targetType the target type, for which adapter instances will be created
+     * @param lookup method handle lookup to use
+     *
      * @return the constructor method handle.
+     *
      * @throws Exception if anything goes wrong
      */
     public static MethodHandle getConstructor(final Class<?> sourceType, final Class<?> targetType, final MethodHandles.Lookup lookup) throws Exception {
@@ -168,13 +195,18 @@
     }
 
     /**
-     * Returns whether an instance of the specified class/interface can be generated from a ScriptFunction. Returns true
-     * iff: the adapter for the class/interface can be created, it is abstract (this includes interfaces), it has at
-     * least one abstract method, all the abstract methods share the same name, and it has a public or protected default
-     * constructor. Note that invoking this class will most likely result in the adapter class being defined in the JVM
-     * if it hasn't been already.
+     * Returns whether an instance of the specified class/interface can be
+     * generated from a ScriptFunction. Returns {@code true} iff: the adapter
+     * for the class/interface can be created, it is abstract (this includes
+     * interfaces), it has at least one abstract method, all the abstract
+     * methods share the same name, and it has a public or protected default
+     * constructor. Note that invoking this class will most likely result in the
+     * adapter class being defined in the JVM if it hasn't been already.
+     *
      * @param clazz the inspected class
-     * @return true iff an instance of the specified class/interface can be generated from a ScriptFunction.
+     *
+     * @return {@code true} iff an instance of the specified class/interface can
+     *         be generated from a ScriptFunction.
      */
     static boolean isAutoConvertibleFromFunction(final Class<?> clazz) {
         return getAdapterInfo(new Class<?>[] { clazz }).autoConvertibleFromFunction;
@@ -198,7 +230,9 @@
 
    /**
      * For a given class, create its adapter class and associated info.
+     *
      * @param type the class for which the adapter is created
+     *
      * @return the adapter info for the class.
      */
     private static AdapterInfo createAdapterInfo(final Class<?>[] types, final ClassAndLoader definingClassAndLoader) {
@@ -311,11 +345,14 @@
         }
 
         /**
-         * Choose between the passed class loader and the class loader that defines the ScriptObject class, based on which
-         * of the two can see the classes in both.
-         * @param classAndLoader the loader and a representative class from it that will be used to add the generated
-         * adapter to its ADAPTER_INFO_MAPS.
+         * Choose between the passed class loader and the class loader that defines the
+         * ScriptObject class, based on which of the two can see the classes in both.
+         *
+         * @param classAndLoader the loader and a representative class from it that will
+         *        be used to add the generated adapter to its ADAPTER_INFO_MAPS.
+         *
          * @return the class loader that sees both the specified class and Nashorn classes.
+         *
          * @throws IllegalStateException if no such class loader is found.
          */
         private static ClassLoader findCommonLoader(final ClassAndLoader classAndLoader) throws AdaptationException {
--- a/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/runtime/regexp/joni/EncodingHelper.java	Mon Jun 08 14:10:39 2015 +0530
+++ b/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/runtime/regexp/joni/EncodingHelper.java	Mon Jun 08 10:28:04 2015 +0200
@@ -229,6 +229,11 @@
 
     /**
      * @see <a href="http://www.geocities.jp/kosako3/oniguruma/doc/RE.txt">http://www.geocities.jp/kosako3/oniguruma/doc/RE.txt</a>
+     *
+     * @param code code
+     * @param ctype ctype
+     *
+     * @return isCodeCType
      */
     public static boolean isCodeCType(final int code, final int ctype) {
         int type;
--- a/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/runtime/regexp/joni/Syntax.java	Mon Jun 08 14:10:39 2015 +0530
+++ b/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/runtime/regexp/joni/Syntax.java	Mon Jun 08 10:28:04 2015 +0200
@@ -57,10 +57,10 @@
         }
     }
 
-    /**
-     * OP
-     *
-     */
+    //
+    // OP
+    //
+
     protected boolean isOp(final int opm) {
         return (op & opm) != 0;
     }
@@ -189,11 +189,10 @@
         return isOp(OP_ESC_X_BRACE_HEX8);
     }
 
+    //
+    // OP2
+    //
 
-    /**
-     * OP
-     *
-     */
     protected boolean isOp2(final int opm) {
         return (op2 & opm) != 0;
     }
@@ -278,10 +277,10 @@
         return isOp2(OP2_INEFFECTIVE_ESCAPE);
     }
 
-    /**
-     * BEHAVIOR
-     *
-     */
+    //
+    // BEHAVIOR
+    //
+
     protected boolean isBehavior(final int bvm) {
         return (behavior & bvm) != 0;
     }