public class CleanSummaries extends java.lang.Object
CleanSummaries - Documentation.
The class is the class responsible for removing summary-descriptions from
Fields, Methods, Constructorsand
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
Tagletthat is supposed to parse and figure out the "First Line Summaries" in the Summary Sections. The
Tagletoften 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:
Stateless Class: This class neither contains any program-state, nor can it be instantiated.
@StaticFunctionalAnnotation 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)
All Methods Static Methods Concrete Methods Modifier and Type Method
insertSentences(Vector<HTMLNode> jdPage, JavaDocHTMLFile jdhf, Vector<String> summarySentencesFile)
protected static int
removeAll(Vector<HTMLNode> fileVec, DotPair dp, Function<Vector<HTMLNode>,HNLIInclusive> funcPtr)
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.
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"
- The number of summary descriptions that were removed.
- Exact Method Body:
protected static int removeAll (java.util.Vector<HTMLNode> fileVec, DotPair dp, java.util.function.Function<java.util.Vector<HTMLNode>,HNLIInclusive> funcPtr)This removes 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
<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.
fileVec- A Java-Doc generated page for any CIET (Class, Interface or Enumerated-Type)
dp- A pointer to a
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.
- Exact Method Body:
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).
- Exact Method Body: