package Torello.HTML.Tools.JavaDoc;

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

import Torello.HTML.NodeSearch.HNLIInclusive;
import Torello.Java.Shell.C;

import java.util.*;

/**
 * <CODE>Convenience - Documentation.</CODE><BR /><BR />
 * <EMBED CLASS="external-html" DATA-FILE-ID="CONVENIENCE">
 */
@Torello.HTML.Tools.JavaDoc.StaticFunctional
public class Convenience
{
    private Convenience() { }

    /**
     * Monitors "Convenience Methods".  Currently, the only modification performed is to remove
     * any "Throws" Sections which may have been automatically inserted because they were
     * "Checked Exceptions."  Warning messages are sent to the log if there is a "See Also,"
     * "Returns" or a "Parameters" section.
     *
     * <BR /><BR /><B>NOTE:</B> The purpose of a "Convenience Method" is to try to keep the
     * JavaDoc Comment to one (at most) two lines, with a link to the "underlying function"
     * that is being invoked.  As long as there is a "link" to that other method, including
     * lists of returns, parameters, and throws clauses becomes very superfluous.
     *
     * @param fileVec Any JavaDoc Generated HTML Web-Page
     * @param log This is the log.  This parameter may be null, and if it is, it will be ignored.
     */
    public static void checkForConvenienceMethods(Vector<HTMLNode> fileVec, StorageWriter log)
    {
        // If there are no methods listed on the page, return immediately.
        if (Details.hasMethodDetails(fileVec) == null) return;

        // Thiis will iterate through each method in the "Method Details Section"
        HNLIInclusive iter = Details.methodDetailsIterator(fileVec);

        while (iter.hasNext())
        {
            // Retrieves the HTML sub-section for the next "Method Description" found inside the
            // JavaDoc Generated Documentation Web-Page
            Vector<HTMLNode> methodDetails = iter.next();

            // This retrieves a pointer to the portion of that sub-section that contains the
            // "description" (a text section)
            DotPair descriptionSection = DetailsPartMethod.description(methodDetails);

            // This utilizes the pointer from the previous step to return any / all HTML found in
            // the description portion for this method as a simple java.lang.String
            String description =    (   (descriptionSection != null) 
                                    &&  (descriptionSection.size() > 0))
                ? Util.textNodesString(methodDetails, descriptionSection).trim()
                : "";

            if (description.startsWith("Convenience Method. "))
            {
                // As in the steps above, this FIRST retrieves a pointer to the "Signature" of
                // this method (method name, parameter names, etc), and uses that pointer to
                // retrieve the HTMLNode's in that "Signature" - and converts it into a simple
                // Java String.
                DotPair sigDP           = DetailsPartMethod.signature(methodDetails);
                String  signature       = Util.textNodesString(methodDetails, sigDP);

                // The next four sections are also checked, because "Convenience Methods" are
                // supposed to have "Simplified Documentation" - and none of these sub-sections
                // should be present in a "Convenience Method"
                DotPair throwsSection   = DetailsPartMethod.throwing(methodDetails);
                DotPair returnSection   = DetailsPartMethod.returns(methodDetails);
                DotPair paramsSection   = DetailsPartMethod.parameters(methodDetails);
                DotPair seeAlsoSection  = DetailsPartMethod.see(methodDetails);

                // simplify the signature
                signature = Escape.replace(signature).replace("\n", " ");
                signature = StringParse.removeDuplicateSpaces(signature);

                if (log != null) log.println
                    ("\tConvenience Method Found: " + C.BGREEN + signature + C.RESET);

                // Warn and remove if a "Throws Section" is found
                if ((throwsSection != null) && (throwsSection.size() > 0))
                {
                    Util.removeRange(methodDetails, throwsSection);
                    iter.set(methodDetails);
                    if (log != null) log.println("\tThrows Section Removed.");
                }

                // These cases should *NEVER* actually happen, but if they do, make sure to
                // print a warning about them.

                if ((returnSection != null) && (returnSection.size() > 0))
                    if (log != null) log.println(C.BRED + "\tHas a 'Parameters' Section." + C.RESET);

                if ((returnSection != null) && (returnSection.size() > 0))
                    if (log != null) log.println(C.BRED + "\tHas a 'Returns' Section." + C.RESET);

                if ((seeAlsoSection != null) && (seeAlsoSection.size() > 0))
                    if (log != null) log.println(C.BRED + "\tHas a 'See Also' Section." + C.RESET);
            }
        }
    }

    /**
     * Monitors "Convenience Constructors".  Currently, the only modification performed is to
     * remove any "Throws" Sections which may have been automatically inserted because they were
     * "Checked Exceptions."  Warning messages are sent to the log if there is a "See Also"
     * section, or a parameters section.
     *
     * <BR /><BR /><B>NOTE:</B> The purpose of a "Convenience Constructor" is to try to keep the
     * JavaDoc Comment to one (at most) two lines, with a link to the "underlying constructor"
     * that is being invoked.  As long as there is a "link" to that other constructor, including
     * lists see-also, parameters, and throws clauses becomes very superfluous.
     *
     * @param fileVec Any JavaDoc Generated HTML Web-Page
     * @param log This is the log.  This parameter may be null, and if it is, it will be ignored.
     */
    public static void checkForConvenienceConstructors
        (Vector<HTMLNode> fileVec, StorageWriter log)
    {
        // If there are no constructor listed on the page, return immediately.
        if (Details.hasConstructorDetails(fileVec) == null) return;

        // This will iterate through each constructor in the "Constructor Details Section"
        HNLIInclusive iter = Details.constructorDetailsIterator(fileVec);

        while (iter.hasNext())
        {
            // Retrieves the HTML sub-section for the next "Constructor Description" found inside
            // the JavaDoc Generated Documentation Web-Page
            Vector<HTMLNode> constructorDetails = iter.next();

            // This retrieves a pointer to the portion of that sub-section that contains the
            // "description" (a text section)
            DotPair descriptionSection = DetailsPartConstructor.description(constructorDetails);

            // This utilizes the pointer from the previous step to return any / all HTML found in
            // the description portion for this constructor as a simple java.lang.String
            String description =    (   (descriptionSection != null) 
                                    &&  (descriptionSection.size() > 0))
                ? Util.textNodesString(constructorDetails, descriptionSection).trim()
                : "";

            if (description.startsWith("Convenience Constructor. "))
            {
                // As in the steps above, this FIRST retrieves a pointer to the "Signature" of
                // this method (method name, parameter names, etc), and uses that pointer to
                // retrieve the HTMLNode's in that "Signature" - and converts it into a simple
                // Java String.
                DotPair sigDP           = DetailsPartConstructor.signature(constructorDetails);
                String  signature       = Util.textNodesString(constructorDetails, sigDP);

                // The next four sections are also checked, because "Convenience Constructors" 
                // are supposed to have "Simplified Documentation" - and none of these 
                // sub-sections should be present in a "Convenience Constructor"
                DotPair throwsSection   = DetailsPartConstructor.throwing(constructorDetails);
                DotPair paramsSection   = DetailsPartConstructor.parameters(constructorDetails);
                DotPair seeAlsoSection  = DetailsPartConstructor.see(constructorDetails);

                // simplify the signature
                signature = Escape.replace(signature).replace("\n", " ");
                signature = StringParse.removeDuplicateSpaces(signature);

                if (log != null)
                    log.println
                        ("\tConvenience Constructor Found: " + C.BGREEN + signature + C.RESET);

                // Warn and remove if a "Throws Section" is found
                if ((throwsSection != null) && (throwsSection.size() > 0))
                {
                    Util.removeRange(constructorDetails, throwsSection);
                    iter.set(constructorDetails);
                    if (log != null) log.println("\tThrows Section Removed.");
                }

                // This case should *NEVER* actually happen, but if it does, make sure to
                // print a warning about it.
                if ((seeAlsoSection != null) && (seeAlsoSection.size() > 0))
                    if (log != null)
                        log.println(C.BRED + "\tHas a 'See Also' Section." + C.RESET);
            }
        }
    }
}