package Torello.JavaDoc;

import Torello.HTML.*;
import Torello.HTML.NodeSearch.*;
import Torello.Java.*;

import static Torello.Java.C.*;

import java.util.*;

import java.io.Serializable;

import Torello.JDUInternal.GeneralPurpose.Messager;

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


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


    // ********************************************************************************************
    // ********************************************************************************************
    // EVERYTHING ELSE
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * 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 = new TreeMap<>();

    // These are all of the keys that are used for the SubSections that will be stored inside
    // this TreeMap

    private static final Character DESCRIPTION_KEY          = 'a';
    private static final Character ANNOTATION_DEFAULT_KEY   = 'b';
    private static final Character RETURNS_KEY              = 'c';
    private static final Character SEE_ALSO_KEY             = 'd';
    private static final Character THROWS_KEY               = 'e';
    private static final Character PARAMETERS_KEY           = 'f';
    private static final Character TYPE_PARAMETERS_KEY      = 'g';
    private static final Character OVERRIDES_KEY            = 'h';
    private static final Character SPECIFIED_BY_KEY         = 'i';
    private static final Character AUTHOR_KEY               = 'j';
    private static final Character SINCE_KEY                = 'k';

    // 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 ArrayList<TagNodeIndex> miscSimpleTagLabels = null;

    /**
     * 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(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(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(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(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(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(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(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(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(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(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(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; }


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


    private String detErrMsg(Vector<HTMLNode> html, DotPair location)
    {
        String htmlStr = Util.rangeToString(html, location);
        return StrPrint.abbrevEnd(htmlStr, false, 300);
    }

    /**
     * Constructs an instance of this class.
     * 
     * @param entity This identifies which "Entity-Type" from which the HTML provided was derived.
     * If the HTML-{@code Vector} passed to this constructor were taken from a "Method Detail" part
     * of a Java Doc Web-Page, then this parameter would be passed {@code Entity.METHOD}
     * 
     * @param location The exact location on the Java Doc Web-Page from whence the HTML was
     * extracted.  It is important to note that this class facilitates changes, additions, and
     * removal of HTML tags to a specific Detail-Segment of a CIET <B>"Details Section"</B>.
     * 
     * <BR /><BR />After the changes have been made, and all other HTML processors in this package
     * have completed their updates, this HTML will need to replace the old-stuff in the page
     * {@code Vector}.  Keeping this location around makes this a simple replacement that has been
     * optimized.
     * 
     * <BR /><BR />Note that changing nodes in a {@code Vector<HTMLNode>}) can become profusely
     * in-efficient <I>if those changes are done in-place!</I>  By extracting small portions of
     * the HTML-Vector, and only modifying small parts (all the while saving the original location
     * of the HTMl) modifying HTML can be quickly and efficiently - <I>even when not using DOM
     * Tree like data-structures.</I>
     * 
     * @param entityAsEnum If it is necessary to ask whether this "Reference HTML SubSection"
     * is an HTML sub-section for a Method, Field or Constructor etc...  Rather than using the
     * {@code getClass()} on field {@code entity}, you may use this Enumeration, instead.
     * 
     * @param html The HTML of a Java Doc detail-section
     * 
     * @throws IllegalArgumentException If the parameter {@code 'entity'} and
     * {@code 'entityAsEnum'} do not reference the same type of detail-section.  This is a quick
     * check that isn't costly.  In the HTML file processors of this package, this won't ever be
     * thrown.
     */

    // The ReflHTML-Constructor: is only called from JavaDocHTMLFile
    // USES: Messager.assertFailHTML() (JavaDocHTMLParseException)

    ReflHTML(
            ENTITY              entity,
            DotPair             location,
            Vector<HTMLNode>    html,
            Entity              entityAsEnum,
            String              htmlID,
            String              srcAsHTMLFileURL
        )
    {
        this.entity         = entity;
        this.location       = location;
        this.entityAsEnum   = entityAsEnum;
        this.htmlID         = htmlID;

        // This will never happen.  ReflHTML's are constructed properly in JavaDocHTMLFile.
        // This switch statement is practically-free, so, this prevents possible errors later on.

        switch (entityAsEnum)
        {
            case METHOD:            if (! (entity instanceof Method))
                                        throw ENTITY_MATCH(entity, entityAsEnum);
                                    break;

            case FIELD:             if (! (entity instanceof Field))
                                        throw ENTITY_MATCH(entity, entityAsEnum);
                                    break;

            case CONSTRUCTOR:       if (! (entity instanceof Constructor))
                                        throw ENTITY_MATCH(entity, entityAsEnum);
                                    break;

            case ENUM_CONSTANT:     if (! (entity instanceof EnumConstant))
                                        throw ENTITY_MATCH(entity, entityAsEnum);
                                    break;

            case ANNOTATION_ELEM:   if (! (entity instanceof AnnotationElem))
                                        throw ENTITY_MATCH(entity, entityAsEnum);
                                    break;
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // This is used over and over again, in every Messager.assertFailHTML
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final String sig = this.entity.signature; // Makes for easier typing


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Partialize, Maximize & Minimize Buttons: "Wrapper <DIV>'s" location/placement
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        this.endingLI = TagNodeFind.last(html, location.start, location.end, TC.ClosingTags, "LI");

        if (this.endingLI == -1) Messager.assertFailHTML
            ("There was no closing HTML <LI> Element in this Refl-Detail", sig);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Convenience Method's & Constructor's add a CSS Class to the first <UL>
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        TagNode tn = html.elementAt(location.start).ifTagNode();

        if (tn == null) Messager.assertFailHTML(
            "The first node in this detail is not a <UL>:\n" + detErrMsg(html, location),
            sig
        );

        this.openingUL = new TagNodeIndex(location.start, tn);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // HiLitedDetails needs an insertion-point
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // There is a <DL>...</DL> (HTML Definitions List) that Java Doc uses.  There should be one
        // at the end of the Detail-Section, which is where the HiLited Detail is placed.  If a
        // closing </DL> is not found, then an opening and closing <DL> ... </DL> needs to created
        // and inserted at the end
        // 
        // REMEMBER: 'hiLitedDetail' is wrapped in a <DD>...</DD><DT>...</DT>

        int insertionPoint = TagNodeFind.last
            (html, location.start, location.end, TC.ClosingTags, "dl");

        this.needToAddOpenCloseDLsForHiLitedDetails = insertionPoint == -1;

        // If a </DL> wasn't found, a new <DL> (Definition List), needs to be built.  Also a new
        // insertion point is needed.  The details section ends with a closing '</LI>' element,
        // which is where to insert the new <DL>...</DL>
        //
        // NOTE: **FIELDS** are the Detail-Elements that usually do not have a <DL>...</DL>, because
        //       there aren't many <SPAN> Label-Banners present in a field

        if (insertionPoint == -1)
        {
            insertionPoint = TagNodeFind.last
                (html, location.start, location.end, TC.ClosingTags, "li");

            if (insertionPoint == -1) Messager.assertFailHTML
                ("There is a detail with no ending </DL> and no ending </LI>", sig);
        }

        this.hiLitedCode = Replaceable.empty(insertionPoint);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Mandatory HTML Fields: name & signature
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // One precaution is that this <H4> must be among the first 8 nodes in the sub-page,
        // Except for Annotation Elements, which have several HTML Nodes at the start of the detail

        this.name = TagNodePeekInclusive.first(
            html, location.start,
            ((this.entityAsEnum == Entity.ANNOTATION_ELEM) ? location.end : (location.start + 8)),
            "h4"
        );

        if (this.name == null)

            Messager.assertFailHTML(
                "There was no name <H4> found in the detail:\n" +
                // StrIndent.indent(Util.pageToString(html), 4),
                detErrMsg(html, location),
                sig
            );

        int sPos = this.name.location.end + 1;

        // Here, it is required that the <PRE> have a class that has the word "Signature"
        // Unfortunately, javadoc doesn't always insert the class...

        this.signature = TagNodePeekInclusive.first(html, sPos, location.end, "pre");

        if (this.signature == null)

            Messager.assertFailHTML(
                "There was no signature <PRE> found in the detail:\n" +
                // StrIndent.indent(Util.pageToString(html), 4),
                detErrMsg(html, location),
                sig
            );


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // UPDATE "/src-html/" URL FOR INNER-CLASSES
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // This may seem **TOTALLY AND COMPLETELY** out of place, but this minor clean-up is going
        // to be done, **RIGHT HERE**, in the Refl...
        //
        // When applied to the Java-HTML JAR, this saves 100 MB of Java-Doc Files...
        //
        // NOTE: The check for whether this is done is done inside the calling class - which 
        //       happens to be JavaDocHTMLFIle.  If this URL-HREF replacement DOES-NOT need to
        //       happen, then the URL 'srcAsHTMLFileURL' will be null.
        //
        // If this "ReflHTML" instance is a emmber of a Nested-Type / Inner-Type, then and only
        // then should this be needed...

        if (srcAsHTMLFileURL != null)
        {
            TagNodeIndex tni = InnerTagPeek.first
                (signature.html, "a", "href", href -> href.contains("/src-html/"));

            if (tni == null) Messager.assertFailGeneralPurpose(
                "Could not locate the link to the /src-html/ file, but srcAsHTMLFileURL " +
                '[' + srcAsHTMLFileURL + "] exists",
                sig
            );

            String href = srcAsHTMLFileURL;

            if (entity.location != null) href += "#line." + ((entity.location.jdcStartLine == -1)
                ? entity.location.signatureStartLine
                : entity.location.jdcStartLine);

            signature.html.setElementAt(tni.n.setAV("HREF", href, SD.SingleQuotes), tni.index);
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Description HTML Field, it is not Mandatory
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        sPos = this.signature.location.end + 1;

        SubSection subSection = InnerTagPeekInclusive.first
            (html, sPos, location.end, "div", "class", TextComparitor.C, "block");

        if (subSection != null)
        {
            // JavaDoc Inserts a cute little note whenever a method overrides another method
            // stating that the description has been copied from the overriden method.  Afterwards,
            // **A SECOND DIV IS INSERTED** that contains the text of the description from the
            // method that is being overriden.  This only occurs when the method that is doing the
            // overriding (the method from 'this' ReflHTML) - does not contain any description-text
            //
            // When this happens, just insert **BOTH** <DIV> Elements into the Vector

            /*
            // Somewhat inefficient.  This code is executed 10,000 times - for each and
            // every detail element on each and every JavaDoc Page

            int copiedPos = InnerTagFind.first(
                html, subSection.location.start + 1, subSection.location.end,
                "span", "class", TextComparitor.C, "descfrmTypeLabel"
            );
            */
            String classStr;

            if (
                    // Much faster short-circuit boolean-evaluation
                    ((tn = html.elementAt(subSection.location.start + 1).ifTagNode()) != null)
                &&  tn.tok.equals("span")
                &&  ((classStr = tn.AV("class")) != null)
                &&  classStr.equals("descfrmTypeLabel")
            )
            // if (copiedPos != -1)
            {
                // This part of the loop is almost never executed (unless the class) was
                // actually found.  Out of 10,000 Details there are probably 20 methods like
                // this.

                this.descFromTypeLabel = true;

                // Make sure to skip the text</SPAN></DIV>
                SubSection ssCopied = InnerTagPeekInclusive.first(
                    html, subSection.location.start + 4, location.end,
                    "div", "class", TextComparitor.C, "block"
                );

                if (ssCopied == null) Messager.assertFailHTML(
                    "A <SPAN CLASS=descfrmTypeLabel> Label was Found, but there was not a " +
                    "second <DIV CLASS=\"block\">:\n" +
                    detErrMsg(html, location),
                    sig
                );

                /*
                System.out.println(
                    "\n=====================================================" +
                    "\ncopiedPos: "     + copiedPos +
                    "\nlocation.end: "  + location.end +
                    "\n\nSubSection: "  + subSection.toString() +
                    "\nLocation: "      + subSection.location.toString() +
                    "\n\nssCopied: "    + ssCopied.toString() +
                    "\nLocation: "      + ssCopied.location.toString() +
                    "\n=====================================================" 
                );
                */

                subSection = new SubSection(
                    new DotPair(subSection.location.start, ssCopied.location.end),
                    Util.cloneRange(html, subSection.location.start, ssCopied.location.end + 1)
                );
            }
            else this.descFromTypeLabel = false;

            // For whichever of the two cases that has occured, just insert the HTML into the table
            sPos = subSection.location.end + 1;
            subSections.put(DESCRIPTION_KEY, subSection);
        }
        else this.descFromTypeLabel = false;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Annotations Have this little "Default" thing
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // <dt><SPAN CLASS=C21>Default:</SPAN></dt>
        // <dd>{}</dd>

        // NOTE: This is 'temp' variable that is reused over and over in this method
        DotPair dp = TagNodeFindInclusive.first(html, sPos, -1, "dl");

        if (dp != null)
        {
            int defPos = TextNodeFind.first
                (html, dp.start, dp.end, s -> s.equals("Default:"));

            if (defPos != -1)
            {
                dp = Surrounding.first(html, defPos, "dt");
                subSections.put
                    (ANNOTATION_DEFAULT_KEY, new SubSection(dp, Util.cloneRange(html, dp)));
            }
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // <DL> Labels: <DT><SPAN CLASS="someLabel">Some Label</SPAN></DT><DD>...</DD> Fields.  
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final String[] spanClasses = {
            "paramLabel", "returnLabel", "seeLabel", "throwsLabel", "overrideSpecifyLabel",
            "simpleTagLabel"
        };

        int[] spans = InnerTagFind.all
            (html, sPos, location.end, "span", "class", TextComparitor.EQ, spanClasses);

        for (int spanPos : spans)
        {
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Build the 'location' (DotPair) of the HTML that "surrounds" the SPAN (DT/DD's)
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            //
            //  <DT><SPAN CLASS='someLabel'>Some Label</SPAN></DT>
            //  <DD> Some User Code Information </DD>
            //  <DD> For Parameters & Throws, there are multiple DD's </DD>

            // First ensure that there is an opening <DT> directly befofre the <SPAN CLASS=Label>
            // The 'tn' was declared at the top of this method, it is a re-usable temp variable

            tn = html.elementAt(spanPos - 1).openTag();

            if ((tn == null) || (! tn.tok.equals("dt"))) Messager.assertFailHTML(
                "There is a " + BGREEN + html.elementAt(spanPos).str + RESET + "\n" +
                "Not preceeded by an opening " + BGREEN + "<DT>" + RESET + "\n" +
                "Instead there is a " + BGREEN + html.elementAt(spanPos - 1).str +
                RESET,
                sig
            );

            // Passed the above requirement/test, so this is the start of the SubSection
            int locStart = spanPos - 1;

            // The particular section we are observing ends as soon as another section begins, or
            // we encounter a </DL> element.  a <DT> element implies a new section is starting, and
            // a </DL> element means all of the labels have been handled
            //
            // Find the ending </DD> of the last <DD>...</DD> pair

            int locEnd = -1, len = html.size();

            // Find either a closing </DL> (meaning no more <SPAN CLASS='someLabel'> elements),
            // or an oopening <DT> - which is starting a new SPAN-LABEL

            INNER_FOR_LOOP:
            for (int i = (spanPos + 1); i < len; i++)

                if ((tn = html.elementAt(i).ifTagNode()) != null)

                    if (    (tn.tok.equals("dl") &&  tn.isClosing)      // Closing </DL>
                        ||  (tn.tok.equals("dt") &&  (! tn.isClosing))  // Opening <DT>
                    )
                    {
                        locEnd = i;
                        break INNER_FOR_LOOP;
                    }

            // I still haven't found what I'm looking for...
            // There was not closing </DL>, nor an new, opening <DT>

            if (locEnd == -1) Messager.assertFailHTML(
                "There is a " + BGREEN + html.elementAt(spanPos).str + RESET + ' ' +
                "which isn't terminated by a new <DT> or a closing </DL>",
                sig
            );

            // Back up through any TextNodes - which, usually, is just a '\n' newline character.
            while ((tn = html.elementAt(--locEnd).ifTagNode()) == null);

            // Finally, make sure there is a closing </DD> which is the end of the 
            // <DT>...</DT><DD>...</DD> Combination.  Remember, there may only be one <DT>..<DT>
            // (with a <SPAN CLASS='someLabel'), but that <DT> may be followed by more than one
            // <DD>...</DD> list.  Parameters and Throws Labels have severl <DD> pairs!

            if ((! tn.isClosing) || (! tn.tok.equals("dd"))) Messager.assertFailHTML(
                "There is a " + BGREEN + html.elementAt(spanPos).str + RESET + ' ' +
                "which is missing a <DD> definition",
                sig
            );


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Finished Searching. Build the "SubSection" instance, and start the switch-statement
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            // 'dp' is a temp variable that was first used earlier
            dp = new DotPair(locStart, locEnd);

            // A 'SubSection' includes both the location, and the HTML put together in a
            // wrapper-class (SubSection is wrapper for Vector<HTMLNode> & DotPair)

            SubSection section = new SubSection(dp, Util.cloneRange(html, dp));

            // Temporary Variables for the switch statement
            String      kind;
            TextNode    txn;

            // In case you missed it, the six labels that were searched are:
            // "paramLabel", "returnLabel", "seeLabel", "throwsLabel", "overrideSpecifyLabel",
            // and "simpleTagLabel"

            CASE:
            switch (html.elementAt(spanPos).asTagNode().AV("class"))
            {
                case "returnLabel" :

                    if (subSections.containsKey(RETURNS_KEY))
                        Messager.assertFailHTML("There is a second 'returnLabel", sig);
                    else
                        subSections.put(RETURNS_KEY, section);

                    break CASE;

                case "seeLabel" :

                    if (subSections.containsKey(SEE_ALSO_KEY))
                        Messager.assertFailHTML("There is a second 'seeLabel", sig);
                    else
                        subSections.put(SEE_ALSO_KEY, section);

                    break CASE;

                case "throwsLabel" :

                    if (subSections.containsKey(THROWS_KEY))
                        Messager.assertFailHTML("There is a second 'throwsLabel", sig);
                    else
                        subSections.put(THROWS_KEY, section);

                    break CASE;


                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                // There can be two kinds of "paramLabel" 
                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                //
                // One is used for regular-parameters, which is the most common, while the second
                // is for "Type-Parameters" (rare, but useful)

                case "paramLabel" :

                    if ((txn = html.elementAt(spanPos + 1).ifTextNode()) == null)
                        Messager.assertFailHTML
                            ("There is a 'paramLabel' not followed by a TextNode", sig);

                    kind = txn.str;

                    if (kind.equals("Parameters:"))
                    {
                        if (subSections.containsKey(PARAMETERS_KEY))
                            Messager.assertFailHTML
                                ("There is a second 'paramLabel' for parameters", sig);
                        else
                            subSections.put(PARAMETERS_KEY, section);
                    }
                    else if (kind.equals("Type Parameters:"))
                    {
                        if (subSections.containsKey(TYPE_PARAMETERS_KEY))
                            Messager.assertFailHTML
                                ("There is a second 'paramLabel' for type-parameters", sig);
                        else
                            subSections.put(TYPE_PARAMETERS_KEY, section);
                    }

                    else Messager.assertFailHTML(
                        "Unknown Parameter Label Found:\n" +
                        StrIndent.indent(Util.pageToString(section.html), 4),
                        sig
                    );

                    break CASE;


                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                // There can be two kinds of "overrideSpecifyLabel"
                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                // (surprise, "override" and "specified by")

                case "overrideSpecifyLabel" :

                    if ((txn = html.elementAt(spanPos + 1).ifTextNode()) == null)
                        Messager.assertFailHTML
                            ("There is a 'overrideSpecifyLabel' not followed by a TextNode", sig);

                    kind = txn.str;

                    if (kind.equals("Specified by:"))
                    {
                        if (subSections.containsKey(SPECIFIED_BY_KEY))
                        {
                            SubSection first = subSections.get(SPECIFIED_BY_KEY);

                            if ((dp.start - first.location.end) > 2)

                                Messager.assertFailHTML(
                                    "There is a second 'overrideSpecifyLabel' for 'Specified " +
                                    "by:', and unfortunately it is not contiguous with the " +
                                    "previous one.",
                                    sig
                                );

                            dp = new DotPair(first.location.start, dp.end);
                            section = new SubSection(dp, Util.cloneRange(html, dp));
                        }

                        subSections.put(SPECIFIED_BY_KEY, section);
                    }

                    else if (kind.equals("Overrides:"))
                    {
                        if (subSections.containsKey(OVERRIDES_KEY))
                            Messager.assertFailHTML
                                ("There is a second 'Overrides' label", sig);
                        else
                            subSections.put(OVERRIDES_KEY, section);
                    }

                    else Messager.assertFailHTML(
                        "Unknown Overrides/Specified-By Label Found:\n" +
                        StrIndent.indent(Util.pageToString(section.html), 4),
                        sig
                    );

                    break CASE;


                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                // There can many kinds of "simpleTagLabel"
                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

                case "simpleTagLabel" :

                    if ((txn = html.elementAt(spanPos + 1).ifTextNode()) == null)
                        Messager.assertFailHTML
                            ("There is a 'simpleTagLabel' not followed by a TextNode", sig);

                    kind = txn.str;

                    if (kind.equals("Since:"))
                    {
                        if (subSections.containsKey(SINCE_KEY))
                            Messager.assertFailHTML
                                ("There is a second 'simpleTagLabel' for 'since'", sig);
                        else
                            subSections.put(SINCE_KEY, section);
                    }
                    else
                    {
                        // 99% of the classes in JavaHTML do not have these, no need to build
                        // this array-list at construction-time, only build if used

                        if (miscSimpleTagLabels == null)
                            miscSimpleTagLabels = new ArrayList<>();

                        miscSimpleTagLabels.add
                            (new TagNodeIndex(spanPos, html.elementAt(spanPos).asTagNode()));
                    }
            }
        }
    }

    // This should never happend
    private IllegalArgumentException ENTITY_MATCH(Declaration entity, Entity entityAsEnum)
    {
        return new IllegalArgumentException(
            "The 'Entity' passed to parameter 'entityAsEnum' [" + entityAsEnum + "], does " +
            "not match the type of parameter 'entity' [" + entity.getClass().getSimpleName() +
            "].  They must be the same."
        );
    }

    /**
     * Clone Constructor.
     * @param other Another instance of {@code ReflHTML}
     * @see #clone()
     */
    @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;

        // Cannot 'clone' the other.subSections, it assigned a value at initialization (at the top
        // where it is declared). Use 'TreeMap.putAll' instead

        this.subSections.putAll(other.subSections);

        // This is not inialized unless there are actually 'simpleTagLabels' in the detail
        this.miscSimpleTagLabels = (other.miscSimpleTagLabels != null)
            ? ((ArrayList<TagNodeIndex>) other.miscSimpleTagLabels.clone())
            : null;
    }


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

    /**
     * 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(DESCRIPTION_KEY)) != null)        replaceables.add(ss);
        if ((ss = subSections.get(ANNOTATION_DEFAULT_KEY)) != null) replaceables.add(ss);
        if ((ss = subSections.get(RETURNS_KEY)) != null)            replaceables.add(ss);
        if ((ss = subSections.get(SEE_ALSO_KEY)) != null)           replaceables.add(ss);
        if ((ss = subSections.get(THROWS_KEY)) != null)             replaceables.add(ss);
        if ((ss = subSections.get(PARAMETERS_KEY)) != null)         replaceables.add(ss);
        if ((ss = subSections.get(TYPE_PARAMETERS_KEY)) != null)    replaceables.add(ss);
        if ((ss = subSections.get(OVERRIDES_KEY)) != null)          replaceables.add(ss);
        if ((ss = subSections.get(SPECIFIED_BY_KEY)) != null)       replaceables.add(ss);
        if ((ss = subSections.get(AUTHOR_KEY)) != null)             replaceables.add(ss);
        if ((ss = subSections.get(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; }

        // private ArrayList<TagNodeIndex> miscSimpleTagLabels = null;
        if (miscSimpleTagLabels != null)
        {
            miscSimpleTagLabels.clear();
            miscSimpleTagLabels = null;
        }
    }
}