Class Convenience


  • public class Convenience
    extends java.lang.Object
    Convenience - Documentation.

    The Upgrader Tool "keeps an eye out" for any methods whose Java-Doc descriptions begin with the sub-string "Convenience Method" or "Convenience Constructor". When one is found, a few check are performed to ensure that the generated description is kept simplified according to the standard pattern for "Convenience Methods" (and Constructors) on an Upgraded Java-Doc Documentation Web-Page.

    NOTE: Convenience Methods are simple, only having one or two lines in the body. Often they simply provide default values for parameters that the user ought not to have to bother with in many of the use-cases of another method.



    • Method Detail

      • checkForConvenienceMethods

        public static void checkForConvenienceMethods​
                    (java.util.Vector<HTMLNode> fileVec,
                     StorageWriter log)
        
        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.

        NOTE: 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.
        Parameters:
        fileVec - Any JavaDoc Generated HTML Web-Page
        log - This is the log. This parameter may be null, and if it is, it will be ignored.
        Code:
        Exact Method Body:
         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
         // 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);
             }
         }
        
      • checkForConvenienceConstructors

        public static void checkForConvenienceConstructors​
                    (java.util.Vector<HTMLNode> fileVec,
                     StorageWriter log)
        
        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.

        NOTE: 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.
        Parameters:
        fileVec - Any JavaDoc Generated HTML Web-Page
        log - This is the log. This parameter may be null, and if it is, it will be ignored.
        Code:
        Exact Method Body:
         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
         // 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);
             }
         }