package Torello.JavaDoc;

import java.util.regex.Pattern;
import java.util.function.Predicate;

import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import java.lang.annotation.Repeatable;

import static java.lang.annotation.RetentionPolicy.SOURCE;
import static java.lang.annotation.ElementType.*;

// NOTE: Of all the weird things that could have been done to Java @Annotations, this by
//       far takes the cake...  Why is there another Annotation required to use the
//       @Repeatable Annotation?  I have to write @LJSRepeatable just to make @LinkJavaSource
//       repeatable?  Why?
// 
// 
// EXPORTS:
// 
//     public String    handle();
//     public String    typeName()      default "";
//     public Entity    entity();
//     public String    name();
//     public byte      paramCount()    default -1;
//     public String[]  paramNames()    default { };
//     public String[]  paramTypesJOW() default { };
// 
// 
// The following files are relatedf to this Annotation-Mirror Data-Class:
// 
// * Torello.JavaDoc.LinkJavaSource
//      For the actual annotation definition.
//      This is the actual @interface for the @LinkJavaSource Annotation
// 
// * package Torello.JDUInternal.Features.LINK_JAVA_SOURCE
//      This package does the "vast majority" of the work that is needed process a User's
//      Annotation-Placement.  The classes in the packages in this class look for, and load, all 
//      of the External '.java'-Files which have been specified by the programmer's annotation
//      uses.  These classes also perform the Source-Code HiLiting, and save the output to the
//      appropriate packge's '[pkg-javadoc]/ljs-hilite-files/' directory.  They finally, also,
//      generate the appropriate "HREF=..." so that an appropriate '<A HREF...>' link may be
//      inserted
// 
// * Torello.JDUInternal.Annotations.EntityAnnotations.Mirror.LJSMirror
//      The Data-Contents of Annotation that has been placed by the User on the Entity
//      (Entity: Method, Field, Constructor, Enum-Constant, Annotation-Element)
// 
// * Torello.JDUInternal.Annotations.EntityAnnotations.Processor.LinkJSourceProcessor
//      The Annotation-Processor that is invoked by 'javac' when compiling a class that uses the
//      @LinkJavaSource Annotation.  

/** <EMBED CLASS='external-html' DATA-FILE-ID=LJS_TOP_EXAMPLE> */
@Retention(SOURCE)
@Target({TYPE, FIELD, CONSTRUCTOR, METHOD})
@Repeatable(Torello.JavaDoc.hidden.LJSRepeatable.class)
public @interface LinkJavaSource
{
    /**
     * The {@code String}-Value which is provided to this element specifies which HiLited 
     * Source-Code File to use for the URL-Link in this {@code <A HREF>}-Button.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=LJS_HANDLE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=LJS_HANDLE_EX>
     */
    public String handle();


    // The "handle" Annotation-Element is Mandatory, Not Optional.  (No Default value
    // is provided in the @LinkJavaSource Annotation-Class).  It is supposed to contain
    // "a pointer" or "File-Name Nick-Name" (a handle!) to a file that has been listed
    // inside the File: 
    //       "../upgrade-files/json-config/ExtraJavaHiLiting.json"
    // 
    // Every one of the '.java' Source-Files listed inside that '.json' files must
    // contain:
    //      1) A Valid '.java' File-Name
    //      2) A handle for referencing that File-Name with the @LinkJavaSource
    //         Annotation

    /**
     * This {@code String} may be used to specify an '<B>Inner-Type</B>', '<B>Nested-Type</B>' or
     * possibly an '<B>Auxilliary-Class</B>'.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=LJS_TYPE_NAME>
     * <EMBED CLASS='external-html' DATA-FILE-ID=LJS_TYPE_NAME_EX>
     */
    public String typeName() default "";


    // It is altogether possible for the User to have requested that '.java' File be
    // Hi-Lited which contains a class that actually has one or more inner-types,
    // inner-interfaces or even auxiliary classes!
    // 
    // If the user would like the "name()" that he has provided to actually
    // reference something other than the primary Class, Interface, Enum or Record,
    // (such as an Inner-Type or an Auxiliary-Type), he must provided the exact,
    // Full-Package, name of the Class or Type inside that file that he is intending
    // to reference.
    // 
    // He may do this by passing a valid Full-Package Java Class or Type-Name to this
    // Optional Annotation-Element.
    // 
    // This Annotation-Element is Optional, and has a default value (assigned by the
    // 'javac' Annotations-Processor equal to the Empty-String)

    /**
     * When specifying a Line-Number to use for the link, identifies which kind of {@link Entity}
     * is being linked.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=LJS_ENTITY>
     * <EMBED CLASS='external-html' DATA-FILE-ID=LJS_ENTITY_EX>
     */
    public Entity entity() default Entity.METHOD;

    /**
     * When specifying a Line-Number to use, identifies the {@link Entity} or "Member" Name.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=LJS_NAME>
     * <EMBED CLASS='external-html' DATA-FILE-ID=LJS_NAME_EX>
     */
    public String name() default "";


    // The "name()" Annotation-Element should contain the name of the Member/Entity
    // contained by the Class/Interface/Type (CIET) which is specified by "handle()"
    // 
    // "name()" is allowed to be optional in the case that the user is specifying a
    // constructor.  If so, he must provide either a paramNames(), a paramTypesJOW or a
    // paramCount().
    // 
    // Specifically: "name" should be the name of a Field, Method,
    //               Constructor (Optional) or Enum-Constant from the CIET/Type named
    //               by "handle()"

    /**
     * When specifying the Line-Number of either a {@link Entity#METHOD Method} or a
     * {@link Entity#CONSTRUCTOR Constructor}, identifies the number of parameters contained by 
     * the Method or Constructor Signature.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=LJS_PARAM_COUNT>
     * <EMBED CLASS='external-html' DATA-FILE-ID=LJS_PARAM_COUNT_EX>
     */
    public byte paramCount() default -1;

    /**
     * When specifying the Line-Number of either a {@link Entity#METHOD Method} or a
     * {@link Entity#CONSTRUCTOR Constructor}, identifies the names of the parameters accepted by 
     * the Method or Constructor.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=LJS_PARAM_NAMES>
     * <EMBED CLASS='external-html' DATA-FILE-ID=LJS_PARAM_NAMES_EX>
     */
    public String[] paramNames() default { };

    /**
     * When specifying the Line-Number of either a {@link Entity#METHOD Method} or a
     * {@link Entity#CONSTRUCTOR Constructor}, identifies the Single-Word-Names for the 
     * <B>{@code 'types'}</B> of the Method's or Constructor's parameters.
     * 
     * <BR /><BR />For example, if a method such as {@code boolean equals(Object other)} were 
     * needing to be linked, the "Single Word Name" would be
     * <B STYLE='color: red;'>{@code String}</B>, rather than {@code 'java.lang.String'}
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=LJS_PARAM_TYPES_JOW>
     * <EMBED CLASS='external-html' DATA-FILE-ID=LJS_PARAM_T_JOW_EX>
     */
    public String[] paramTypesJOW() default { };
}