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
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
package Torello.HTML.Tools.JavaDoc;

import Torello.HTML.*;
import Torello.HTML.NodeSearch.*;

import java.util.*;

/**
 * <CODE>TopDescription - Documentation.</CODE><BR /><BR />
 * <EMBED CLASS="external-html" DATA-FILE-ID="TD">.
 */
@StaticFunctional
public class TopDescription
{
    private TopDescription() { }

    /**
     * <EMBED CLASS="external-html" DATA-FILE-ID="TDDAT">
     * 
     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
     * 
     * @return A {@code 'DotPair'} pointer that holds pointers to the starting-position and
     * ending-position in a vectorized-html web-page, in this case an HTML page generated by Java's
     * 'javadoc' executable utility for generating code-documentation, ... <I><B>to the
     * class-description section at the top of the page.</B></I>
     * 
     * <BR /><BR /><B>NOTE:</B> If any insertion of HTML is going to happen, it is usually better
     * to insert such elements inside of an {@code <LI>...</LI>} pair <I><B>inside the HTML
     * Un-Ordered List</B></I> - which is the only element inside the HTML DIV element in a javadoc
     * generated HTML class-description page.
     * 
     * @see #dividerInsideDescriptionAtTop(Vector)
     * @see InnerTagFindInclusive
     * @see TextComparitor
     */
    public static DotPair descriptionAtTop(Vector<HTMLNode> javaDocHTMLCIETPage)
    {
        return InnerTagFindInclusive.first
            (javaDocHTMLCIETPage, "div", "class", TextComparitor.C, "description");
    }

    /**
     * It becomes difficult to explain, but the "Description Divider" (at the top of a javadoc
     * created HTML class-file) actually just, sort-of, 'wraps' and another HTML "divider"
     * ({@code <DIV ...> </DIV>}) element.  If, by some chance, a programmer has decided to
     * <I>insert HTML</I> into the top of an HTML java-doc class-description file, and he / she
     * would like to preserve / utilize the CSS-Styling that is (automatically) assigned by JavaDoc
     * to the rest of content in that page, then inserting at the beginning or end of the HTML
     * "Description Divider" - rather than the internal "block" divider  will produce a situation
     * where the inserted HTML <I>is not formatted the same way, using the same fonts <B>as the
     * rest of the text in the class-description</I></B>
     *
     * <BR /><BR /><B>SUMMARY:</B> If a programmer wants to 'borrow' or 'inherit' the style &amp;
     * font assignments that are assigned by the CSS definition to the HTML text being inserted,
     * use method:
     * 
     * <DIV CLASS="METHODSIGNATURE">{@code
     * public static DotPair dividerInsideDescriptionAtTop(Vector<HTMLNode> javaDocHTMLCIETPage)
     * }</DIV>
     *
     * <BR /><B><I>Rather than the method:</I></B>
     *
     * <DIV CLASS="METHODSIGNATURE">{@code
     * public static DotPair descriptionAtTop(Vector<HTMLNode> javaDocHTMLCIETPage)
     * }</DIV>
     * 
     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
     * 
     * @return A {@code 'DotPair'} pointer that holds pointers to the starting-position and
     * ending-position in a vectorized-html web-page, in this case an HTML page generated by Java's
     * 'javadoc' executable utility for generating code-documentation, ... <I><B>to the HTML
     * {@code <DIV CLASS='block'>...</DIV>} class-description section at the top  of the
     * page.</B></I>
     * 
     * @see #descriptionAtTop(Vector)
     * @see InnerTagFindInclusive
     * @see TextComparitor
     */
    public static DotPair dividerInsideDescriptionAtTop(Vector<HTMLNode> javaDocHTMLCIETPage)
    {
        DotPair dp = descriptionAtTop(javaDocHTMLCIETPage);

        if (dp == null) return null;

        return InnerTagFindInclusive.first
            (javaDocHTMLCIETPage, dp.start, dp.end + 1, "div", "class", TextComparitor.C, "block");
    }

    /**
     * This returns a DotPair (start &amp; end integer vector-index pointers) to the HTML "title"
     * element that contains the "Class, Interface, or Enumerated-Type Name" that is at the top of
     * all Java-Doc Generated Web-Page.  What the HTML actually looks like is included in the
     * HTML-Snippet below:
     * 
     * <DIV CLASS="HTML">{@code
     * <!-- In any Java-Doc Generated HTML-Description Web-Page, the "Title" HTML looks like this: -->
     * <h2 title="Class HTMLNode" class="title">Class HTMLNode</h2>
     * }</DIV>
     * 
     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
     * 
     * @return A {@code 'DotPair'} pointer that holds pointers to the starting-position and
     * ending-position in a vectorized-html web-page of the "title" ({@code <h2 title="Class
     * HTMLNode" class="title"> ... title ...</h2>}) for any class, interface or enumerated-type
     * JavaDoc Generated Web-Page.
     * 
     * @see CommentNodeFind
     * @see InnerTagFindInclusive
     * @see TextComparitor
     */
    public static DotPair title(Vector<HTMLNode> javaDocHTMLCIETPage)
    {
        int pos = CommentNodeFind.first
            (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA ==");

        if (pos == -1) return null;

        return InnerTagFindInclusive.first
            (javaDocHTMLCIETPage, "h2", "class", TextComparitor.C, "title");
    }

    /**
     * This returns the Title of this JavaDoc HTML Documentation Page as a String.  This String
     * will have the "Class, Interface, or Enumerated-Type Name" that is at the top of all Java-Doc
     * Generated Web-Pages.  What the HTML actually looks like is included in the HTML-Snippet
     * below:
     * 
     * <DIV CLASS="HTML">{@code
     * <!-- In any Java-Doc Generated HTML-Description Web-Page, the "Title" HTML looks like this: -->
     * <h2 title="Class HTMLNode" class="title">Class HTMLNode</h2>
     * }</DIV>
     * 
     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
     * 
     * @return A {@code 'DotPair'} pointer that holds pointers to the starting-position and
     * ending-position in a vectorized-html web-page of the "title" ({@code <h2 title="Class
     * HTMLNode" class="title"> ... title ...</h2>}) for any class, interface or enumerated-type
     * JavaDoc Generated Web-Page.
     * 
     * @see Util#textNodesString(Vector)
     * @see CommentNodeFind
     * @see InnerTagFindInclusive
     * @see TextComparitor
     */
    public static String titleAsString(Vector<HTMLNode> javaDocHTMLCIETPage)
    {
        int pos = CommentNodeFind.first
            (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA ==");

        if (pos == -1) return null;

        Vector<HTMLNode> v = InnerTagGetInclusive.first
            (javaDocHTMLCIETPage, "h2", "class", TextComparitor.C, "title");

        return Escape.replace(Util.textNodesString(v));
    }

    /**
     * This returns a DotPair (start &amp; end integer vector-index pointers) to the HTML
     * "Unordered List" element that contains the "Class or Interface Inheritance Specification"
     * which is at the top of all Java-Doc Generated Class or Interface Description Web-Pages.
     * What the HTML actually looks like is included in the hilited code below:
     * 
     * <DIV CLASS="HTML">{@code
     * <!-- In Java-Doc Generated HTML-Description Web-Pages, the "Inheritance List" HTML looks like: -->
     * <!-- In this particular case, "class CommentNode" (which inherits from HTMLNode) is used -->
     * <ul class="inheritance">
     * <li>Torello.HTML.HTMLNode</li>
     * </ul>
     * }</DIV>
     * 
     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
     * 
     * @return A {@code 'DotPair'} pointer that holds pointers to the starting-position and
     * ending-position in a vectorized-html web-page of the "inheritance Unordered List"
     * ({@code <ul class="inheritance"> ... </ul>}) for any class or interface JavaDoc Generated
     * Web-Page.  If this web-page is not a javaDoc generated web-page, or is a part of a web-page
     * that does not contain the information, then this method will return null, gracefully. No
     * Exceptions will be thrown.
     * 
     * @see CommentNodeFind
     * @see InnerTagPeekInclusive
     * @see TextComparitor
     */
    public static Vector<SubSection> inheritance(Vector<HTMLNode> javaDocHTMLCIETPage)
    {
        int pos = CommentNodeFind.first
            (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA ==");

        if (pos == -1) return null;

        return InnerTagPeekInclusive.all
            (javaDocHTMLCIETPage, pos, -1, "ul", "class", TextComparitor.C, "inheritance");
    }

    /**
     * This returns a DotPair (start &amp; end integer vector-index pointers) to the HTML
     * Divider-Element ({@code "<DIV ...>"}) that contains the "Package Name" in which this class,
     * interface, or enumerated-type is located.  The package information is located at the top of
     * all Java-Doc Generated Class or Interface Description Web-Pages.  What the HTML actually
     * looks like is included in the hilited code below:
     * 
     * <DIV CLASS="HTML">{@code
     * <!-- In Java-Doc Generated HTML-Description Web-Pages, the "Containing Package" HTML looks like: -->
     * <div class="subTitle">Torello.HTML</div>
     * }</DIV>
     * 
     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
     * 
     * @return A {@code 'DotPair'} pointer that holds pointers to the starting-position and
     * ending-position in a vectorized-html web-page of the "Package Information"
     * ({@code <div class="subTitle"> ... </div>}) for any class, interface, or enumerated-type
     * JavaDoc Generated Web-Page.  If this web-page is not a javaDoc generated web-page, or is a
     * part of a web-page that does not contain the information, then this method will return null,
     * gracefully; and no exceptions will be thrown.
     * 
     * @see CommentNodeFind
     * @see InnerTagFindInclusive
     * @see TextComparitor
     */
    public static DotPair packageInfo(Vector<HTMLNode> javaDocHTMLCIETPage)
    {
        int pos = CommentNodeFind.first
            (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA ==");

        if (pos == -1) return null;

        return InnerTagFindInclusive.first
            (javaDocHTMLCIETPage, pos, -1, "div", "class", TextComparitor.C, "subTitle");
    }

    /**
     * Rather than returning an vectorized-html sublist - <I>which is what method
     * {@code 'package(Vector<HTMLNode>)'} does</I> - this method finds the "Package Name" itself
     * and returns that as a regular java-string.  This operation can be performed on a class,
     * interface, or enumerated-type.  This package-information is located at the top of all
     * Java-Doc Description Web-Pages.  What the HTML actually looks like is included in the
     * hilited code below:
     * 
     * <DIV CLASS="HTML">{@code
     * <!-- In Java-Doc Generated HTML-Description Web-Pages, the "Containing Package" HTML looks like:
     * <div class="subTitle">Torello.HTML</div>
     * }</DIV>
     * 
     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
     * 
     * @return A string that contains "Package Information" for any class, interface, or
     * enumerated-type JavaDoc Generated Web-Page. If this web-page is not a javaDoc generated
     * web-page, or is a part of a web-page that does not contain the information, then this method
     * will return null, gracefully; and no exceptions will throw.
     * 
     * @see Util#textNodesString(Vector)
     * @see CommentNodeFind
     * @see InnerTagGetInclusive
     * @see TextComparitor
     */
    public static String packageInfoAsString(Vector<HTMLNode> javaDocHTMLCIETPage)
    {
        int pos = CommentNodeFind.first
            (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA ==");

        if (pos == -1) return null;

        Vector<HTMLNode> v = InnerTagGetInclusive.first
            (javaDocHTMLCIETPage, pos, -1, "class", TextComparitor.C, "subTitle");

        return Escape.replace(Util.textNodesString(v));
    }

    /**
     * Returns all of the HTML Element "{@code <DL> ... </DL>}" sublists at the top of a CIET
     * (Class, Interface, or Enumerated-Type) java web-page.  This contains a plethora of variants,
     * depending on  whether the particular documentation page is for a class, an interface, a
     * function-interface, a static-inner-class, an enumerated type, etc.  Below is an example
     * piece of HTML for the class "CommentNode."  There are many other versions for this sub-list,
     * and it would be best to run this method-operation on different HTML Documentation Pages to
     * see all the possible versions of {@code <DD> and <DT>} definitions that are possible in this
     * {@code <DL> ... </DL>} sublist occurring in the "Description-at-Top" of a javadoc web-pge.
     *
     * <DIV CLASS="HTML">{@code
     * <!-- In Java-Doc Generated HTML-Description Web-Pages, the top "DL" HTML Element looks like: -->
     * <dl>
     * <dt>All Implemented Interfaces:</dt>
     * <dd>java.io.Serializable, java.lang.CharSequence, java.lang.Cloneable</dd>
     * </dl>
     * <dl>
     * <dt>Direct Known Subclasses:</dt>
     * <dd><a href="../../Torello/HTML/CommentNode.html" title="class in Torello.HTML">CommentNode</a>, <a href="../../Torello/HTML/TagNode.html" title="class in Torello.HTML">TagNode</a>, <a href="../../Torello/HTML/TextNode.html" title="class in Torello.HTML">TextNode</a></dd>
     * </dl>
     * }</DIV>
     * 
     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
     * 
     * @see CommentNodeFind
     * @see TagNodeFindInclusive
     * @see TextComparitor
     */
    public static Vector<DotPair> allTopDLs(Vector<HTMLNode> javaDocHTMLCIETPage)
    {
        int sPos = CommentNodeFind.first
            (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA ==");

        if (sPos == -1) return null;

        int ePos = TagNodeFind.first(javaDocHTMLCIETPage, sPos, -1, TC.OpeningTags, "hr");

        if (ePos == -1) return null;

        return TagNodeFindInclusive.all(javaDocHTMLCIETPage, sPos, ePos, "dl");
    }

}