Using @j2s tags in JavaDoc

Java2Script compiler supports some "directives" that the user can include in its java code inside javadoc comments, that affects how a java element, like a method, a class or simple code block is translated to javascript. So the javadoc always must go before some java block of code. Also, usually this directives accepts some input that must be after the @j2s directive in the same javadoc. In the following java segment, we use the directive @j2sNative to tell the J2S compiler that a java code block must be replaced by some native javascript code that we give:

System.out.println("Code before");
/**
 * @j2sNative
 *
 * alert("a javascript native statement");
 */
{
    System.out.println("these statements will be replaced");
} 
System.out.println("Code after");

that will be translated to

System.out.println("Code before");
{
alert("a javascript native statement");
}
System.out.println("Code after");

The important thing to notice here is how the java statement inside the block ("these statements will be replaced") is not present in the translated code, and it was replaced by the javascript statement alert("a javascript native statement"); that we wrote inside the javadoc comment, after the @j2sNative directive.

All these @j2s annotations that we will describe later in more detail, are used the same way. First of all, they must be inside a JavaDoc comment. JavaDoc comments are special comments that begin with /** instead of /*. This JavaDoc comment have to go before a java code entity, like a method definition, a class definition or a code block. Second, the javadoc must contain a special J2S annotation like in the previous example, @j2sNative . We call this @j2s annotations J2S compiler directives, since they let us customize in some ways the compiler output code. Also, in most cases, the J2S compiler directive accepts some text input, like in the last example the javascript native code, and act over some java element, like in the last example, the java code block.