001package Torello.HTML.Tools.JavaDoc;
002
003import Torello.HTML.*;
004import Torello.Java.*;
005
006import Torello.HTML.NodeSearch.HNLIInclusive;
007import Torello.Java.Shell.C;
008
009import java.util.*;
010
011/**
012 * <CODE>Convenience - Documentation.</CODE><BR /><BR />
013 * <EMBED CLASS="external-html" DATA-FILE-ID="CONVENIENCE">
014 */
015@Torello.HTML.Tools.JavaDoc.StaticFunctional
016public class Convenience
017{
018    private Convenience() { }
019
020    /**
021     * Monitors "Convenience Methods".  Currently, the only modification performed is to remove
022     * any "Throws" Sections which may have been automatically inserted because they were
023     * "Checked Exceptions."  Warning messages are sent to the log if there is a "See Also,"
024     * "Returns" or a "Parameters" section.
025     *
026     * <BR /><BR /><B>NOTE:</B> The purpose of a "Convenience Method" is to try to keep the
027     * JavaDoc Comment to one (at most) two lines, with a link to the "underlying function"
028     * that is being invoked.  As long as there is a "link" to that other method, including
029     * lists of returns, parameters, and throws clauses becomes very superfluous.
030     *
031     * @param fileVec Any JavaDoc Generated HTML Web-Page
032     * @param log This is the log.  This parameter may be null, and if it is, it will be ignored.
033     */
034    public static void checkForConvenienceMethods(Vector<HTMLNode> fileVec, StorageWriter log)
035    {
036        // If there are no methods listed on the page, return immediately.
037        if (Details.hasMethodDetails(fileVec) == null) return;
038
039        // Thiis will iterate through each method in the "Method Details Section"
040        HNLIInclusive iter = Details.methodDetailsIterator(fileVec);
041
042        while (iter.hasNext())
043        {
044            // Retrieves the HTML sub-section for the next "Method Description" found inside the
045            // JavaDoc Generated Documentation Web-Page
046            Vector<HTMLNode> methodDetails = iter.next();
047
048            // This retrieves a pointer to the portion of that sub-section that contains the
049            // "description" (a text section)
050            DotPair descriptionSection = DetailsPartMethod.description(methodDetails);
051
052            // This utilizes the pointer from the previous step to return any / all HTML found in
053            // the description portion for this method as a simple java.lang.String
054            String description =    (   (descriptionSection != null) 
055                                    &&  (descriptionSection.size() > 0))
056                ? Util.textNodesString(methodDetails, descriptionSection).trim()
057                : "";
058
059            if (description.startsWith("Convenience Method. "))
060            {
061                // As in the steps above, this FIRST retrieves a pointer to the "Signature" of
062                // this method (method name, parameter names, etc), and uses that pointer to
063                // retrieve the HTMLNode's in that "Signature" - and converts it into a simple
064                // Java String.
065                DotPair sigDP           = DetailsPartMethod.signature(methodDetails);
066                String  signature       = Util.textNodesString(methodDetails, sigDP);
067
068                // The next four sections are also checked, because "Convenience Methods" are
069                // supposed to have "Simplified Documentation" - and none of these sub-sections
070                // should be present in a "Convenience Method"
071                DotPair throwsSection   = DetailsPartMethod.throwing(methodDetails);
072                DotPair returnSection   = DetailsPartMethod.returns(methodDetails);
073                DotPair paramsSection   = DetailsPartMethod.parameters(methodDetails);
074                DotPair seeAlsoSection  = DetailsPartMethod.see(methodDetails);
075
076                // simplify the signature
077                signature = Escape.replace(signature).replace("\n", " ");
078                signature = StringParse.removeDuplicateSpaces(signature);
079
080                if (log != null) log.println
081                    ("\tConvenience Method Found: " + C.BGREEN + signature + C.RESET);
082
083                // Warn and remove if a "Throws Section" is found
084                if ((throwsSection != null) && (throwsSection.size() > 0))
085                {
086                    Util.removeRange(methodDetails, throwsSection);
087                    iter.set(methodDetails);
088                    if (log != null) log.println("\tThrows Section Removed.");
089                }
090
091                // These cases should *NEVER* actually happen, but if they do, make sure to
092                // print a warning about them.
093
094                if ((returnSection != null) && (returnSection.size() > 0))
095                    if (log != null) log.println(C.BRED + "\tHas a 'Parameters' Section." + C.RESET);
096
097                if ((returnSection != null) && (returnSection.size() > 0))
098                    if (log != null) log.println(C.BRED + "\tHas a 'Returns' Section." + C.RESET);
099
100                if ((seeAlsoSection != null) && (seeAlsoSection.size() > 0))
101                    if (log != null) log.println(C.BRED + "\tHas a 'See Also' Section." + C.RESET);
102            }
103        }
104    }
105
106    /**
107     * Monitors "Convenience Constructors".  Currently, the only modification performed is to
108     * remove any "Throws" Sections which may have been automatically inserted because they were
109     * "Checked Exceptions."  Warning messages are sent to the log if there is a "See Also"
110     * section, or a parameters section.
111     *
112     * <BR /><BR /><B>NOTE:</B> The purpose of a "Convenience Constructor" is to try to keep the
113     * JavaDoc Comment to one (at most) two lines, with a link to the "underlying constructor"
114     * that is being invoked.  As long as there is a "link" to that other constructor, including
115     * lists see-also, parameters, and throws clauses becomes very superfluous.
116     *
117     * @param fileVec Any JavaDoc Generated HTML Web-Page
118     * @param log This is the log.  This parameter may be null, and if it is, it will be ignored.
119     */
120    public static void checkForConvenienceConstructors
121        (Vector<HTMLNode> fileVec, StorageWriter log)
122    {
123        // If there are no constructor listed on the page, return immediately.
124        if (Details.hasConstructorDetails(fileVec) == null) return;
125
126        // This will iterate through each constructor in the "Constructor Details Section"
127        HNLIInclusive iter = Details.constructorDetailsIterator(fileVec);
128
129        while (iter.hasNext())
130        {
131            // Retrieves the HTML sub-section for the next "Constructor Description" found inside
132            // the JavaDoc Generated Documentation Web-Page
133            Vector<HTMLNode> constructorDetails = iter.next();
134
135            // This retrieves a pointer to the portion of that sub-section that contains the
136            // "description" (a text section)
137            DotPair descriptionSection = DetailsPartConstructor.description(constructorDetails);
138
139            // This utilizes the pointer from the previous step to return any / all HTML found in
140            // the description portion for this constructor as a simple java.lang.String
141            String description =    (   (descriptionSection != null) 
142                                    &&  (descriptionSection.size() > 0))
143                ? Util.textNodesString(constructorDetails, descriptionSection).trim()
144                : "";
145
146            if (description.startsWith("Convenience Constructor. "))
147            {
148                // As in the steps above, this FIRST retrieves a pointer to the "Signature" of
149                // this method (method name, parameter names, etc), and uses that pointer to
150                // retrieve the HTMLNode's in that "Signature" - and converts it into a simple
151                // Java String.
152                DotPair sigDP           = DetailsPartConstructor.signature(constructorDetails);
153                String  signature       = Util.textNodesString(constructorDetails, sigDP);
154
155                // The next four sections are also checked, because "Convenience Constructors" 
156                // are supposed to have "Simplified Documentation" - and none of these 
157                // sub-sections should be present in a "Convenience Constructor"
158                DotPair throwsSection   = DetailsPartConstructor.throwing(constructorDetails);
159                DotPair paramsSection   = DetailsPartConstructor.parameters(constructorDetails);
160                DotPair seeAlsoSection  = DetailsPartConstructor.see(constructorDetails);
161
162                // simplify the signature
163                signature = Escape.replace(signature).replace("\n", " ");
164                signature = StringParse.removeDuplicateSpaces(signature);
165
166                if (log != null)
167                    log.println
168                        ("\tConvenience Constructor Found: " + C.BGREEN + signature + C.RESET);
169
170                // Warn and remove if a "Throws Section" is found
171                if ((throwsSection != null) && (throwsSection.size() > 0))
172                {
173                    Util.removeRange(constructorDetails, throwsSection);
174                    iter.set(constructorDetails);
175                    if (log != null) log.println("\tThrows Section Removed.");
176                }
177
178                // This case should *NEVER* actually happen, but if it does, make sure to
179                // print a warning about it.
180                if ((seeAlsoSection != null) && (seeAlsoSection.size() > 0))
181                    if (log != null)
182                        log.println(C.BRED + "\tHas a 'See Also' Section." + C.RESET);
183            }
184        }
185    }
186}