package Torello.JavaDoc.Annotations;

import java.lang.annotation.*;

// @CSSLinks Annotation
// 
// EXPORTS:
//      public String[] FileNames();
//
// * 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"


/**
 * 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)

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();    
}