package Torello.JavaDoc;

import java.lang.annotation.*;

// @CSSLinks Annotation
// 
// EXPORTS:
//      public String[] FileNames();
// 
// * Torello.JavaDoc.CSSLinks
//      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_CSS_FILES
//      The classes in this package do the processing for inserting the '.css' Files which the user
//      has requested be placed into his Java-Doc '.html' Web-Page.  These '.css' Files must be
//      located in the '../upgrade-files/stylesheets/' 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.CSSLinksProcessor
//      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.CSSLMirror
//      After the JDU Detects that a CIET / Type has had the @CSSLinks 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. 

/**
 * This Annotation allows a user to request that a CSS Link-Import be included in the Header
 * Portion of any CIET/Type's respective Java-Doc Web-Page.  This Annotation allows for multiple
 * sheets to be applied to a single Java-Doc Page.
 * 
 * <BR /><BR />The {@link #FileNames()} element in this annotation should be supplied with 
 * names for a file located inside the {@code ../upgrade-files/stylesheets/} sub-directory of
 * whatever Java Source-Code Package in which your CIET/Type (your {@code '.java'} file) resides.
 * When you specify a CSS-File in that directory, you need not include any actual directory string
 * information in the file-name.  Just the Simple-Name of the file itself is expected / sufficient.
 * 
 * <BR /><BR />Importing CSS-Files from other locations on disk is also allowed.  In such cases
 * you would then (and only then) be obligated to include the Full-Path / Canonical File-Name
 * for the CSS-File to be imported.
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
@JDHeaderBackgroundImg()

public @interface CSSLinks
{
    /**
     * The CSS-StyleSheet file (or files) for which an HTML {@code <LINK REL=stylesheet>} Tag is to
     * be inserted into this CIET/Type's Java-Doc Page Header.
     * 
     * <BR /><BR />This Annotation-Element is a {@code String}-Array, which means more than one
     * Style-Sheet may be included here.  If the Style-Sheet has been properly placed, directly,
     * into the {@code ../upgrade-files/stylesheets/} directory, then this {@code 'FileNames'}
     * {@code String}-Array <I>should not include any parent or container directory information in
     * the any of those kinds of FileName-{@code String's}</I>.
     * 
     * <BR /><BR />If a StyleSheet whose location on disk is situated on the File-System in some
     * unrelated place, then the file's Full-Path Name (or at least it's Relative-Path Name with
     * respect to the Current Working Directory at Build Initiation Time) should be the 
     * {@code String} used within this Array-Element.
     */
    public String[] FileNames();    
}