package Torello.JavaDoc;

import java.lang.annotation.*;


// @JDHeaderBackgroundImg Annotation
// 
// EXPORTS:
//      String[] CSSClass() default { };
//      String[] EmbedTagFileID() default { };
// 
// * Torello.JavaDoc.JDHeaderBackgroundImg
//      This is the actual User-Annotation that is part of the API.  A user may place the
//      @JDHeaderBackgroundImg Annotation on a Type / CIET (Class, Interface, Enum, Annotation or
//      Rec - And a Wood-Plank Background with the provided HTML will be placed onto the Java-Doc
//      for the Class / Type / CIET that the user has annotated. 
// 
// * package Torello.JDUInternal.Features.EXTERNAL_HTML_FILES
//      The classes in this package do the processing for inserting the HTML from External-HTML
//      Files into Java-Doc '.html' Output-Files.  It places an HTML <IMG SRC=...> at the top of
//      the page.  The Imge contains a Wooden-Panel, and the User's JDHBI HTML for that class is 
//      then placed on top of / over the Wood-Paneling
// 
// * Torello.JDUInternal.Annotations.TypeAnnotations.Processor.JDHBImgProcessor
//      This is Annotation-Processsor that is / can-be invoked by the 'javac' (Java-Compiler) at
//      Compile-Time.  This Annotation-Processor largely does nothing other than to guarantee that
//      any String-Tokens which have been provided are, indeed, valid tokens which obey the syntax
//      rules.
// 
// * Torello.JDUInternal.Annotations.TypeAnnotations.Mirror.JDHBIMirror
//      After the JDU Detects that a CIET / Type has had the @JDHBIMirror 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. 

/**
 * <B STYLE='color:darkred;'>Java-Annotation:</B>
 * 
 * A Java-Annotation for inserting a Wooden-Plank Background Image at the top of a Java-Doc
 * Page using External-HTML File's; the image used is configurable, and my be changed by
 * assigning the Annotation-Element Values appropriately.
 */

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)

// NOTE: THIS ACTUALLY IS A "SELF-ANNOTATING" ANNOTATION...
@JDHeaderBackgroundImg

public @interface JDHeaderBackgroundImg
{
    /**
     * This Annotation-Element is optional.  It is intended to contain the CSS-Class the user
     * would like associated with the Java-Doc Header-Background Image Divider
     * (the {@code '<DIV>'} element).  
     * 
     * <BR /><BR />This Optional-Element has a default-value, and that is to use a CSS-Class which
     * contains an image of a "Dark Wooden Board" for a background-image.  This image will serve as
     * the background for an HTML divider {@code '<DIV>'} element that is placed at the top of the
     * Java-Doc HTML Page for the type/class being annotated.
     * 
     * <BR /><BR />Note that the {@code default} value for this element is, indeed, an Empty
     * {@code String[]}-Array.  The JavaDoc Upgrader will interpret this as a request to use the
     * default {@code CSS CLASS}, which is {@code "JDWoodBoardDark"}.  Click
     * {@link #DEFAULT_CSS_CLASS} to view (or retrieve} this {@code String}
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>IMPORTANT:</B>
     * 
     * <BR >It is advisable not to change the default value for this {@code CSS CLASS}.  Though
     * there shouldn't be any problems in using an alternate image, <I>it will require (and, 
     * hopefully this is obvious) ... it will require writing your own definition for that
     * {@code CSS-Class} and inserting it into your {@code JavaDoc.css} style-definitions page.</I>
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Multiple {@code CSS-Classes}</B>
     * 
     * <BR />This Annotation-Element is, indeed, a {@code String[]}-Array, rather than just a
     * simple-{@code String}.  You may choose to provide mltiple {@code CSS-Classes} to this 
     * Annotation, and if you do - <I>the HTML-{@code <DIV>} will have a {@code 'CLASS'}
     * attribute with multiple {@code CSS CLASS's} assigned.</I>
     * 
     * <BR /><BR />This example shows assigning the default-background to a Java {@code class}.
     * Since there is no {@code EmbedTagFileID} assigned to that element, the default Dark
     * Wooden Plank will be used as a background.  The Ugrader will look for the external-HTML
     * in the default-directory location, which is listed first (followed by the example)
     * 
     * <BR/><SPAN CLASS=JDFileDirName>
     * "SrcPackageDirectory/upgrade-files/external-html/JDHBI/MyClass.html"
     * </SPAN>
     * 
     * <!--
     * <DIV CLASS=EXAMPLE><EXTERNALCODESNIPPET> 
     * @ JDHeaderBackgroundImg
     * public class MyClass
     * { ... }
     * </EXTERNALCODESNIPPET></DIV>
     * -->
     * 
     * <BR /><BR />This example shows how to assign an alternate CSS-Class to the HTML
     * {@code <DIV>} element that is inserted.  In this example, two user-provided CSS classes
     * are going to be applied to the {@code <DIV>}.  Again, as in the previous example, the
     * Ugrader will look for the External-HTML file in the default location:
     * 
     * <!--
     * <BR /><DIV CLASS=SNIP>{@code
     * JDHeaderBackgroundImg(CSSClass={"MyOwnBeachesBackground", "ImportantCSSClass"})
     * }</DIV>
     * -->
     */
    String[] CSSClass() default { };

    /**
     * This Annotation-Element is also optional.  If used, it must contain a valid {@code FILE-ID}
     * that is listed in either the {@code Package-Local}, or the {@code Global} Embed-Tags Map.
     * This {@code FILE-ID} maps to the external HTML File that contains the HTML which is to be
     * inserted on top of the Header-Banner containing the background image.
     * 
     * <BR /><BR />If the Empty-String ({@code ""}) is passed to this Annotation-Element, or if the
     * default value (which is the Empty-String) is passed, then the JavaDoc Upgrader will look for
     * the HTML inside the {@code 'upgrade-files/'} directory:
     * 
     * <BR /><BR /><SPAN CLASS=JDFileDirName>
     * "PackageSrcDirectory/upgrade-files/external-html/JDHBI/"
     * </SPAN>
     * 
     * <BR /><BR />For a file-name that matches the name of the CIET / Type (The 'ClassName'),
     * but ending with the suffix {@code '.html'}.  For instance, in the following snippet:
     * 
     * <!--
     * <DIV CLASS=EXAMPLE><EXTERNALCODESNIPPET>
     * JDHeaderBackgroundImg(EmbedTagFileID="MyHTML")
     * </EXTERNALCODESNIPPET></DIV>
     * -->
     * 
     * <BR /><BR />The Upgrader would reference the {@code external-html-ids.properties} file
     * which contained the definition.
     */
    String[] EmbedTagFileID() default { };

    /** This is the default CSS-Class used for the {@code <DIV>} that is inserted. */
    public static final String DEFAULT_CSS_CLASS = "JDWoodBoardDark";
}