8085885: address Javadoc warnings in Nashorn source code
Reviewed-by: hannesw, lagergren
--- 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;
}