001package Torello.JavaDoc;
002
003import java.lang.annotation.*;
004
005
006// @JDHeaderBackgroundImg Annotation
007// 
008// EXPORTS:
009//      String[] CSSClass() default { };
010//      String[] EmbedTagFileID() default { };
011// 
012// * Torello.JavaDoc.JDHeaderBackgroundImg
013//      This is the actual User-Annotation that is part of the API.  A user may place the
014//      @JDHeaderBackgroundImg Annotation on a Type / CIET (Class, Interface, Enum, Annotation or
015//      Rec - And a Wood-Plank Background with the provided HTML will be placed onto the Java-Doc
016//      for the Class / Type / CIET that the user has annotated. 
017// 
018// * package Torello.JDUInternal.Features.EXTERNAL_HTML_FILES
019//      The classes in this package do the processing for inserting the HTML from External-HTML
020//      Files into Java-Doc '.html' Output-Files.  It places an HTML <IMG SRC=...> at the top of
021//      the page.  The Imge contains a Wooden-Panel, and the User's JDHBI HTML for that class is 
022//      then placed on top of / over the Wood-Paneling
023// 
024// * Torello.JDUInternal.Annotations.TypeAnnotations.Processor.JDHBImgProcessor
025//      This is Annotation-Processsor that is / can-be invoked by the 'javac' (Java-Compiler) at
026//      Compile-Time.  This Annotation-Processor largely does nothing other than to guarantee that
027//      any String-Tokens which have been provided are, indeed, valid tokens which obey the syntax
028//      rules.
029// 
030// * Torello.JDUInternal.Annotations.TypeAnnotations.Mirror.JDHBIMirror
031//      After the JDU Detects that a CIET / Type has had the @JDHBIMirror Annotation placed upon
032//      it, this class extracts the relevant information out of the Annotation using the AST
033//      Library in 'com.sun.source.tree' and all of it's helper classes. 
034
035/**
036 * <B STYLE='color:darkred;'>Java-Annotation:</B>
037 * 
038 * A Java-Annotation for inserting a Wooden-Plank Background Image at the top of a Java-Doc
039 * Page using External-HTML File's; the image used is configurable, and my be changed by
040 * assigning the Annotation-Element Values appropriately.
041 */
042
043@Target(ElementType.TYPE)
044@Retention(RetentionPolicy.SOURCE)
045
046// NOTE: THIS ACTUALLY IS A "SELF-ANNOTATING" ANNOTATION...
047@JDHeaderBackgroundImg
048
049public @interface JDHeaderBackgroundImg
050{
051    /**
052     * This Annotation-Element is optional.  It is intended to contain the CSS-Class the user
053     * would like associated with the Java-Doc Header-Background Image Divider
054     * (the {@code '<DIV>'} element).  
055     * 
056     * <BR /><BR />This Optional-Element has a default-value, and that is to use a CSS-Class which
057     * contains an image of a "Dark Wooden Board" for a background-image.  This image will serve as
058     * the background for an HTML divider {@code '<DIV>'} element that is placed at the top of the
059     * Java-Doc HTML Page for the type/class being annotated.
060     * 
061     * <BR /><BR />Note that the {@code default} value for this element is, indeed, an Empty
062     * {@code String[]}-Array.  The JavaDoc Upgrader will interpret this as a request to use the
063     * default {@code CSS CLASS}, which is {@code "JDWoodBoardDark"}.  Click
064     * {@link #DEFAULT_CSS_CLASS} to view (or retrieve} this {@code String}
065     * 
066     * <BR /><BR /><B CLASS=JDDescLabel>IMPORTANT:</B>
067     * 
068     * <BR >It is advisable not to change the default value for this {@code CSS CLASS}.  Though
069     * there shouldn't be any problems in using an alternate image, <I>it will require (and, 
070     * hopefully this is obvious) ... it will require writing your own definition for that
071     * {@code CSS-Class} and inserting it into your {@code JavaDoc.css} style-definitions page.</I>
072     * 
073     * <BR /><BR /><B CLASS=JDDescLabel>Multiple {@code CSS-Classes}</B>
074     * 
075     * <BR />This Annotation-Element is, indeed, a {@code String[]}-Array, rather than just a
076     * simple-{@code String}.  You may choose to provide mltiple {@code CSS-Classes} to this 
077     * Annotation, and if you do - <I>the HTML-{@code <DIV>} will have a {@code 'CLASS'}
078     * attribute with multiple {@code CSS CLASS's} assigned.</I>
079     * 
080     * <BR /><BR />This example shows assigning the default-background to a Java {@code class}.
081     * Since there is no {@code EmbedTagFileID} assigned to that element, the default Dark
082     * Wooden Plank will be used as a background.  The Ugrader will look for the external-HTML
083     * in the default-directory location, which is listed first (followed by the example)
084     * 
085     * <BR/><SPAN CLASS=JDFileDirName>
086     * "SrcPackageDirectory/upgrade-files/external-html/JDHBI/MyClass.html"
087     * </SPAN>
088     * 
089     * <!--
090     * <DIV CLASS=EXAMPLE><EXTERNALCODESNIPPET> 
091     * @ JDHeaderBackgroundImg
092     * public class MyClass
093     * { ... }
094     * </EXTERNALCODESNIPPET></DIV>
095     * -->
096     * 
097     * <BR /><BR />This example shows how to assign an alternate CSS-Class to the HTML
098     * {@code <DIV>} element that is inserted.  In this example, two user-provided CSS classes
099     * are going to be applied to the {@code <DIV>}.  Again, as in the previous example, the
100     * Ugrader will look for the External-HTML file in the default location:
101     * 
102     * <!--
103     * <BR /><DIV CLASS=SNIP>{@code
104     * JDHeaderBackgroundImg(CSSClass={"MyOwnBeachesBackground", "ImportantCSSClass"})
105     * }</DIV>
106     * -->
107     */
108    String[] CSSClass() default { };
109
110    /**
111     * This Annotation-Element is also optional.  If used, it must contain a valid {@code FILE-ID}
112     * that is listed in either the {@code Package-Local}, or the {@code Global} Embed-Tags Map.
113     * This {@code FILE-ID} maps to the external HTML File that contains the HTML which is to be
114     * inserted on top of the Header-Banner containing the background image.
115     * 
116     * <BR /><BR />If the Empty-String ({@code ""}) is passed to this Annotation-Element, or if the
117     * default value (which is the Empty-String) is passed, then the JavaDoc Upgrader will look for
118     * the HTML inside the {@code 'upgrade-files/'} directory:
119     * 
120     * <BR /><BR /><SPAN CLASS=JDFileDirName>
121     * "PackageSrcDirectory/upgrade-files/external-html/JDHBI/"
122     * </SPAN>
123     * 
124     * <BR /><BR />For a file-name that matches the name of the CIET / Type (The 'ClassName'),
125     * but ending with the suffix {@code '.html'}.  For instance, in the following snippet:
126     * 
127     * <!--
128     * <DIV CLASS=EXAMPLE><EXTERNALCODESNIPPET>
129     * JDHeaderBackgroundImg(EmbedTagFileID="MyHTML")
130     * </EXTERNALCODESNIPPET></DIV>
131     * -->
132     * 
133     * <BR /><BR />The Upgrader would reference the {@code external-html-ids.properties} file
134     * which contained the definition.
135     */
136    String[] EmbedTagFileID() default { };
137
138    /** This is the default CSS-Class used for the {@code <DIV>} that is inserted. */
139    public static final String DEFAULT_CSS_CLASS = "JDWoodBoardDark";
140}