Class CleanSummaries

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

    The class is the class responsible for removing summary-descriptions from Fields, Methods, Constructors and Enumerated Constants "Field Summary", "Method Summary", and "Constructor Summary" summary sections of a JavaDoc Web-Page. Currently there is no functionality for inserting simple first-line sentences into a JavaDoc CIET Web-Page.

    First, the page is more readable without the "AI Driven" Java Taglet that is supposed to parse and figure out the "First Line Summaries" in the Summary Sections. The Taglet often inserts spurious HTML Dividers and makes it unreadable. Second, using good method and field names usually makes the single "Summary Sentence" kind of extraneous.

    Cleaned Summaries look as in the picture below:

    Cleaned Summaries




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
  • 4 Method(s), 4 declared static
  • 0 Field(s)


    • Method Detail

      • removeAllDescriptionsFromSummaries

        public static int removeAllDescriptionsFromSummaries​(CommonParamRecord pr)
        IMPORTANT NOTE: This version of "remove All dividers from the Summaries" removes 100% of text from the summary-section - and just lives the method/field/constructor signature (input parameters, and output type)... NOTHING ELSE REMAINS.... Right now, I have decided to go with this one instead of the other one. The other version removes all text after the 2nd opening Divider. It is probably better, but unfortunately, sometimes the "... " winds up being stuck inside the summary description.

        NOTE: I think I have figured out how the logic decides which text goes in the summary. Generally, if there is a sentence that ends with a period and has no newlines, that is put into the summary section, and everything else is left out. If I can go back into all of my classes, and put a good one-sentence opening summary into my JavaDoc's, then I could get rid of this version, and use the original "Remove All Dividers From Summaries."

        ALSO: The reason we have "remove All Dividers from Summaries" in the first place is because as soon as I had my <DIV CLASS='MyClassThings'> ... </DIV> into a JavaDoc, the JavaDoc Tool doesn't deal with it perfectly... (It starts messing up the summary sections! That's all!)

        TO DO: Put much better one-sentence, one-period summary descriptions at the top of all the methods and constructors in these packages.
        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:
        The number of summary descriptions that were removed.
        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
         if (pr.sw != null) pr.sw.println
     ("SummaryDescriptions.removeAllDescriptionsFromSummaries(...) ");

 int remCount = 0;

 remCount += removeAll(
     pr.fileVec, Summaries.hasFieldSummaries(pr.fileVec),
     Summaries::fieldSummaryIterator
 );

 remCount += removeAll(
     pr.fileVec, Summaries.hasConstructorSummaries(pr.fileVec),
     Summaries::constructorSummaryIterator
 );

 remCount += removeAll(
     pr.fileVec, Summaries.hasMethodSummaries(pr.fileVec),
     Summaries::methodSummaryIterator
 );

 remCount += removeAll(
     pr.fileVec, Summaries.hasNestedClassSummaries(pr.fileVec),
     Summaries::nestedClassSummaryIterator
 );

 if (pr.sw != null) pr.sw.println(
     "\tRemoved  " + C.BBLUE + StringParse.zeroPad(remCount, 5) + C.RESET + 
     " Summary Descriptions HTMLNode's"
 );

 return remCount;

      • removeAll

        protected static int removeAll​
            (java.util.Vector<HTMLNode> fileVec,
             DotPair dp,
             java.util.function.Function<java.util.Vector<HTMLNode>,​HNLIInclusive> funcPtr)
        This removes the 'description' from the 'Summaries' sections of a java-doc generated web-page. Primarily, the 'description' that is auto-computed by java-doc can be very error-prone for many non-trivial methods, constructors, etc... that have longer comment sections. Especially any description where HTML <DIV> elements are included, the traditional "nice looking one sentence" summary that is provided by JDK methods for packages like "java.lang" or "java.util" will mushroom into behemoths with tables and charts - rendering the output largely unusable.
        Parameters:
        fileVec - A Java-Doc generated page for any CIET (Class, Interface or Enumerated-Type)
        dp - A pointer to a 'Summary' section.
        funcPtr - A Java function-pointer that will produce the HNLIInclusive (HTML Iterator) that will iterate the individual summaries for each method in the 'Method Summaries' or also each constructor in the 'Constructor Summaries' - and so on and so forth.
        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
         if (dp == null) return 0;

 // NEWER JavaDoc's add a "Description" column to constructors.  Older Javadoc have a
 // single column called "Constructor & Description"  The 'if statement' after this 
 // checks for '3 columns' but constructors only have 2 columns (unlike the others)
 DotPair constructorTH = InnerTagFindInclusive.first
     (fileVec, dp.start, dp.end, "th", "class", TextComparitor.C, "colLast");

 if (constructorTH != null)
     if (TextNodeFind.first
         (fileVec, constructorTH.start, constructorTH.end, s -> s.equals("Description")) != -1)
             Util.removeRange(fileVec, constructorTH);

 // NEWER JavaDoc's have a "colSecond" (3 columns)
 if (InnerTagCount.all
     (fileVec, dp.start, dp.end, "th", "class", TextComparitor.C, "colSecond") > 0)
 {
     // This removes the column HEADERS...  It will not be included in the "remove count" 
     // return value.
     InnerTagRemoveInclusive.all
         (fileVec, dp.start, dp.end, "th", "class", TextComparitor.C, "colLast");

     // These are the actual summary-description columns.  Remove them all at the same time.
     // Return as "remove count"
     return InnerTagRemoveInclusive.all
         (fileVec, dp.start, dp.end, "td", "class", TextComparitor.C, "colLast");
 }

 // OLDER JavaDoc's have "colFirst" and "colLast" (2 columns)
 int             remCount    = 0;
 HNLIInclusive   iter        = funcPtr.apply(fileVec);
 while (iter.hasNext())
 {
     Vector<HTMLNode>    summary = iter.next();
     int[]               posArr  = TagNodeFind.all(summary, TC.Both, "div");

     // A summary that had html dividers means a "summary description" was present.
     // The purpose of this method is to remove those.
     if (posArr.length > 0)
     {
         remCount++; 
         Util.removeRange(summary, posArr[0], posArr[posArr.length - 1] + 1);
         iter.set(summary);
     }
 }
 return remCount;

      • insertSentences

        public static void insertSentences​
            (java.util.Vector<HTMLNode> jdPage,
             JavaDocHTMLFile jdhf,
             java.util.Vector<java.lang.String> summarySentencesFile)
        Not currently Used.

        TO-DO: Finish it.

        NOTE: Yes, it is more work. But, yes, the "Summaries" section actually look better with just the method signatures, and without those "First Sentences" anyway... Using good naming conventions for methods, makes the method names a little longer, but it makes the this section (in particular) MORE READABLE - even without the "Summary Sentences" (which were removed).
        Code:
        Exact Method Body:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
         HNLIInclusive   methodSummaries = Summaries.methodSummaryIterator(jdPage);
 DotPair         summaryLocation = null;
 int             counter         = 0;
 int             insertLocation  = 0;

 while (methodSummaries.hasNext())
 {
     // Returns the Location of a 
     // <tr id="i1" class="rowColor"> 
     //      <td class="colFirst">...</td> <td class="colLast"> ... </td>
     // </tr>
     summaryLocation = methodSummaries.nextDotPair();
     Method method = jdhf.getMethod(counter++);
        
     insertLocation = TagNodeFind.last
         (jdPage, summaryLocation.start, summaryLocation.end, TC.ClosingTags, "td");
 }