Mercurial > hg > openjdk > aarch64-port > nashorn
changeset 1421:523767716eb3
8085885: address Javadoc warnings in Nashorn source code
Reviewed-by: hannesw, lagergren
line wrap: on
line diff
--- a/src/jdk/internal/dynalink/DynamicLinker.java Mon Jun 08 17:59:32 2015 +0530 +++ b/src/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/src/jdk/nashorn/internal/codegen/ClassEmitter.java Mon Jun 08 17:59:32 2015 +0530 +++ b/src/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/src/jdk/nashorn/internal/ir/LexicalContext.java Mon Jun 08 17:59:32 2015 +0530 +++ b/src/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. */ public 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/src/jdk/nashorn/internal/objects/annotations/Constructor.java Mon Jun 08 17:59:32 2015 +0530 +++ b/src/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/src/jdk/nashorn/internal/objects/annotations/Function.java Mon Jun 08 17:59:32 2015 +0530 +++ b/src/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/src/jdk/nashorn/internal/objects/annotations/Getter.java Mon Jun 08 17:59:32 2015 +0530 +++ b/src/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/src/jdk/nashorn/internal/objects/annotations/ScriptClass.java Mon Jun 08 17:59:32 2015 +0530 +++ b/src/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/src/jdk/nashorn/internal/objects/annotations/Setter.java Mon Jun 08 17:59:32 2015 +0530 +++ b/src/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/src/jdk/nashorn/internal/objects/annotations/SpecializedFunction.java Mon Jun 08 17:59:32 2015 +0530 +++ b/src/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/src/jdk/nashorn/internal/parser/JSONParser.java Mon Jun 08 17:59:32 2015 +0530 +++ b/src/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/src/jdk/nashorn/internal/parser/TokenType.java Mon Jun 08 17:59:32 2015 +0530 +++ b/src/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/src/jdk/nashorn/internal/runtime/linker/JavaAdapterFactory.java Mon Jun 08 17:59:32 2015 +0530 +++ b/src/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/src/jdk/nashorn/internal/runtime/regexp/joni/EncodingHelper.java Mon Jun 08 17:59:32 2015 +0530 +++ b/src/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/src/jdk/nashorn/internal/runtime/regexp/joni/Syntax.java Mon Jun 08 17:59:32 2015 +0530 +++ b/src/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; }