package Torello.JavaDoc;

import java.lang.annotation.*;

// @CSSLinks Annotation
// 
// EXPORTS:
//      public String[] FileNames();
//      public String[] FullPathFileNames();
// 
// * Torello.JavaDoc.JavaScriptImport
//      This is the actual User-Annotation that is part of the Upgrader-API.  A user may place the
//      @CSSLinks Annotation on a Type / CIET (Class, Interface, Enum, Annotation or
//      Rec) - And a CSS-File Link in the form of a <LINK REL=stylesheet TYPE=text/css HREF=...>
//      will be inserted for Class / Type / CIET that the user has annotated. 
// 
// * package Torello.JDUInternal.Features.USER_SUPPLIED_JAVASCRIPT
//      The classes in this package do the processing for inserting the '.js' Files which the user
//      has requested be placed into his Java-Doc '.html' Web-Page.  These '.js' Files must be
//      located in the '../upgrade-files/script/' directory.  These '.css' Files must either:
// 
//          1) obey the standard naming convention and have the exact same file-name as the
//          Java-Class which has been annotated by the @CSSLinks Annotation
// 
//          2) have a name equal to one of the names provided to the Annotation-Element "FileNames"
// 
// * Torello.JDUInternal.Annotations.TypeAnnotations.Processor.JSImportProcessor
//      This is the Annotation-Processsor that is / can-be invoked by the 'javac' (Java-Compiler) at
//      Compile-Time.  This Annotation-Processor does not do very much, but will check that the
//      names provided to the "FileNames" Annotation-Element are, indeed, valid Operating-System
//      File-Names - which exist and are accessible.
// 
// * Torello.JDUInternal.Annotations.TypeAnnotations.Mirror.JSImportMirror
//      After the JDU Detects that a CIET / Type has had the @JavaScriptImport Annotation placed upon
//      it, this class extracts the relevant information out of the Annotation using the AST
//      Library in 'com.sun.source.tree' and all of it's helper classes. 

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
public @interface JavaScriptImport
{
    /**
     * The File Names which should be passed via this {@code String[]}-Array must be relative to
     * precisely one of your package's {@code '[src-dir]/upgrade-files/script/'} directories.  Keep
     * in mind that although Java's "Class Path" allows Source-Files for any given package to be 
     * distributed to multiple locations, {@code '.js'}-Files can only match precisely one 
     * {@code ../upgrade-files/script/*.js'} File on disk, or the the Annotation Processing system
     * wil flag this annotation as an error.
     */
    public String[] FileNames() default {};

    /**
     * The File Names which are passed using this Element may refer to any {@code '.js'} File any 
     * where on the File-System.  These Java-Script Files do not have to reside within the 
     * {@code ../upgrade-files/script/} directory.
     */
    public String[] FullPathFileNames() default {};
}