package Torello.JavaDoc;

import static Torello.Java.C.*;

import Torello.HTML.HTMLNode;
import Torello.HTML.TagNode;
import Torello.HTML.TextNode;
import Torello.HTML.SubSection;
import Torello.HTML.Replaceable;
import Torello.HTML.TagNodeIndex;
import Torello.HTML.DotPair;
import Torello.HTML.HTMLTags;
import Torello.HTML.TC;

import Torello.Java.ReadOnly.ReadOnlyList;

import java.util.Vector;
import java.util.TreeMap;
import java.util.TreeSet;

import java.io.Serializable;

import Torello.JDUInternal.Messager.Where.JDUUserAPI;
import Torello.JDUInternal.Messager.Messager;
import Torello.JDUInternal.Messager.Where.Where_Am_I;

import Torello.JDUInternal.Parse.HTML.TheREFL.D1_PrimaryRefl;
import Torello.JDUInternal.Parse.HTML.TheREFL.D2_ReflDLs;
import Torello.JDUInternal.Parse.HTML.TheREFL.ReflMapKeys;


/**
 * This class stores the HTML Detail-Descriptions retrieved from a Java Doc web-page 'Details
 * Section', and simultaneously, holds the reflection-data extracted from the
 * <CODE>'&#46;java'</CODE> corresponding source-code files - facilitating all changes to a Java
 * Doc Page deemed necessary.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=PROG_MOD_HTML>
 * <EMBED CLASS='external-html' DATA-FILE-ID=REFLHTML>
 * 
 * @param <ENTITY> This will take one of five type's: {@link Method}, {@link Constructor},
 * {@link Field}, {@link EnumConstant}, or {@link AnnotationElem}.   The HTML contained by an
 * instance of this class corresponds directly to the HTML contained by a detail section of one of
 * one of these five Members / Entities.
 */
@JDHeaderBackgroundImg(EmbedTagFileID="REFLECTION_HTML_CLASS")
@SuppressWarnings("rawtypes")
public class ReflHTML<ENTITY extends Declaration>
    implements java.io.Serializable, java.lang.Comparable<ReflHTML>
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1;

    // When the Messager Reports its errors, this class passes this reference to the Messager
    // to facilitate the printing of that information (What class encountered an error or warning
    // that needs to be printed by the Messager).

    private static final Where_Am_I WHERE_AM_I = JDUUserAPI.ReflectionHTML;


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructor
    // ********************************************************************************************
    // ********************************************************************************************


    // Primary Constructor for this class.  Note that all of the work for this constructor has
    // since been moved to the Data-Record classes located inside package:
    // 
    // Torello.JDUInternal.Parse.HTML.TheREFL
    // 
    // This constructor, now, does absolutely nothing but copy the computed fields from the
    // aforementioned Data-Records
    // 
    // Keeping HTML-Parsing code in a separate, internal, package allows me to "localize" the
    // complicated parsing code into a single location - far away from the end user.  This code
    // is dependent upon which of the Java-Doc Versions is being used.
    // 
    // Since October of 2024, HTML-Parsing Code has been moved to a single, JDUInternal,
    // suite of directories that are much easier to manage.  This constructor, for instance, just
    // block copies the fields from one of those JDUInternal Data-Record Classes.

    public ReflHTML(
            final D1_PrimaryRefl<ENTITY>    primaryDataRec,
            final D2_ReflDLs<ENTITY>        defListsRec,
            final String                    htmlID
        )
    {
        // This is stuff that was passed directly t TheREFL.D1_PrimaryRefl
        // These were saved into public-final fields in that class to make it "slightly faster"
        // to copy them into this class public-final fields

        this.entity         = primaryDataRec.entity;
        this.location       = primaryDataRec.location;
        this.entityAsEnum   = primaryDataRec.entityAsEnum;
        this.subSections    = primaryDataRec.subSections;


        // This was computed directly before this constructor was called, and then passed as a
        // parameter to this method

        this.htmlID = htmlID;


        // Stuff Computed in Torello.JDUInternal.Parse.HTML.TheREFL.D1_PrimaryRefl
        // This stuff was not "passed" to the "D1_PrimaryRefl" Data-Record, it was computed there,
        // and now it is simply copied and saved into this class public-final fields.

        this.endingLI           = primaryDataRec.endingLI;
        this.openingUL          = primaryDataRec.openingUL;
        this.hiLitedCode        = primaryDataRec.hiLitedCode;
        this.name               = primaryDataRec.name;
        this.signature          = primaryDataRec.signature;
        this.descFromTypeLabel  = primaryDataRec.descFromTypeLabel;

        this.needToAddOpenCloseDLsForHiLitedDetails =
            primaryDataRec.needToAddOpenCloseDLsForHiLitedDetails;


        // The "Definition Lists <DL>" Data-Record fills up one TreeMap of SubSections, and
        // one ReadOnlyList of this stuff.

        this.miscSimpleTagLabels = defListsRec.miscSimpleTagLabels;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // HTML Processor's Special Access Stuff
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This points to the opening {@code <UL>} tag for the detail.  It's contents may be modified
     * to include CSS classes or id's.
     */
    public final TagNodeIndex openingUL;

    private static final TagNode OPEN_DL    = HTMLTags.hasTag("dl", TC.OpeningTags);
    private static final TagNode CLOSE_DL   = HTMLTags.hasTag("dl", TC.ClosingTags);

    private Replaceable hiLitedCode = null;

    private final boolean needToAddOpenCloseDLsForHiLitedDetails;

    public void insertHiLitedDetail(Vector<HTMLNode> hiLitedDetail)
    {
        if (needToAddOpenCloseDLsForHiLitedDetails)
        {
            hiLitedDetail.insertElementAt(OPEN_DL, 0);
            hiLitedDetail.add(CLOSE_DL);
        }

        this.hiLitedCode = this.hiLitedCode.setHTML(hiLitedDetail);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Main Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This is the actual type-reflection (type-mirror) of the {@code Entity} extracted from the
     * Java Doc {@code '.html'} web-page file, <I><B>and</B> from the </I> {@code '.java'} Source
     * Code File.
     * 
     * <BR /><BR />Since the type-parameter {@code ENTITY} must extend {@link Declaration}, this
     * field will hold all of the information that was parsed &amp; extracted by Java Parser.
     * Depending on what type of instance of {@code Declaration} this represents, this will field
     * will contain all of the parameter-names, parameter-types, modifiers, and exceptions that
     * are associated with the entity.
     * 
     * <BR /><BR />This will take one of five type's: {@link Method}, {@link Constructor},
     * {@link Field}, {@link EnumConstant}, {@link AnnotationElem}.  This allows you to retrieve
     * all reflected information, quickly and easily, associated with the Java Doc HTML "Detail
     * Section" for a particular method, field, constructor etc...
     */
    public final ENTITY entity;

    /**
     * This is used as a 'faster-way' to retrieve what type of Entity this "Reference-HTML" 
     * detail-section is being represented here.  This makes the code more readable than using
     * Java's {@code 'getClass()'} reflection to identify whether this 'Detail Section HTML' holds
     * the HTML for a Method, Field, Constructor, Enumeration, etc...
     * 
     * <BR /><BR />The value in {@code 'entityAsEnum'} shall always be identical to the type of
     * the {@link #entity}.  So for instance, if {@link #entity} contained a {@link Field} instance,
     * this field would be equal to {@link Entity#FIELD}.  If this entity represented a
     * {@link Method} HTML Detail-Section element, then this field would hold
     * {@link Entity#METHOD}.
     */
    public final Entity entityAsEnum;

    // The location in the parsed Java Doc '.html' web-page from whence this HTML was retrieved.
    // This field is declared final.  The many sections, parts, and segments of a Java Doc
    // generated page can have their contents added, abbreviated, and extended, but they cannot be
    // moved to different places on the page.

    private final DotPair location;

    // This is used to insert two "wrapper dividers" - the HTML <DIV> Elements that "wrap" around
    // the contents of a ReflHTML.  These wrapper DIV's (of which there are two) are need for the 
    // maximize, minimize & partialize buttons.  Both of the two DIV's have **BOTH** a CSS-ID
    // **AND** a CSS-CLASS that are used by two-line Java-Script methods that set the CSS "display"
    // property to "block" and "none" (for hiding and showing these Refl's at the click of a
    // button)

    private final int endingLI;


    // ********************************************************************************************
    // ********************************************************************************************
    // More Main Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Each Deteail Entity on a JavaDoc Page has a <I>small and empty</I> Anchor-Link, <I>with an
     * ID Attribute</I> that allows the browser to redirect to the detail on a JavaDoc page using
     * a relative URL to redirect to the details location on the web-page.  If that detail element
     * was found, it's will be stored in this field.  (Otherwise, this field will contain null)
     * 
     * <BR /><BR />Below is the <CODE>&lt;A ID=..&gt;</CODE> generated by Java Doc for a method
     * that is named {@code 'length'}, and takes zero parameters as input.
     * 
     * <DIV CLASS=HTML>{@code
     * <a id="length()">
     * <!--   -->
     * </a>
     * }</DIV>
     */
    public final String htmlID;


    // Every Detail-Element (Method, Field, Constructor, Enum-Constant and Annotation-Element)
    // **MUST** have a name.  This should be a member field, instead of an entry in the
    // TreeMap of 'possible' subsections

    private final SubSection name;
    private final SubSection signature;

    // This Vector's contents are auto-inserted by the "NavButtons" class
    private final Vector<HTMLNode> detailNavBar = new Vector<>();



    // This is a TreeMap that will hold all of the 'optional' Detail-Elements.  Many of the
    // entries in this TreeMap will be very common (at least as far as Java-HTML Type's goes),
    // but *NONE* of them are 'mandatory' - Java Doc will not auto-create the detail-elements
    // that are stored in this map.  They must be explicitly added by the user with taglets

    private final TreeMap<Character, SubSection> subSections;


    // The other 'simpleTagLabels' just have their index and value saved, furthermore this
    // array-list is only built if one is found/identified in the JavaDoc page.  99% of the
    // types in JavaHTML do not have these...

    private final ReadOnlyList<TagNodeIndex> miscSimpleTagLabels;

    /**
     * This boolean indicates that the HTML description provided by this JavaDoc Detail has
     * been copied from an parent-class or from an interface.  In cases where an abstract method
     * is implemented, the programmer may "opt-out" of typing anything about what the method's
     * purpose is.  If so, JavaDoc automatically copies the abstract (or parent) method's
     * description, and leaves a little note saying so.
     * 
     * <BR /><BR />Note that when this occurs, there will by two HTML {@code <DIV CLASS="block">}
     * elements on the page for that detail.
     */
    public final boolean descFromTypeLabel;


    // ********************************************************************************************
    // ********************************************************************************************
    // SubSection Accessor Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns an HTML-{@code Vector} of the HTML used to display the
     * <B STYLE='color: red;'>name</B> of a detail element.
     * 
     * <BR /><BR />This also contains the same information as in the field
     * {@link Declaration#name}, which is reflected (using <B>{@code Java Parer}</B>) from the
     * associated {@code 'java'} source-code file.  The HTML for this segment is listed, here
     * below:
     * 
     * <DIV CLASS=HTML>{@code
     * <h4> [Name] </h4>
     * }</DIV>
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=REFL_MODIFY>
     * 
     * @return An HTML-{@code Vector} of the Java Doc <B STYLE='color: red;'>name</B>
     * segment of this detail.  This method will never return null, as all detail-elements have
     * a name.
     * 
     * @see Declaration#name
     */
    public Vector<HTMLNode> name() { return name.html; }

    /**
     * Returns an HTML-{@code Vector} of the HTML used to display the
     * <B STYLE='color: red;'>signature</B> of a detail element.
     * 
     * <BR /><BR />This also contains the same information as in the field
     * {@link Declaration#signature}, which is reflected (using <B>{@code Java Parer}</B>) from the
     * associated {@code 'java'} source-code file.  In the HTML below it is the text that appears
     * between the <CODE>&lt;PRE&gt;</CODE> tags.  Note that the HTML {@code 'class'} attribute
     * (present, below) will not always be included in every detail element.
     * 
     * <DIV CLASS=HTML>{@code
     * <h4> [Name] </h4>
     * <pre class="Signature"> ... </pre>
     * }</DIV>
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=REFL_MODIFY>
     * 
     * @return An HTML-{@code Vector} of the Java Doc <B STYLE='color: red;'>signature</B>
     * segment of this detail.  This method will never return null, as all detail-elements have
     * a signature.
     * 
     * @see Declaration#signature
     */
    public Vector<HTMLNode> signature() { return signature.html; }

    /**
     * Returns an HTML-{@code Vector} of the HTML used to display the
     * <B STYLE='color: red;'>description</B> of a detail element.
     * 
     * <BR /><BR />This HTML is generated by the Java Doc Tool using the text provided by a
     * programmer in his Java Doc Comments directly above the code in a {@code '.java'} file.  In
     * a Java Doc {@code '.html'} file, the description is always surrounded by an HTML divider
     * ({@code '<DIV>'}) element, as appears below:
     * 
     * <DIV CLASS=HTML>{@code
     * <div class="block"> ... [Text-Description of Method, Field, etc...] ... </div>
     * }</DIV>
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=REFL_MODIFY>
     * 
     * @return An HTML-{@code Vector} of the Java Doc <B STYLE='color: red;'>description</B>
     * segment of this detail.  Since a description is not mandatory, and it is not an
     * auto-generated segment of a detail element, <I>this method will return null if a programmer
     * has not written or included a description for this particular detail element in his
     * source-code for this detail element.</I>
     * 
     */
    public final Vector<HTMLNode> description()
    {
        SubSection s = subSections.get(ReflMapKeys.DESCRIPTION_KEY);
        return (s!= null) ? s.html : null;
    }

    /**
     * Returns an HTML-{@code Vector} of the HTML used to display the
     * <B STYLE='color: red;'>Default Annotation Element Value</B> of an Annotation-Detail element.
     * 
     * <BR /><BR />This also contains the same information as in the field
     * {@link AnnotationElem#defaultValue}, which is reflected (using <B>{@code Java Parer}</B>)
     * from the associated {@code 'java'} source-code file.  The HTML for this segment is listed,
     * here below:
     * 
     * <DIV CLASS=HTML>{@code
     * <dl>
     * <dt>Default:</dt>
     * <dd> [ some values possibly inserted here ]</dd>
     * </dl>
     * }</DIV>
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=REFL_MODIFY>
     * 
     * <BR /><BR />Unless this detail is an "Annotation Detail", calling this method will generate
     * an exception-throw.
     * 
     * @return An HTML-{@code Vector} of an annotation detail element's
     * <B STYLE='color: red;'>Default Value</B>.  If the annotation does not have a default value
     * assigned, or it is not present on the Java Doc Page, this method will return null.
     * 
     * @throws DetailsException If the {@code ReflHTML} instance on which this method is being
     * invoked is not for an Annotation Detail, the invocation will generate a
     * {@code DetailsException}
     * 
     * @see AnnotationElem#defaultValue
     */
    public Vector<HTMLNode> annotationDefault()
    {
        if (entityAsEnum != Entity.ANNOTATION_ELEM)

            throw new DetailsException(
                "This ReflHTML is a Reflection of a(n) " + entityAsEnum.toString() + " details, " +
                "however only Annotations may have Annotation-Element Default Values."
            );

        SubSection s = subSections.get(ReflMapKeys.ANNOTATION_DEFAULT_KEY);
        return (s!= null) ? s.html : null;
    }

    /**
     * Returns an HTML-{@code Vector} of the HTML used to display the
     * <B STYLE='color: red;'>Returns:</B> segment of a Method Detail element.
     * 
     * <BR /><BR />This also contains some of the information present in the field
     * {@link Method#returnType}, which is reflected (using <B>{@code Java Parer}</B>) from the
     * associated {@code 'java'} source-code file.
     * 
     * <BR /><BR />This HTML is auto-generated by Java Doc using the
     * <B><CODE STYLE='color: blue;'>&commat;return</CODE></B> taglet's, which may be provided
     * by a programmer in his {@code '.java'} source-code file.  The HTML output generated by Java
     * Doc is as below:
     * 
     * <DIV CLASS=HTML>{@code
     * <dt><span class="returnLabel">Returns:</span></dt>
     * <dd> [User-Provided Return-Value Information, as HTML, Here] </dd>
     * }</DIV>
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=REFL_MODIFY>
     * 
     * <BR /><BR />Only methods may have return-values.  Furthermore, only methods for which the
     * programmer has provided a <B><CODE STYLE='color: blue;'>&commat;return</CODE></B>
     * taglet entry will the result of this method be non-null.
     * 
     * @return An HTML-{@code Vector} of a method detail element's
     * <B STYLE='color: red;'>Returns:</B> label.  If the method does not have such a label,
     * because the programmer did not provide a
     * <B><CODE STYLE='color: blue;'>&commat;return</CODE></B> taglet, this method will
     * return null.
     * 
     * @throws DetailsException If the {@code ReflHTML} instance on which this method is being
     * invoked is not for an Method Detail, the invocation will generate a
     * {@code DetailsException}
     * 
     * @see Method#returnType
     */
    public Vector<HTMLNode> returns()
    {
        if (entityAsEnum != Entity.METHOD)

            throw new DetailsException(
                "This ReflHTML is a Reflection of a(n) " + entityAsEnum.toString() + " details, " +
                "however only Methods may have Return-Values."
            );

        SubSection s = subSections.get(ReflMapKeys.RETURNS_KEY);
        return (s!= null) ? s.html : null;
    }

    /**
     * Returns an HTML-{@code Vector} of the HTML used to display the
     * <B STYLE='color: red;'>See Also:</B> segment of any detail element.
     * 
     * <BR /><BR />This HTML is auto-generated by Java Doc using the
     * <B><CODE STYLE='color: blue;'>&commat;see</CODE></B> taglet's, which may be provided
     * by a programmer in his {@code '.java'} source-code file.  The HTML output generated by Java
     * Doc is as below:
     * 
     * <DIV CLASS=HTML>{@code
     * <dt><span class="seeLabel">See Also:</span></dt>
     * <dd><a href="#someMethod()"><code>someMethod()</code></a></dd>
     * }</DIV>
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=REFL_MODIFY>
     * 
     * <BR /><BR />Only detail elements for which the programmer has provided at least one
     * <B><CODE STYLE='color: blue;'>&commat;see</CODE></B> taglet entry will the result of
     * this method be non-null.
     * 
     * @return An HTML-{@code Vector} of a method detail element's
     * <B STYLE='color: red;'>See Also:</B> label.  If the method does not have such a label,
     * because the programmer did not provide any
     * <B><CODE STYLE='color: blue;'>&commat;see</CODE></B> taglet, this method will
     * return null.
     * 
     */
    public Vector<HTMLNode> seeAlso()
    {
        SubSection s = subSections.get(ReflMapKeys.SEE_ALSO_KEY);
        return (s!= null) ? s.html : null;
    }

    /**
     * Returns an HTML-{@code Vector} of the HTML used to display the
     * <B STYLE='color: red;'>Throws:</B> segment of a Method or Constructor Detail element.
     * 
     * <BR /><BR />This also contains some of the information present in the field
     * {@link Callable#exceptions}, which is reflected (using <B>{@code Java Parer}</B>) from the
     * associated {@code 'java'} source-code file.
     * 
     * <BR /><BR />This HTML is auto-generated by Java Doc using the
     * <B><CODE STYLE='color: blue;'>&commat;throws</CODE></B> taglet's, which may be provided
     * by a programmer in his {@code '.java'} source-code file.  If a method or constructor is
     * throwing <I>checked exceptions</I>, Java Doc will auto-create a 'Throws:' label / segment.
     * The HTML output generated by Java Doc is as below:
     * 
     * <DIV CLASS=HTML>{@code
     * <dt><span class="throwsLabel">Throws:</span></dt>
     * <dd> [Text explaining thrown exceptions by a method or constructor]</dd>
     * }</DIV>
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=REFL_MODIFY>
     * 
     * <BR /><BR />Only methods and constructors are capable of throwing exceptions.  Furthermore,
     * only details for which the programmer has provided a
     * <B><CODE STYLE='color: blue;'>&commat;throws</CODE></B> taglet entry (or which throw
     * checked-exceptions) will the result of this method be non-null.
     * 
     * @return An HTML-{@code Vector} of a method or constructor detail element's
     * <B STYLE='color: red;'>Throws:</B> label.  If the detail does not have such a label, this
     * method will return null.
     * 
     * @throws DetailsException If the {@code ReflHTML} instance on which this method is being
     * invoked is <I><B>neither</B></I> a Method Detail <B><I>nor</I></B> a Constructor Detail, the
     * invocation will generate a {@code DetailsException}
     * 
     * @see Callable#exceptions
     */
    public Vector<HTMLNode> throwing()
    {
        if ((entityAsEnum != Entity.METHOD) && (entityAsEnum != Entity.CONSTRUCTOR))

            throw new DetailsException(
                "This ReflHTML is a Reflection of a(n) " + entityAsEnum.toString() + " details, " +
                "however only Methods and Constructors may throw Exceptions."
            );

        SubSection s = subSections.get(ReflMapKeys.THROWS_KEY);
        return (s!= null) ? s.html : null;
    }

    /**
     * Returns an HTML-{@code Vector} of the HTML used to display the
     * <B STYLE='color: red;'>Parmeters:</B> segment of a Method or Constructor Detail element.
     * 
     * <BR /><BR />This also contains some of the information present in the fields
     * {@link Callable#parameterNames} and {@link Callable#parameterTypes}, which is reflected
     * (using <B>{@code Java Parer}</B>) from the associated {@code 'java'} source-code file.
     * 
     * <BR /><BR />This HTML is auto-generated by Java Doc using the
     * <B><CODE STYLE='color: blue;'>&commat;param</CODE></B> taglet's, which may be provided
     * by a programmer in his {@code '.java'} source-code file.  The HTML output generated by Java
     * Doc is as below:
     * 
     * <DIV CLASS=HTML>{@code
     * <dt><span class="paramLabel">Parameters:</span></dt>
     * <dd><code>[Parameter Name]</code> - [Some Parameter Description]</dd>
     * }</DIV>
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=REFL_MODIFY>
     * 
     * <BR /><BR />Only methods and constructors may accept input parameters.  Furthermore,
     * only details for which the programmer has provided a
     * <B><CODE STYLE='color: blue;'>&commat;param</CODE></B> taglet entry will there be 
     * parameter descriptive-text on a Java Doc Page. The result of this method will be non-null,
     * only in cases where such descriptions have been included in their JavaDoc commenting.
     * 
     * @return An HTML-{@code Vector} of a method or constructor detail element's
     * <B STYLE='color: red;'>Parameters:</B> label.  If the detail does not have such a label,
     * this method will return null.
     * 
     * @throws DetailsException If the {@code ReflHTML} instance on which this method is being
     * invoked is <I><B>neither</B></I> a Method Detail <B><I>nor</I></B> a Constructor Detail, the
     * invocation will generate a {@code DetailsException}
     * 
     * @see Callable#parameterNames
     * @see Callable#parameterTypes
     */
    public Vector<HTMLNode> parameters()
    {
        if ((entityAsEnum != Entity.METHOD) && (entityAsEnum != Entity.CONSTRUCTOR))

            throw new DetailsException(
                "This ReflHTML is a Reflection of a " + entityAsEnum.toString() + " details, " +
                "however only Methods and Constructors may have Parameters."
            );

        SubSection s = subSections.get(ReflMapKeys.PARAMETERS_KEY);
        return (s!= null) ? s.html : null;
    }

    /**
     * Returns an HTML-{@code Vector} of the HTML used to display the
     * <B STYLE='color: red;'>Type Parmeters:</B> segment of a Method or Constructor Detail
     * element.
     * 
     * <BR /><BR />This HTML is auto-generated by Java Doc using the
     * <B><CODE STYLE='color: blue;'>&commat;param</CODE> <CODE>&lt;T&gt;</CODE></B> taglet's,
     * which may be provided by a programmer in his {@code '.java'} source-code file.  The HTML
     * output generated by Java Doc is as below:
     * 
     * <DIV CLASS=HTML>{@code
     * <dt><span class="paramLabel">Type Parameters:</span></dt>
     * <dd><code>[Type Parameter <T>]</code> - [Some Type Parameter Description]</dd>
     * }</DIV>
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=REFL_MODIFY>
     * 
     * <BR /><BR />Only methods and constructors will allow type-parameters.  Furthermore,
     * only details for which the programmer has provided a
     * <B><CODE STYLE='color: blue;'>&commat;param</CODE> <CODE>&lt;T&gt;</CODE></B> taglet
     * entry will there be parameter descriptive-text on a Java Doc Page. The result of this method
     * will be non-null, only in cases where such descriptions have been included in their
     * JavaDoc commenting.
     * 
     * @return An HTML-{@code Vector} of a method or constructor detail element's
     * <B STYLE='color: red;'>Type Parameters:</B> label.  If the detail does not have such a
     * label, this method will return null.
     * 
     * @throws DetailsException If the {@code ReflHTML} instance on which this method is being
     * invoked is <I><B>neither</B></I> a Method Detail <B><I>nor</I></B> a Constructor Detail, the
     * invocation will generate a {@code DetailsException}
     */
    public Vector<HTMLNode> typeParameters()
    {
        if ((entityAsEnum != Entity.METHOD) && (entityAsEnum != Entity.CONSTRUCTOR))

            throw new DetailsException(
                "This ReflHTML is a Reflection of a(n) " + entityAsEnum.toString() + " details, " +
                "however only Methods and Constructors may have Type-Parameters."
            );

        SubSection s = subSections.get(ReflMapKeys.TYPE_PARAMETERS_KEY);
        return (s!= null) ? s.html : null;
    }

    /**
     * Returns an HTML-{@code Vector} of the HTML used to display the
     * <B STYLE='color: red;'>Overrides:</B> segment of a Method Detail element.
     * 
     * <BR /><BR />This HTML is auto-generated by Java Doc, for methods which override a parent
     * class or interface. The HTML output generated by Java Doc is as below:
     * 
     * <DIV CLASS=HTML>{@code
     * <dt><span class="overrideSpecifyLabel">Overrides:</span></dt>
     * <dd><code> [ Some Name ]</code>&nbsp;in interface&nbsp;<code> [Interface Name] </code></dd>
     * }</DIV>
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=REFL_MODIFY>
     * 
     * <BR /><BR />Only methods may override other methods.  The result of this method will
     * be non-null, only in cases where the Method Detail on which this invocation was made is
     * actually an overrided method.
     * 
     * @return An HTML-{@code Vector} of a method detail element's
     * <B STYLE='color: red;'>Overrides:</B> label.  If the detail does not have such a label, this
     * method will return null.
     * 
     * @throws DetailsException If the {@code ReflHTML} detail instance on which this method is
     * being invoked is not a Method Detail, then a {@code DetailsException} will throw.
     */
    public Vector<HTMLNode> overrides()
    {
        if (entityAsEnum != Entity.METHOD)

            throw new DetailsException(
                "This ReflHTML is a Reflection of a(n) " + entityAsEnum.toString() + " details, " +
                "however only Methods may have \"Overrides:\" Labels."
            );

        SubSection s = subSections.get(ReflMapKeys.OVERRIDES_KEY);
        return (s!= null) ? s.html : null;
    }

    /**
     * Returns an HTML-{@code Vector} of the HTML used to display the
     * <B STYLE='color: red;'>Specified by:</B> segment of a Method Detail element.
     * 
     * <BR /><BR />This HTML is auto-generated by Java Doc, for methods which implement another
     * method that was specified by an interface which the type implements, or a method specified
     * by an abstract parent super-class.  The HTML output generated by Java Doc is as below:
     * 
     * <DIV CLASS=HTML>{@code
     * <dt><span class="overrideSpecifyLabel">Specified by:</span></dt>
     * <dd><code> [ Some Name ]</code>&nbsp;in interface&nbsp;<code> [Interface Name] </code></dd>
     * }</DIV>
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=REFL_MODIFY>
     * 
     * <BR /><BR />Only methods may implement a "specified-method" (obviously!)  The result of this
     * method will be non-null - only in cases where the Method Detail on which this invocation was
     * made <I>actually implements another abstract method declaration.</I>
     * 
     * @return An HTML-{@code Vector} of a method detail element's
     * <B STYLE='color: red;'>Specified by:</B> label.  If the detail does not have such a label,
     * this method will return null.
     * 
     * @throws DetailsException If the {@code ReflHTML} detail instance on which this method is
     * being invoked is not a Method Detail, then a {@code DetailsException} will throw.
     */
    public Vector<HTMLNode> specifiedBy()
    {
        if (entityAsEnum != Entity.METHOD)

            throw new DetailsException(
                "This ReflHTML is a Reflection of a(n) " + entityAsEnum.toString() + " details, " +
                "however only Methods may have \"Specified-By:\" Labels."
            );

        SubSection s = subSections.get(ReflMapKeys.SPECIFIED_BY_KEY);
        return (s!= null) ? s.html : null;
    }

    /** This will be implented at a later date.  For now, this throws an exception. */
    public Vector<HTMLNode> author()
    {
        if (1 == 1) throw new Torello.Java.ToDoException("Not Tested Yet");

        SubSection s = subSections.get(ReflMapKeys.AUTHOR_KEY);
        return (s!= null) ? s.html : null;
    }

    /**
     * Returns an HTML-{@code Vector} of the HTML used to display the
     * <B STYLE='color: red;'>Specified by:</B> segment of a Method Detail element.  
     *  
     * <DIV CLASS=HTML>{@code
     * <dt><span class="simpleTagLabel">Since:</span></dt>
     * <dd> [ Version Number Information ]</dd>
     * }</DIV>
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=REFL_MODIFY>
     * 
     * <BR /><BR />Only details for which the programmer has provided a
     * <B><CODE STYLE='color: blue;'>&commat;since</CODE></B> taglet entry will there be 'since'
     * descriptive-text on a Java Doc Page. The result of this method will be non-null, only in
     * cases where such version-information has been included in their JavaDoc commenting.
     * 
     * @return An HTML-{@code Vector} of a method detail element's
     * <B STYLE='color: red;'>Since:</B> label.  If the detail does not have such a label, this
     * method will return null. 
     */
    public Vector<HTMLNode> since()
    {
        SubSection s = subSections.get(ReflMapKeys.SINCE_KEY);
        return (s!= null) ? s.html : null;
    }

    /**
     * Returns an HTML-{@code Vector} of the HTML used to display the
     * <B STYLE='color: red;'>Navigation Button-Bar</B> of a detail element.
     * 
     * <BR /><BR />This is a row of buttons that is present directly below the signature of an
     * HTML Detail-Entry.  This row of buttons is automatically generated by the Java-Doc Upgrader
     * Tool.  It isn't Standard JavaDoc HTML.
     * 
     * <BR /><BR />The actual HTML inserted by the Upgrader-Tool is included directly below:
     * 
     * <DIV CLASS=HTML>{@code
     * <DIV CLASS=DetailNav>
	 *      <A HREF='#openTagPWA()'>&#129093;</A>
	 *      &nbsp;<A HREF='#isOpenTagPWA()'>&#129095;</A>
	 *      &nbsp;<A onclick="flashSumm('MD244')">&#8648;</A>
	 *      &nbsp;<A HREF='hilite-files/HTMLNode.java.html#L273'>&#11179;</A>
	 *      <SPAN>
	 *          <A onclick='minimize(244)'>&#x1F5D5;</A>
	 *          &nbsp;<A onclick='partialize(244)'>&#x1F5D7;</A>
	 *          &nbsp;<A onclick='maximize(244)'>&#x1F5D6;</A>
	 *      </SPAN>
	 *      <NOSCRIPT>
	 *      <DIV ID=NoScriptMPMAB>JavaScript is disabled on your browser.</DIV>
	 *      </NOSCRIPT>
     * </DIV>
     * }</DIV>
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=REFL_MODIFY>
     * 
     * @return An HTML-{@code Vector} of the Java Doc
     * <B STYLE='color: red;'>Navigation Button-Bar</B> segment of this detail.  This method will
     * never return null, as all detail-elements have these buttons.
     */
    public Vector<HTMLNode> detailNavBar()
    { return detailNavBar; }


    // ********************************************************************************************
    // ********************************************************************************************
    // java.lang.Cloneable, java.lang.Comparable
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Java's {@code interface Cloneable} requirements.  This provides a "Deep Clone", where all
     * internal {@code Vector's} and {@code SubSection's} are also cloned, rather than a
     * "Shallow Clone", having identical references.
     * 
     * @return A new {@code ReflHTML} whose internal fields are identical to this one.
     */
    public ReflHTML<ENTITY> clone() { return new ReflHTML<>(this); }

    // Clone Constructor.
    @SuppressWarnings("unchecked")
    ReflHTML(ReflHTML<ENTITY> other)
    {
        this.entity             = other.entity; /* not cloned, the reflected entity */
        this.entityAsEnum       = other.entityAsEnum;
        this.location           = other.location; /* immutable, no need to clone */
        this.endingLI           = other.endingLI;
        this.htmlID             = other.htmlID;
        this.openingUL          = other.openingUL;
        this.name               = other.name.clone();
        this.signature          = other.signature.clone();
        this.descFromTypeLabel  = other.descFromTypeLabel;

        // The Code-HiLited Details "Special Additions"
        this.hiLitedCode = other.hiLitedCode;

        this.needToAddOpenCloseDLsForHiLitedDetails =
            other.needToAddOpenCloseDLsForHiLitedDetails;

        this.subSections = (TreeMap<Character,SubSection>) other.subSections.clone();


        // Since the time when this was converted to a "ReadOnlyList", this is no longer cloned,
        // this reference is now just copied.  ReadOnly stuff doesn't need to be cloned.

        this.miscSimpleTagLabels = other.miscSimpleTagLabels;
    }

    /**
     * Java's {@code interface Comparable<T>} requirements.  This does a very simple comparison
     * using the {@code location} field.
     * 
     * <BR /><BR /><B><SPAN STYLE="color: red;">FINAL METHOD:</B></SPAN> This method is declared 
     * {@code final}, and cannot be modified by sub-classes.
     * 
     * @param other Any other {@code ReflHTML} to be compared to {@code 'this' ReflHTML}
     * 
     * @return An integer that fulfils Java's {@code interface Comparable<T> public boolean
     * compareTo(T t)} method requirements.
     * 
     * @see DotPair#compareTo(DotPair)
     */
    public final int compareTo(ReflHTML other)
    { return this.location.compareTo(other.location); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Rebuilding a ReflHTML from it's pieces
    // ********************************************************************************************
    // ********************************************************************************************


    private static final Vector<HTMLNode> TEMP_END_VEC = new Vector<>(1);

    TreeSet<Replaceable> allReplaceables()
    {
        TreeSet<Replaceable> replaceables = new TreeSet<>();
        SubSection ss = null;

        replaceables.add(openingUL);
        replaceables.add(this.name);

        replaceables.add
            (Replaceable.createInsertion(this.name.location.end + 1, this.detailNavBar));

        replaceables.add(this.signature);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Add "Maximize-Partialize-Minimize" Button <DIV>'s - EMBARRASING THAT THIS IS DONE HERE
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // It seems like this isn't the best place to do this, but I simply am at a loss for words
        // about where I *SHOULD* put this stuff.

        this.signature.html.add(
            0,
            new TextNode("<DIV CLASS=ORD ID=ORD" + this.entity.id + ">\n")
        );

        this.signature.html.add
            (new TextNode("\n<DIV CLASS=IRD ID=IRD" + this.entity.id + ">\n"));

        Vector<HTMLNode> TEMP_VEC = new Vector<>();

        TEMP_VEC.add(
            new TextNode(
                "\n</DIV> <!-- IRD" + this.entity.id + " -->" +
                "\n</DIV> <!-- ORD" + this.entity.id + " -->\n\n"
            )
        );

        replaceables.add(Replaceable.createInsertion(endingLI, TEMP_VEC));

    
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // All of the other's
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        if ((ss = subSections.get(ReflMapKeys.DESCRIPTION_KEY)) != null)
            replaceables.add(ss);

        if ((ss = subSections.get(ReflMapKeys.ANNOTATION_DEFAULT_KEY)) != null)
            replaceables.add(ss);

        if ((ss = subSections.get(ReflMapKeys.RETURNS_KEY)) != null)
            replaceables.add(ss);

        if ((ss = subSections.get(ReflMapKeys.SEE_ALSO_KEY)) != null)
            replaceables.add(ss);

        if ((ss = subSections.get(ReflMapKeys.THROWS_KEY)) != null)
            replaceables.add(ss);

        if ((ss = subSections.get(ReflMapKeys.PARAMETERS_KEY)) != null)
            replaceables.add(ss);

        if ((ss = subSections.get(ReflMapKeys.TYPE_PARAMETERS_KEY)) != null)
            replaceables.add(ss);

        if ((ss = subSections.get(ReflMapKeys.OVERRIDES_KEY)) != null)
            replaceables.add(ss);

        if ((ss = subSections.get(ReflMapKeys.SPECIFIED_BY_KEY)) != null)
            replaceables.add(ss);

        if ((ss = subSections.get(ReflMapKeys.AUTHOR_KEY)) != null)
            replaceables.add(ss);

        if ((ss = subSections.get(ReflMapKeys.SINCE_KEY)) != null)
            replaceables.add(ss);

        replaceables.add(hiLitedCode);

        return replaceables;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // THE NEW-THING: Garbage-Collector Helper?
    // ********************************************************************************************
    // ********************************************************************************************
    // 
    // Does this help?  Is this "good" for the Garbage-Collect?  Is this going to speed it up,
    // or slow it down?  This is just a "C-Styled" FREE or DESTORY method...
    // It isn't publicly visible anyway...
    //
    // NOTE: Many of the null checks are completely superfluous, but not all of them...
    //       In any case, the worst feeling in the world would be NPE for this silly little
    //       "optimization"

    void clear()
    {
        // public final TagNodeIndex openingUL;
        if (openingUL != null) openingUL.n = null;

        // private final SubSection name;
        if (name != null) { name.html.clear(); name.html = null; }

        // private final SubSection signature;
        if (signature != null) { signature.html.clear(); signature.html = null; }

        // private final TreeMap<Character, SubSection> subSections = new TreeMap<>();
        if (subSections != null)
        {
            for (SubSection ss : subSections.values())
            {
                ss.html.clear();
                ss.html = null;
            }

            subSections.clear();
        }

        // private Replaceable hiLitedCode = null;
        if (hiLitedCode != null) { hiLitedCode.clearHTML(); hiLitedCode = null; }
    }
}