1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
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);
            }
        }
    }
}