package Torello.JavaDoc;

import java.util.Vector; // used once in a static initializer for "Replaceable"

import Torello.Java.*;

import static Torello.Java.C.*;

// These are used in Java-Doc Link Examples only, not in source-code.
import Torello.Java.ParallelArrayException;
import Torello.HTML.Replaceable;

/**
 * An abstract helper class for user-provided {@code SummarySorter.class} files for sorting the
 * Table of Contents inside the Field / Method / Constructor Summaries inside a Java Doc Web Page.
 */
public abstract class SummarySorterHelper
{
    // ********************************************************************************************
    // String Constants
    // ********************************************************************************************

    /**
     * Label for methods inherited from class {@code Object}
     * 
     * <BR /><BR />Checker Method {@link #OBJECT_M(Method)} matches methods named:
     * {@code "hashCode", "toString", "equals"}
     * 
     * @see #OBJECT_M(Method)
     */
    protected static final String OBJECT_M =
        "<B CLASS=STBLabel>Methods:</B> class java.lang.Object";

    /**
     * Label for methods inherited from class {@code Combarable}
     * 
     * <BR /><BR />Checker Method {@link #COMPARABLE_M(Method)} matches methods named:
     * {@code "compareTo"}
     * 
     * @see #COMPARABLE_M(Method)
     */
    protected static final String COMPARABLE_M =
        "<B CLASS=STBLabel>Methods:</B> interface java.lang.Comparable";

    /**
     * Label for methods inherited from class {@code CharSequence}
     * 
     * <BR /><BR />Checker Method {@link #CHARSEQUENCE_M(Method)} matches method named:
     * {@code "toString", "subSequence", "charAt", "length"}
     * 
     * @see #CHARSEQUENCE_M(Method)
     */
    protected static final String CHARSEQUENCE_M =
        "<B CLASS=STBLabel>Methods:</B> interface java.lang.CharSequence";

    /**
     * Label for methods inherited from class {@code Cloneable}
     * 
     * <BR /><BR />Checker Method {@link #CLONEABLE_M(Method)} matches method named:
     * {@code "clone"}
     * 
     * @see #CLONEABLE_M(Method)
     */
    protected static final String CLONEABLE_M =
        "<B CLASS=STBLabel>Methods:</B> interface java.lang.Cloneable";

    /**
     * Label for methods inherited from class {@code Iterable}
     */
    protected static final String ITERABLE_M =
        "<B CLASS=STBLabel>Methods:</B> interface java.lang.Iterable";

    /**
     * Label for methods inherited from class {@code Iterator}
     * 
     * <BR /><BR />Checker Method {@link #CLONEABLE_M(Method)} matches method named:
     * {@code "next", "hasNext", "remove", "forEachRemaining"}
     * 
     * @see #ITERATOR_M(Method)
     */
    protected static final String ITERATOR_M =
        "<B CLASS=STBLabel>Methods:</B> interface java.lang.Iterator";

    /**
     * Label for methods inherited from interface {@code Appendable}
     * 
     * <BR /><BR />Checker Method {@link #APPENDABLE_M(Method)} matches method named:
     * {@code "append"}
     * 
     * @see #APPENDABLE_M(Method)
     */
    protected static final String APPENDABLE_M =
        "<B CLASS=STBLabel>Methods:</B> interface java.lang.Appendable";

    /**
     * Label for methods in a {@code FunctionalInterface}
     * @see #fInterface$M$Sections
     * @see #fInterface$M$Sorter(String, Method)
     */
    protected static final String FINTERFACE_M = "@FunctionalInterface (Lambda) Method";

    /**
     * Label for methods inherited from class {@code java.io.Closeable}
     * 
     * <BR /><BR />Checker Method {@link #CLOSEABLE_M(Method)} matches method named:
     * {@code "close"}
     * 
     * @see #CLOSEABLE_M(Method)
     */
    protected static final String CLOSEABLE_M =
        "<B CLASS=STBLabel>Methods:</B> interface java.io.Closeable";

    /**
     * Label for methods inherited from class {@code java.io.Flushable}
     * 
     * <BR /><BR />Checker Method {@link #FLUSHABLE_M(Method)} matches method named:
     * {@code "flush"}
     * 
     * @see #FLUSHABLE_M(Method)
     */
    protected static final String FLUSHABLE_M =
        "<B CLASS=STBLabel>Methods:</B> interface java.io.Flushable";

    /**
     * Label for methods inherited from class {@code java.io.Writer}
     * 
     * <BR /><BR />Checker Method {@link #WRITER_M(Method)} matches method named:
     * {@code "write", "close", "flush", "append"}
     * 
     * @see #WRITER_M(Method)
     */
    protected static final String WRITER_M =
        "<B CLASS=STBLabel>Methods:</B> class java.io.Writer";

    /**
     * Label for methods inherited from class {@code java.io.PrintStream}
     * 
     * <BR /><BR />Checker Method {@link #PRINTSTREAM_M(Method)} matches method named:
     * {@code "print", "println", "printf", "format"}
     * 
     * @see #PRINTSTREAM_M(Method)
     */
    protected static final String PRINTSTREAM_M =
        "<B CLASS=STBLabel>Methods:</B> class java.io.PrintStream";

    /**
     * Label for methods inherited from class {@link Replaceable}
     * 
     * <BR /><BR />Checker Method {@link #REPLACEABLE_M(Method)} matches method-names of all the
     * methods currently listed in {@link Replaceable}.  Review the methods listed in that class to
     * review those method-names.
     * 
     * @see #REPLACEABLE_M(Method)
     */
    protected static final String REPLACEABLE_M =
        "<B CLASS=STBLabel>Methods:</B> interface Torello.HTML.Replaceable";


    // ********************************************************************************************
    // Throw UnreachableError, faster typing.
    // ********************************************************************************************

    /**
     * Label for fields inherited from interface {@code java.io.Serializable}
     */
    protected static final String SERIALIZABLE_F = "Serializable ID";

    /**
     * Label for fields that are <B>{@code static}</B> singleton instances of a class.
     */
    protected static final String SINGLETON_F = "Singleton Instance";


    // ********************************************************************************************
    // Throw UnreachableError, faster typing.
    // ********************************************************************************************

    /**
     * When writing a sorter method, it is often a good practice to throw the
     * {@link UnreachableError} on the very last line of the sorter's code to ensure that every 
     * entity being sorted has been properly placed into one of the Table Of Contents Section
     * Title Categories.  This way, you ever add a new method / field / entity to the class, but
     * forget to categorize it under a specific Section Title, an {@code UnreachableError} will
     * instantly throw, reminding you to sort your newly created method, field, or other entity.
     * 
     * <BR /><BR />The other primary reason for writing this method is to shorten the amount of
     * typing that you need to do.  The below example sorts all of the methods in a class into a 
     * Method Summary Section (on the JavaDoc Generated HTML Page) which has three Sections 
     * each with their own Title.  The Titles, themselves, are listed in the {@code String[]}
     * array.  The sorting method for placing method's into one of these three Section Categories
     * is directly beneath the listed categories.
     * 
     * <BR /><BR />Notice in this example, the last line of code invokes this method
     * ({@code "UE(Declaration d)"})
     * 
     * <DIV CLASS=EXAMPLE>{@code
     * public static final String[] MyClass$Method$Sections =
     * {  "Main Method", "Printing Methods", "File Saving Methods" };
     *
     * public static int MyClass$Method$Sorter(Method m)
     * {
     *     if (m.name.equals("someName1"))          return 0;
     *     if (eqOR(m, "someName2", "someName3"))   return 1;
     *     if (swOR(m, "someName3"))                return 2;
     * 
     *     throw UE(m); // <== RIGHT-HERE, if the method is not categorized, it would have to be
     *                  // becuase you have added another method into the class.  This will halt
     *                  // your build process until you update your Method-Sorter Function.
     * }
     * }</DIV>
     * 
     * @param d Any Declaration ({@link Method}, {@link Field}, {@link Constructor}, etc...). This
     * is actually just supposed to be the entity that was passed to your sorter.  If a call to
     * {@code 'UE(d)'} is made one the last line of your sorter-function, the {@code 'toString'}
     * method for the declaration will be printed to the terminal.
     * 
     * @return This returns a newly created instance of {@link UnreachableError}, which may be
     * immediately thrown.  Remember, the general idea behind this method is to shorten the amount
     * of typing you (the user / programmer) has to do.  When writing Class "Entity Sorters", you
     * will find yourself typing many short sorting methods, like in the example above, over and
     * over again.
     */
    protected static UnreachableError UE(Declaration d)
    {
        System.out.println(
            '\n' + // Messager.Quiet && Messager.Silent needs this
            BRED + "Un Classified " + d.getClass().getSimpleName() + " Found:\n" + RESET +
            d.toString(PF.BODY | PF.JOW_ALSO | PF.UNIX_COLORS)
        );

        return new UnreachableError();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Faster Typing, **ONLY COMPARES NAME**
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SSH_ABBREV DATA-METHNAME=equalsXOR>
     * @param d Any {@link Method}, {@link Field}, {@link Constructor} etc.
     * @param sArr <EMBED CLASS='external-html' DATA-FILE-ID=SSH_SARRP DATA-STROP='Equals'>
     * @return {@code TRUE} - if and only if {@code d.name}
     * <B STYLE='color:red;'>{@code Equals}</B> one of the elements of {@code 'sArr'}
     * @see StrCmpr#equalsXOR(String, String[])
     */
    protected static boolean eqOR(Declaration d, String... sArr)
    { return StrCmpr.equalsXOR(d.name, sArr); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SSH_ABBREV DATA-METHNAME=containsOR>
     * @param d Any {@link Method}, {@link Field}, {@link Constructor} etc.
     * @param sArr <EMBED CLASS='external-html' DATA-FILE-ID=SSH_SARRP DATA-STROP='Contains'>
     * @return {@code TRUE} - if and only if {@code d.name}
     * <B STYLE='color:red;'>{@code Contains}</B> one of the elements of {@code 'sArr'}
     * @see StrCmpr#containsOR(String, String[])
     */
    protected static boolean cOR(Declaration d, String... sArr)
    { return StrCmpr.containsOR(d.name, sArr); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SSH_ABBREV DATA-METHNAME=startsWithXOR>
     * @param d Any {@link Method}, {@link Field}, {@link Constructor} etc.
     * @param sArr <EMBED CLASS='external-html' DATA-FILE-ID=SSH_SARRP DATA-STROP='Starts-With'>
     * @return {@code TRUE} - if and only if {@code d.name}
     * <B STYLE='color:red;'>{@code Starts-With}</B> one of the elements of {@code 'sArr'}
     * @see StrCmpr#startsWithXOR(String, String[])
     */
    protected static boolean swOR(Declaration d, String... sArr)
    { return StrCmpr.startsWithXOR(d.name, sArr); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SSH_ABBREV DATA-METHNAME=endsWithXOR>
     * @param d Any {@link Method}, {@link Field}, {@link Constructor} etc.
     * @param sArr <EMBED CLASS='external-html' DATA-FILE-ID=SSH_SARRP DATA-STROP='Ends-With'>
     * @return {@code TRUE} - if and only if {@code d.name}
     * <B STYLE='color:red;'>{@code Ends-With}</B> one of the elements of {@code 'sArr'}
     * @see StrCmpr#endsWithXOR(String, String[])
     */
    protected static boolean ewOR(Declaration d, String... sArr)
    { return StrCmpr.endsWithXOR(d.name, sArr); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Default Method Name Sorters
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Identifies whether or not a particular method should be placed under the <I>Method Summary
     * Section Title</I> for methods which implement or extend {@code java.lang.Object}.
     * <EMBED CLASS=defs DATA-Type=Object>
     * @param m <EMBED CLASS='external-html' DATA-FILE-ID=SSH_METHP>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SSH_RETM>
     * @see #OBJECT_M
     * @see StrCmpr#equalsXOR(String, String[])
     */
    protected static boolean OBJECT_M(Method m)
    { return StrCmpr.equalsXOR(m.name, "hashCode", "toString", "equals"); }

    /**
     * Identifies whether or not a particular method should be placed under the <I>Method Summary
     * Section Title</I> for methods which implement or extend {@code java.util.Iterator}.
     * <EMBED CLASS=defs DATA-Type=Iterator>
     * @param m <EMBED CLASS='external-html' DATA-FILE-ID=SSH_METHP>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SSH_RETM>
     * @see #ITERATOR_M
     * @see StrCmpr#equalsXOR(String, String[])
     */
    protected static boolean ITERATOR_M(Method m)
    { return StrCmpr.equalsXOR(m.name, "next", "hasNext", "remove", "forEachRemaining"); }

    /**
     * Identifies whether or not a particular method should be placed under the <I>Method Summary
     * Section Title</I> for methods which implement or extend {@code java.lang.Cloneable}.
     * <EMBED CLASS=defs DATA-Type=Cloneable>
     * @param m <EMBED CLASS='external-html' DATA-FILE-ID=SSH_METHP>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SSH_RETM>
     * @see #CLONEABLE_M
     */
    protected static boolean CLONEABLE_M(Method m)
    { return m.name.equals("clone"); }

    /**
     * Identifies whether or not a particular method should be placed under the <I>Method Summary
     * Section Title</I> for methods which implement or extend {@code java.lang.Appendable}.
     * <EMBED CLASS=defs DATA-Type=Appendable>
     * @param m <EMBED CLASS='external-html' DATA-FILE-ID=SSH_METHP>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SSH_RETM>
     * @see #APPENDABLE_M
     */
    protected static boolean APPENDABLE_M(Method m)
    { return m.name.equals("append"); }

    /**
     * Identifies whether or not a particular method should be placed under the <I>Method Summary
     * Section Title</I> for methods which implement or extend {@code java.lang.Comparable}.
     * <EMBED CLASS=defs DATA-Type=Comparable>
     * @param m <EMBED CLASS='external-html' DATA-FILE-ID=SSH_METHP>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SSH_RETM>
     * @see #COMPARABLE_M
     */
    protected static boolean COMPARABLE_M(Method m)
    { return m.name.equals("compareTo"); }

    /**
     * Identifies whether or not a particular method should be placed under the <I>Method Summary
     * Section Title</I> for methods which implement or extend {@code java.lang.CharSequence}.
     * <EMBED CLASS=defs DATA-Type=CharSequence>
     * @param m <EMBED CLASS='external-html' DATA-FILE-ID=SSH_METHP>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SSH_RETM>
     * @see #CHARSEQUENCE_M
     * @see StrCmpr#equalsXOR(String, String[])
     */
    protected static boolean CHARSEQUENCE_M(Method m)
    { return StrCmpr.equalsXOR(m.name, "toString", "subSequence", "charAt", "length"); }

    /**
     * Identifies whether or not a particular method should be placed under the <I>Method Summary
     * Section Title</I> for methods which implement or extend {@code java.io.Closeable}.
     * <EMBED CLASS=defs DATA-Type=Closeable>
     * @param m <EMBED CLASS='external-html' DATA-FILE-ID=SSH_METHP>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SSH_RETM>
     * @see #CLOSEABLE_M
     */
    protected static boolean CLOSEABLE_M(Method m)
    { return m.name.equals("close") && m.returnType.equals("void"); }

    /**
     * Identifies whether or not a particular method should be placed under the <I>Method Summary
     * Section Title</I> for methods which implement or extend {@code java.io.Flushable}.
     * <EMBED CLASS=defs DATA-Type=Flushable>
     * @param m <EMBED CLASS='external-html' DATA-FILE-ID=SSH_METHP>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SSH_RETM>
     * @see #FLUSHABLE_M
     */
    protected static boolean FLUSHABLE_M(Method m)
    { return m.name.equals("flush") && m.returnType.equals("void"); }

    /**
     * Identifies whether or not a particular method should be placed under the <I>Method Summary
     * Section Title</I> for methods which implement or extend {@code java.io.Writer}.
     * <EMBED CLASS=defs DATA-Type=Writer>
     * @param m <EMBED CLASS='external-html' DATA-FILE-ID=SSH_METHP>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SSH_RETM>
     * @see #WRITER_M
     * @see StrCmpr#equalsXOR(String, String[])
     */
    protected static boolean WRITER_M(Method m)
    { return StrCmpr.equalsXOR(m.name, "write", "close", "flush", "append"); }

    /**
     * Identifies whether or not a particular method should be placed under the <I>Method Summary
     * Section Title</I> for methods which implement or extend {@code java.io.PrintStream}.
     * <EMBED CLASS=defs DATA-Type=PrintStream>
     * @param m <EMBED CLASS='external-html' DATA-FILE-ID=SSH_METHP>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SSH_RETM>
     * @see #PRINTSTREAM_M
     * @see StrCmpr#equalsXOR(String, String[])
     */
    protected static boolean PRINTSTREAM_M(Method m)
    { return StrCmpr.equalsXOR(m.name, "print", "println", "printf", "format"); }

    private static final Vector<String> REPLACEABLE_METHODS;

    static
    {
        java.lang.reflect.Method[] mArr = Replaceable.class.getMethods();
        REPLACEABLE_METHODS = new Vector<>(mArr.length);
        for (int i=0; i < mArr.length; i++) REPLACEABLE_METHODS.add(mArr[i].getName());
    }

    /**
     * Identifies whether or not a particular method should be placed under the <I>Method Summary
     * Section Title</I> for methods which implement or extend {@link Replaceable}.
     * <EMBED CLASS=defs DATA-Type=Replaceable>
     * @param m <EMBED CLASS='external-html' DATA-FILE-ID=SSH_METHP>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SSH_RETM>
     * @see #REPLACEABLE_M
     */
    protected static boolean REPLACEABLE_M(Method m)
    { return REPLACEABLE_METHODS.contains(m.name); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Default Field Name Sorters
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Checks if a {@link Field} is named {@code 'serialVersionUID'}.
     * @see #SERIALIZABLE_F
     */
    protected static boolean SERIALIZABLE_F(Field f)
    { return f.name.equals("serialVersionUID"); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Automatic Sorter & Section-Titles
    // ********************************************************************************************
    // ********************************************************************************************


    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // Field Summary Sort - One Field, "serialVersionUID"
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

    /**
     * A Section-Titles {@code String[]} Array List containing only one category.  The category
     * is for Field Summaries having only one field - <B>{@code 'serialVersionUID'}</B>
     * @see #ONLY_SERIALIZABLE_F(Field)
     */
    protected static String[] ONLY_SERIALIZABLE_F =
    { SERIALIZABLE_F };

    /**
     * A sorter for Field Summaries with only one field - <B>{@code 'serialVersionUID'}</B>
     * @see #ONLY_SERIALIZABLE_F
     * @throws UnreachableError If there are other fields in the class.
     */
    protected static int ONLY_SERIALIZABLE_F(Field f)
    { if (SERIALIZABLE_F(f)) return 0; throw UE(f); }


    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // Exception Sorters and Titles
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

    /**
     * A Section-Titles {@code String[]} Array List containing two categories.  The first merely
     * used for the {@code serialVersionUID}, and the second contains all other fields.  This is
     * intended to be used for sorting {@code Exception} classes that provide "convenience" or
     * "introspection" fields where data about the error that has occured is saved inside the
     * exception.
     * 
     * @see #EXCEPTION_CONVENIENCE_F(Field)
     */
    protected static String[] EXCEPTION_CONVENIENCE_F =
    { SERIALIZABLE_F, "<CODE STYLE='font-size: 108%'>'final'</CODE> Exception Convenience Fields" };

    /**
     * This can be used to sort the {@code Field's} of an exception, provided that they fields
     * obey the convenience-construct.  This sorter will place the {@code 'serialVersionUID'}
     * field into the first category, and all other fields into the second.
     * 
     * <BR /><BR />It is <B STYLE='color: red;'>assumed</B> that the convenience-fields are
     * declared <B>{@code final}</B>.  If a field is not declared {@code 'final'}, it will not be
     * categorized, and an {@code UnreachableError} will throw.
     * 
     * @param f This is the {@link Field} that the Java Doc Upgrader is currently categorizing.
     * 
     * @throws UnreachableError If there are other fields in the class besides the Serial ID, and
     * fields which aren't declared {@code 'final'}
     * 
     * @see #EXCEPTION_CONVENIENCE_F
     */
    protected static int EXCEPTION_CONVENIENCE_F(Field f)
    {
        if (SERIALIZABLE_F(f))      return 0;
        if (f.hasModifier("final")) return 1;
        throw UE(f);
    }

    /**
     * If an {@code Exception} class contains 'checker' methods, then this title-bar 
     * {@code String[]} Array can be used to categorize them.  Note that this array only allows
     * for this lone-category, and does not provide others.  The sorter for this Titles-Bar
     * requires that each method in the class have a name that begins with <B>{@code 'check'}</B>
     * 
     * @see #EXCEPTION_CHECKERS_M(Method)
     */
    protected static String[] EXCEPTION_CHECKERS_M =
    { "<CODE STYLE='font-size: 108%'>'static'</CODE> Exception Check Methods" };

    /**
     * Sorts a Method Summary Section for an {@code Exception} class that contains 'checker'
     * methods.  In Java HTML, {@code 'check'} methods are declared {@code 'static'}, and will
     * test parameter-input for exception cases, <I>and then throw the exception in which those
     * methods reside if there are errors with the input</I>.
     * 
     * <BR /><BR /><B>NOTE:</B> See, for example <B>{@link ParallelArrayException}</B>, which 
     * contains multiple methods of this variety.
     * 
     * @param m This is the {@link Method} that the Java Doc Upgrader is currently categorizing.
     * 
     * @throws UnreachableError If there are methods which aren't declared {@code 'static'}, or
     * there are methods whose name does not begin with {@code "check"}.
     * 
     * @see #EXCEPTION_CHECKERS_M
     */
    protected static int EXCEPTION_CHECKERS_M(Method m)
    {
        if (m.name.startsWith("check") && m.hasModifier("static")) return 0;
        throw UE(m);
    }


    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // Method Summary Sort - The 'enum' *SYNTHETIC* (Auto-Generated) methods: values(), valueOf()
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

    /**
     * First Section-Title / Category for the <B STYLE='color: red;'>Synthetic</B> Enum-Method
     * {@code 'values()'}.  All {@code 'enums'} have a {@code 'values'} method that is
     * auto-generated by the Java Compiler.
     * @see #enum$M$Sections
     * @see #enum2$M$Sections
     */
    protected static final String VALUES_M = "List all Enum Constants";

    /**
     * Second Section-Title / Category for the <B STYLE='color: red;'>Synthetic</B> Enum-Method
     * {@code 'valueOf(String)'}.  All {@code 'enums'} have a {@code 'valueOf'} method that is
     * auto-generated by the Java Compiler.
     * @see #enum$M$Sections
     * @see #enum2$M$Sections
     */
    protected static final String VALUEOF_M = "Convert String to Enum Constant";

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SSH_ENUM_DESC>
     * 
     * <BR /><BR />If you have written additional functions, then you should use
     * {@link #enum2$M$Sections}, because that {@code String[]} Array has an extra Category /
     * Section-Title called "More Methods".
     * 
     * @see #VALUEOF_M
     * @see #VALUES_M
     * @see #enum$M$Sorter
     */
    protected static String[] enum$M$Sections =
    { VALUEOF_M, VALUES_M };

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SSH_ENUM_DESC>
     * 
     * <BR /><BR />If your {@code enum} only has these two synthetic-Java methods, then you should
     * use {@link #enum$M$Sections}.
     * 
     * @see #VALUEOF_M
     * @see #VALUES_M
     * @see #enum2$M$Sorter
     */
    protected static String[] enum2$M$Sections =
    { VALUEOF_M, VALUES_M, "More Methods" };

    /**
     * Sorts an {@code enum's} methods (in the Java Doc 'Method Summary') into the Categories /
     * Section-Titles provided by {@link #enum$M$Sections}.
     * 
     * <BR /><BR /><B>NOTE:</B> If the {@code 'enum'} whose methods you are sorting has other
     * methods besides the ones auto-created by the Java Compiler, you should use the pair
     * {@link #enum2$M$Sections} and {@link #enum2$M$Sorter(Method)}.  This one will throw an
     * {@link UnreachableError} if other methods are received.
     * 
     * @param m This is the {@link Method} that the Java Doc Upgrader is currently categorizing.
     * 
     * @return The category number where this method belongs.
     * 
     * @throws UnreachableError If the {@code 'enum'} to which this Method Summary-Sorter has been
     * applied has methods other than the <B STYLE='color:red;'>Synthetically</B> auto-generated
     * methods {@code 'values'} and {@code 'valueOf'}, then when those methods are received by this
     * sorter, this error will throw.
     * 
     * @see #enum$M$Sections
     */
    protected static int enum$M$Sorter(Method m)
    {
        if (m.name.equals("valueOf"))   return 0;
        if (m.name.equals("values"))    return 1;
        throw UE(m);
    }

    /**
     * Sorts an {@code enum's} methods (in the Java Doc 'Method Summary') into the Categories /
     * Section-Titles provided by {@link #enum2$M$Sections}.
     * 
     * @param m This is the {@link Method} that the Java Doc Upgrader is currently categorizing.
     * 
     * @return The category number where this method belongs.
     * 
     * @see #enum2$M$Sections
     */
    protected static int enum2$M$Sorter(Method m)
    {
        if (m.name.equals("valueOf"))   return 0;
        if (m.name.equals("values"))    return 1;
        return 2;
    }


    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // @FunctionalInterface: interfaces which only have the one abstract-method, and no others
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

    /** Title-Category for methods that are <B>{@code 'static'} Factory</B> Methods. */
    protected static final String STATIC_FACTORY = "Methods: Static Factory-Builder";

    /** Title-Category for composition methods (for instance {@code 'andThen'}) */
    protected static final String DEFAULT_COMP = "Methods: Default Composition & Builder";

    /** {@code Iterator.remove()} Method Title-Category. */
    protected static final String DEF_ITER_REMOVE = 
        "Default Methods: Remove Elements with Iterator.remove()";

    /**
     * A "Section Titles" {@code String[]} Array that contains only one Title/Category.  This
     * category identifies a Functional-Interface's <B STYLE='color:red;'>Lambda-Target</B>
     * method.
     * 
     * @see #FINTERFACE_M
     */
    protected static final String[] fInterface$M$Sections = { FINTERFACE_M };

    /**
     * This can be used to place a functional-interface method under the sectional title
     * for functional-interfaces.  <I>This method will only work on interfaces that have
     * only method (namely: the lambda-target method).</I>
     * 
     * @param functionalIntMethName This is the name of the 'lone method' that is used as a
     * lambda-target of a {@code FunctionalInterface}.
     * 
     * @param m This is the {@link Method} that the Java Doc Upgrader is currently categorizing.
     * 
     * @throws UnreachableError If there are other methods in the class besides the one whose name
     * equals {@code 'functionalIntMethName'}
     */
    protected static int fInterface$M$Sorter(String functionalIntMethName, Method m)
    {
        if (m.name.equals(functionalIntMethName)) return 0;
        throw UE(m);
    }
}