Class SkewedParameters


  • public class SkewedParameters
    extends java.lang.Object
    Skewed-Parameter List Repair - Documentation.

    'Long Parameter Lists' make the Java-Doc output look really awful, even bizarre. This class inserts new-lines (<BR>\n Elements)into a JavaDoc file where the return parameters are using 80% of the output frame/divider screen width.




Stateless Class: This class neither contains any program-state, nor can it be instantiated.
The @StaticFunctional Annotation may also be called 'The Spaghetti Report'
  • 1 Constructor(s), 1 declared private, zero-argument constructor
  • 5 Method(s), 5 declared static
  • 8 Field(s), 8 declared static, 8 declared final


    • Field Detail

      • TD_MAX_CHARACTERS

        public static final int TD_MAX_CHARACTERS
        Maximum length of a character-string representing the "Return Value" HTML '<TD>' Element in a "Method Summaries" Section before this class will insert HTML newline ('<BR />') Elements. Also is the maximum-length of the "Field-Type" String for a '<TD>' Element of "Field Summaries" Section before this class will impose the "Insert Commas and HTML <BR /> (newline) feature.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
        1
        public static final int TD_MAX_CHARACTERS = 35;
        
      • MAX_SIG_LINE_LENGTH

        public static final int MAX_SIG_LINE_LENGTH
        Maximum length of a line of the signature in a "Method Details" Section before this class will invoke the "Clean Up Method Signatures" method.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
        1
        public static final int MAX_SIG_LINE_LENGTH = 75;
        
    • Method Detail

      • run

        public static int run​(CommonParamRecord pr)
        This method will replace any / all comma's that are identified in the "Summary" section of the Documentation Page - in the table-column named "Modifier and Type" - with an HTML new-line '<BR />' element. This will be done for "Method Summaries" and also "Field Summaries"

        EXAMPLE: In the "Method Summaries" section of a Java-Doc Generated Class Description / Documentation HTML file, there is a method whose return value & method-signature are:
        1
        2
        3
        4
        5
        6
        7
        8
         // If this is a method-signature that is inside a certain class-file, the method "newLinesToSummaries(...)"
         // Will change the HTML inside the Java-Doc page in the following way...
         public static Ret2<java.util.Vector<HTMLNode>,java.lang.String> getVecAndName();
        
         // The method will have an HTML "<BR />" and a space character inserted after the comma
         // When this javadoc page is rendered in your browser, the return type will not be "way too long."
         public static Ret2<java.util.Vector<HTMLNode>, <NEWLINEHERE> java.lang.String> getVecAndName();
         
        
        The primary reason for this method is that sometimes the "Return Type" of a Java Method forces JavaDoc to create HTML documentation pages that are "really skewed" - where the return type takes more than 70% of the usable-screen display-space. This wll force any and all pages that the programmer requests to break the lengthy return types into two-lines.
        Parameters:
        pr - This contains all of the needed parameters for this method, encapsulated into a single record-class. The list is somewhat lengthy, so this makes the code "look cleaner"
        Returns:
        This will return a count on exactly how many modifications occurred.
        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
         if (pr.sw != null) pr.sw.println("SkewedParameters.run():");
        
         int     commasReplaced  = 0;
         int     total           = 0;
         DotPair dp;
        
         // Inserts "Commas Followed by HTML <BR />\n" HTML-Node lists after Comma's Found in the
         // "Method Summaries" Section.  This prevents giant-long Return-Values from hogging the
         // space in the HMTL-Table <TD> Element.  It looks really bad when they "Hog Space"... 
         // Inserting a new-line prevents the "Method Return Value" from having an inordinately
         // sized <TD> Width,  and "extends" the height of the HTML <TD> Element
         if ((dp = Summaries.hasMethodSummaries(pr.fileVec)) != null)
             commasReplaced += commasToNewLinesInSummaries(pr.fileVec, dp);
        
         // Inserts the Same HTML-Node List having an HTML New-Line Element for Fields whose "Type"
         // is really long.  This prevents the Field Name from being "pushed off the end of the
         // screen," and instead "extends" the height of the HTML <TD> Element.
         if ((dp = Summaries.hasFieldSummaries(pr.fileVec)) != null)
             commasReplaced += commasToNewLinesInSummaries(pr.fileVec, dp);
        
         if (pr.sw != null) pr.sw.println(
             "\tReplaced " + C.BBLUE + StringParse.zeroPad(commasReplaced, 5) + C.RESET +
             " commas with comma-BR"
         );
        
         int signaturesFixed = 0;
        
         // If the Method-Details "Signature" for any methods are horribly skewed such that
         // the parameters are way off to the right of the page, this will fix it.
         if ((dp = Details.hasMethodDetails(pr.fileVec)) != null)
             signaturesFixed = fixSignatures(pr.fileVec, dp);
        
         total += signaturesFixed;
        
         if (pr.sw != null) pr.sw.println(
             "\tModified " + C.BBLUE + StringParse.zeroPad(signaturesFixed, 5) + C.RESET +
             " Method Detail Signatures."
         );
        
         signaturesFixed = 0;
        
         // If the Constructor-Details "Signature" for any constructors are horribly skewed 
         // such that the parameters are way off to the right of the page, this will fix it.
         if ((dp = Details.hasConstructorDetails(pr.fileVec)) != null)
             signaturesFixed = fixSignatures(pr.fileVec, dp);
        
         total += signaturesFixed;
        
         if (pr.sw != null) pr.sw.println(
             "\tModified " + C.BBLUE + StringParse.zeroPad(signaturesFixed, 5) + C.RESET +
             " Constructor Detail Signatures."
         );
        
         return total + commasReplaced;
        
      • commasToNewLinesInSummaries

        protected static int commasToNewLinesInSummaries​
                    (java.util.Vector<HTMLNode> fileVec,
                     DotPair dp)
        
        This method takes care of the "Parameter Skew" that occurs in the "Method Summaries" and / or "Constructor Summaries" part of a JavaDoc Web-Page.
        Parameters:
        fileVec - This is a Java-Doc Generated HTML Documentation Page
        dp - This is the range of a summary section. It may be either the "Field Summary" section or the "Method Summary Section".
        Returns:
        This simply returns how many entries in the Summaries list were modified.
        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
         if (dp == null) return 0;
        
         // The first column iterator that is generated.
         HNLIInclusive iter = InnerTagInclusiveIterator.get
             (fileVec, "td", "class", TextComparitor.C, "colFirst");
        
         // Use the HNLIInclusive Iterator method to restrict the cursor to only
         // the summary section.
         iter.restrictCursor(dp.start, dp.end + 1);
        
         int totalCommasReplaced = 0;
        
         // Iterate the Field Summaries, or Method Summaries.
         while (iter.hasNext())
         {
             Vector<HTMLNode> column = iter.next();
             if (Util.textStrLength(column) > TD_MAX_CHARACTERS)
             {
                 int commasReplaced = replaceCommasWithBR(column);
                 if (commasReplaced > 0)
                 {
                     iter.set(column);
                     totalCommasReplaced += commasReplaced;
                 }
             }
         }
        
         return totalCommasReplaced;
        
      • fixSignatures

        protected static int fixSignatures​(java.util.Vector<HTMLNode> fileVec,
                                           DotPair details)
        This fixes the "signature" part of a Method Details Section, or a Constrcutor Details Section.
        Parameters:
        fileVec - This is the Vectorized HTML of a javadoc generated web-page.
        details - This is the range (as a DotPair) for a specific details section (method or constructor only).
        Returns:
        The number of signatures that were modified.
        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
         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
         int numSigsFixed = 0;
        
         // This shall iterate the method signatures or constructor signatures
         HNLIInclusive iter = InnerTagInclusiveIterator.get
             (fileVec, "ul", "class", TextComparitor.C, "blockList", "blockListLast");
                
         // Make sure we stay "inside" the method details section
         iter.restrictCursor(details);
        
         while (iter.hasNext())
         {
             Vector<HTMLNode> method = iter.next();
             DotPair preDP = TagNodeFindInclusive.first(method, "pre");
        
             // Build a line-by-line Vector of the Method Signature String
             // FIRST-TIME, leave out the HTML Tags.  First decide if this is even necessary.
             // In order to make that decision - see how long the lines are WITHOUT HTML TAGS.
             // System.out.println(Util.textNodesString(jdPage, preDP.start + 1, preDP.end))
        
             String[] sigArr = Util.textNodesString(method, preDP.start + 1, preDP.end).split("\n");
             Vector<String> sig = new Vector<>(sigArr.length);
             for (String str : sigArr) 
             {
                 if (HARD_CORE_DEBUGGING) System.out.println(str);
                 sig.addElement(Escape.replace(str));
             }
        
             // Only need to fix pages which have lines that are longer than MAX_SIG_LINE_LENGTH
             boolean fix = false;
             int max = 0;
             String maxLine = "";
             for (String line : sig)
             {
                 if (line.length() > max) { max = line.length(); maxLine = line; }
                 if (line.length() > MAX_SIG_LINE_LENGTH) { fix=true; /* break; */ }
             }
        
             if (DEBUGGING)
                 System.out.println(
                     "MAX LINE LENGTH: " + max + '\n' +
                     "MAX LINE: " + maxLine
                 );
        
             // No need to fix this particular method signature.
             if (! fix) continue;
        
             // Do it again, build a line-by-line Vector of the Method Signature
             // This time include the HTML Tags in the String.
             sigArr = Util.rangeToString(method, preDP.start + 1, preDP.end).split("\n");
             sig = new Vector<>(sigArr.length);
             for (String str : sigArr) sig.addElement(str);
        
             // NOTE: The first line of the signature contains the RETURN-TYPE
             //       The METHOD-NAME, and also the FIRST-PARAMETER.
             //       This is the most complicated part of the replace operation.
        
             // Compute the first line and the second line.
             int firstLineActualPos = 0;
             while (sig.elementAt(firstLineActualPos).startsWith("@")) firstLineActualPos++;
        
             String firstLine = sig.elementAt(firstLineActualPos);
             if (HARD_CORE_DEBUGGING) System.out.println(firstLine);
        
             int pos = firstLine.indexOf("(");
             String secondLine = SPACES12 + firstLine.substring(pos);
             firstLine = firstLine.substring(firstLineActualPos, pos).trim();
        
             if (DEBUGGING) System.out.println(firstLine);
             if (DEBUGGING) System.out.println(secondLine);
            
             // REPLACE the first line, and INSERT the "newly created" second line.
             // The current second-line will become the third line.
             // NOTE: The 'ActualPos' stuff was added later... If a method has "Annotations"
             //       then they are included above the method name and modifiers.  Just pretend
             //       that the whole thing starts at the first non-annotation line.
        
             sig.setElementAt(firstLine, firstLineActualPos);
             sig.add(firstLineActualPos + 1, secondLine);
             pos = secondLine.indexOf("(");
        
             // Deal with the rest of the parameters (if there are more parameters)
             // If there is only one parameter, the loop will NOT be entered.
             String  line    = secondLine;
             int     i       = firstLineActualPos + 1;
        
             if (HARD_CORE_DEBUGGING)
                 System.out.println("line.indexOf(\")\"): " + line.indexOf(")"));
        
             while (line.indexOf(")") == -1)
             {
                 line = sig.elementAt(++i);
        
                 // Make this line up with the previous parameter name, not the parenthesis
                 // Use 13 spaces instead of 12.
                 line = SPACES13 + line.trim();
        
                 if (DEBUGGING) System.out.println(line);
        
                 // Replace the line we just retrieved, it is now properly indented with 
                 // exactly 13 spaces.  This is 12 + 1, AGAIN, where the +1 is for the parenthesis
                 // that parameter #1 will have in front of it.
                 sig.setElementAt(line, i);
             }
        
             // there are still "throws" to deal with.  If so, move them too.
             // NOTE: The 'throws' itself shall have 8 spaces in front of it.
             //       The rest of them will align up with the Exception-Name.
             if (++i < sig.size()) 
             {
                 // The first line of "throws" statements will actually have the word
                 // "throws" in front of it.
                 line = SPACES8 + sig.elementAt(i).trim();
                 if (DEBUGGING) System.out.println(line);
                 sig.setElementAt(line, i);
        
                 while (++i < sig.size())
                 {
                     // Simply retrieve the line, trim it, properly indent it.
                     // the number 15 is: 8-Spaces of Indent, plus the length of the
                     // String "throws ".
                     line = SPACES15 + sig.elementAt(i).trim();
                     if (DEBUGGING) System.out.println(line);
                     sig.setElementAt(line, i);
                 }
             }
        
             // Replace the old HTML with the new stuff.
             StringBuilder sb = new StringBuilder();
             sig.forEach(str -> sb.append(str + '\n'));
        
             Vector<HTMLNode> newSig = HTMLPage.getPageTokens(sb, false);
             ReplaceNodes.r(method, new DotPair(preDP.start + 1, preDP.end - 1), newSig);
        
             iter.set(method);
        
             // Increment the counter.
             numSigsFixed++;
         }
        
         return numSigsFixed;
        
      • main

        public static void main​(java.lang.String[] argv)
                         throws java.io.IOException
        Throws:
        java.io.IOException
        Code:
        Exact Method Body:
        1
        2
        3
        4
         String jdFile = FileRW.loadFileToString(argv[0]);
         Vector<HTMLNode> jdPage = HTMLPage.getPageTokens(jdFile, false);
         fixSignatures(jdPage, Details.hasMethodDetails(jdPage));
         FileRW.writeFile(Util.pageToString(jdPage), "out.html");