001package Torello.HTML.Tools.JavaDoc; 002 003import Torello.HTML.*; 004import Torello.HTML.NodeSearch.*; 005 006import java.util.*; 007 008/** 009 * <CODE>TopDescription - Documentation.</CODE><BR /><BR /> 010 * <EMBED CLASS="external-html" DATA-FILE-ID="TD">. 011 */ 012@StaticFunctional 013public class TopDescription 014{ 015 private TopDescription() { } 016 017 /** 018 * <EMBED CLASS="external-html" DATA-FILE-ID="TDDAT"> 019 * 020 * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP"> 021 * 022 * @return A {@code 'DotPair'} pointer that holds pointers to the starting-position and 023 * ending-position in a vectorized-html web-page, in this case an HTML page generated by Java's 024 * 'javadoc' executable utility for generating code-documentation, ... <I><B>to the 025 * class-description section at the top of the page.</B></I> 026 * 027 * <BR /><BR /><B>NOTE:</B> If any insertion of HTML is going to happen, it is usually better 028 * to insert such elements inside of an {@code <LI>...</LI>} pair <I><B>inside the HTML 029 * Un-Ordered List</B></I> - which is the only element inside the HTML DIV element in a javadoc 030 * generated HTML class-description page. 031 * 032 * @see #dividerInsideDescriptionAtTop(Vector) 033 * @see InnerTagFindInclusive 034 * @see TextComparitor 035 */ 036 public static DotPair descriptionAtTop(Vector<HTMLNode> javaDocHTMLCIETPage) 037 { 038 return InnerTagFindInclusive.first 039 (javaDocHTMLCIETPage, "div", "class", TextComparitor.C, "description"); 040 } 041 042 /** 043 * It becomes difficult to explain, but the "Description Divider" (at the top of a javadoc 044 * created HTML class-file) actually just, sort-of, 'wraps' and another HTML "divider" 045 * ({@code <DIV ...> </DIV>}) element. If, by some chance, a programmer has decided to 046 * <I>insert HTML</I> into the top of an HTML java-doc class-description file, and he / she 047 * would like to preserve / utilize the CSS-Styling that is (automatically) assigned by JavaDoc 048 * to the rest of content in that page, then inserting at the beginning or end of the HTML 049 * "Description Divider" - rather than the internal "block" divider will produce a situation 050 * where the inserted HTML <I>is not formatted the same way, using the same fonts <B>as the 051 * rest of the text in the class-description</I></B> 052 * 053 * <BR /><BR /><B>SUMMARY:</B> If a programmer wants to 'borrow' or 'inherit' the style & 054 * font assignments that are assigned by the CSS definition to the HTML text being inserted, 055 * use method: 056 * 057 * <DIV CLASS="METHODSIGNATURE">{@code 058 * public static DotPair dividerInsideDescriptionAtTop(Vector<HTMLNode> javaDocHTMLCIETPage) 059 * }</DIV> 060 * 061 * <BR /><B><I>Rather than the method:</I></B> 062 * 063 * <DIV CLASS="METHODSIGNATURE">{@code 064 * public static DotPair descriptionAtTop(Vector<HTMLNode> javaDocHTMLCIETPage) 065 * }</DIV> 066 * 067 * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP"> 068 * 069 * @return A {@code 'DotPair'} pointer that holds pointers to the starting-position and 070 * ending-position in a vectorized-html web-page, in this case an HTML page generated by Java's 071 * 'javadoc' executable utility for generating code-documentation, ... <I><B>to the HTML 072 * {@code <DIV CLASS='block'>...</DIV>} class-description section at the top of the 073 * page.</B></I> 074 * 075 * @see #descriptionAtTop(Vector) 076 * @see InnerTagFindInclusive 077 * @see TextComparitor 078 */ 079 public static DotPair dividerInsideDescriptionAtTop(Vector<HTMLNode> javaDocHTMLCIETPage) 080 { 081 DotPair dp = descriptionAtTop(javaDocHTMLCIETPage); 082 083 if (dp == null) return null; 084 085 return InnerTagFindInclusive.first 086 (javaDocHTMLCIETPage, dp.start, dp.end + 1, "div", "class", TextComparitor.C, "block"); 087 } 088 089 /** 090 * This returns a DotPair (start & end integer vector-index pointers) to the HTML "title" 091 * element that contains the "Class, Interface, or Enumerated-Type Name" that is at the top of 092 * all Java-Doc Generated Web-Page. What the HTML actually looks like is included in the 093 * HTML-Snippet below: 094 * 095 * <DIV CLASS="HTML">{@code 096 * <!-- In any Java-Doc Generated HTML-Description Web-Page, the "Title" HTML looks like this: --> 097 * <h2 title="Class HTMLNode" class="title">Class HTMLNode</h2> 098 * }</DIV> 099 * 100 * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP"> 101 * 102 * @return A {@code 'DotPair'} pointer that holds pointers to the starting-position and 103 * ending-position in a vectorized-html web-page of the "title" ({@code <h2 title="Class 104 * HTMLNode" class="title"> ... title ...</h2>}) for any class, interface or enumerated-type 105 * JavaDoc Generated Web-Page. 106 * 107 * @see CommentNodeFind 108 * @see InnerTagFindInclusive 109 * @see TextComparitor 110 */ 111 public static DotPair title(Vector<HTMLNode> javaDocHTMLCIETPage) 112 { 113 int pos = CommentNodeFind.first 114 (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA =="); 115 116 if (pos == -1) return null; 117 118 return InnerTagFindInclusive.first 119 (javaDocHTMLCIETPage, "h2", "class", TextComparitor.C, "title"); 120 } 121 122 /** 123 * This returns the Title of this JavaDoc HTML Documentation Page as a String. This String 124 * will have the "Class, Interface, or Enumerated-Type Name" that is at the top of all Java-Doc 125 * Generated Web-Pages. What the HTML actually looks like is included in the HTML-Snippet 126 * below: 127 * 128 * <DIV CLASS="HTML">{@code 129 * <!-- In any Java-Doc Generated HTML-Description Web-Page, the "Title" HTML looks like this: --> 130 * <h2 title="Class HTMLNode" class="title">Class HTMLNode</h2> 131 * }</DIV> 132 * 133 * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP"> 134 * 135 * @return A {@code 'DotPair'} pointer that holds pointers to the starting-position and 136 * ending-position in a vectorized-html web-page of the "title" ({@code <h2 title="Class 137 * HTMLNode" class="title"> ... title ...</h2>}) for any class, interface or enumerated-type 138 * JavaDoc Generated Web-Page. 139 * 140 * @see Util#textNodesString(Vector) 141 * @see CommentNodeFind 142 * @see InnerTagFindInclusive 143 * @see TextComparitor 144 */ 145 public static String titleAsString(Vector<HTMLNode> javaDocHTMLCIETPage) 146 { 147 int pos = CommentNodeFind.first 148 (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA =="); 149 150 if (pos == -1) return null; 151 152 Vector<HTMLNode> v = InnerTagGetInclusive.first 153 (javaDocHTMLCIETPage, "h2", "class", TextComparitor.C, "title"); 154 155 return Escape.replace(Util.textNodesString(v)); 156 } 157 158 /** 159 * This returns a DotPair (start & end integer vector-index pointers) to the HTML 160 * "Unordered List" element that contains the "Class or Interface Inheritance Specification" 161 * which is at the top of all Java-Doc Generated Class or Interface Description Web-Pages. 162 * What the HTML actually looks like is included in the hilited code below: 163 * 164 * <DIV CLASS="HTML">{@code 165 * <!-- In Java-Doc Generated HTML-Description Web-Pages, the "Inheritance List" HTML looks like: --> 166 * <!-- In this particular case, "class CommentNode" (which inherits from HTMLNode) is used --> 167 * <ul class="inheritance"> 168 * <li>Torello.HTML.HTMLNode</li> 169 * </ul> 170 * }</DIV> 171 * 172 * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP"> 173 * 174 * @return A {@code 'DotPair'} pointer that holds pointers to the starting-position and 175 * ending-position in a vectorized-html web-page of the "inheritance Unordered List" 176 * ({@code <ul class="inheritance"> ... </ul>}) for any class or interface JavaDoc Generated 177 * Web-Page. If this web-page is not a javaDoc generated web-page, or is a part of a web-page 178 * that does not contain the information, then this method will return null, gracefully. No 179 * Exceptions will be thrown. 180 * 181 * @see CommentNodeFind 182 * @see InnerTagPeekInclusive 183 * @see TextComparitor 184 */ 185 public static Vector<SubSection> inheritance(Vector<HTMLNode> javaDocHTMLCIETPage) 186 { 187 int pos = CommentNodeFind.first 188 (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA =="); 189 190 if (pos == -1) return null; 191 192 return InnerTagPeekInclusive.all 193 (javaDocHTMLCIETPage, pos, -1, "ul", "class", TextComparitor.C, "inheritance"); 194 } 195 196 /** 197 * This returns a DotPair (start & end integer vector-index pointers) to the HTML 198 * Divider-Element ({@code "<DIV ...>"}) that contains the "Package Name" in which this class, 199 * interface, or enumerated-type is located. The package information is located at the top of 200 * all Java-Doc Generated Class or Interface Description Web-Pages. What the HTML actually 201 * looks like is included in the hilited code below: 202 * 203 * <DIV CLASS="HTML">{@code 204 * <!-- In Java-Doc Generated HTML-Description Web-Pages, the "Containing Package" HTML looks like: --> 205 * <div class="subTitle">Torello.HTML</div> 206 * }</DIV> 207 * 208 * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP"> 209 * 210 * @return A {@code 'DotPair'} pointer that holds pointers to the starting-position and 211 * ending-position in a vectorized-html web-page of the "Package Information" 212 * ({@code <div class="subTitle"> ... </div>}) for any class, interface, or enumerated-type 213 * JavaDoc Generated Web-Page. If this web-page is not a javaDoc generated web-page, or is a 214 * part of a web-page that does not contain the information, then this method will return null, 215 * gracefully; and no exceptions will be thrown. 216 * 217 * @see CommentNodeFind 218 * @see InnerTagFindInclusive 219 * @see TextComparitor 220 */ 221 public static DotPair packageInfo(Vector<HTMLNode> javaDocHTMLCIETPage) 222 { 223 int pos = CommentNodeFind.first 224 (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA =="); 225 226 if (pos == -1) return null; 227 228 return InnerTagFindInclusive.first 229 (javaDocHTMLCIETPage, pos, -1, "div", "class", TextComparitor.C, "subTitle"); 230 } 231 232 /** 233 * Rather than returning an vectorized-html sublist - <I>which is what method 234 * {@code 'package(Vector<HTMLNode>)'} does</I> - this method finds the "Package Name" itself 235 * and returns that as a regular java-string. This operation can be performed on a class, 236 * interface, or enumerated-type. This package-information is located at the top of all 237 * Java-Doc Description Web-Pages. What the HTML actually looks like is included in the 238 * hilited code below: 239 * 240 * <DIV CLASS="HTML">{@code 241 * <!-- In Java-Doc Generated HTML-Description Web-Pages, the "Containing Package" HTML looks like: 242 * <div class="subTitle">Torello.HTML</div> 243 * }</DIV> 244 * 245 * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP"> 246 * 247 * @return A string that contains "Package Information" for any class, interface, or 248 * enumerated-type JavaDoc Generated Web-Page. If this web-page is not a javaDoc generated 249 * web-page, or is a part of a web-page that does not contain the information, then this method 250 * will return null, gracefully; and no exceptions will throw. 251 * 252 * @see Util#textNodesString(Vector) 253 * @see CommentNodeFind 254 * @see InnerTagGetInclusive 255 * @see TextComparitor 256 */ 257 public static String packageInfoAsString(Vector<HTMLNode> javaDocHTMLCIETPage) 258 { 259 int pos = CommentNodeFind.first 260 (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA =="); 261 262 if (pos == -1) return null; 263 264 Vector<HTMLNode> v = InnerTagGetInclusive.first 265 (javaDocHTMLCIETPage, pos, -1, "class", TextComparitor.C, "subTitle"); 266 267 return Escape.replace(Util.textNodesString(v)); 268 } 269 270 /** 271 * Returns all of the HTML Element "{@code <DL> ... </DL>}" sublists at the top of a CIET 272 * (Class, Interface, or Enumerated-Type) java web-page. This contains a plethora of variants, 273 * depending on whether the particular documentation page is for a class, an interface, a 274 * function-interface, a static-inner-class, an enumerated type, etc. Below is an example 275 * piece of HTML for the class "CommentNode." There are many other versions for this sub-list, 276 * and it would be best to run this method-operation on different HTML Documentation Pages to 277 * see all the possible versions of {@code <DD> and <DT>} definitions that are possible in this 278 * {@code <DL> ... </DL>} sublist occurring in the "Description-at-Top" of a javadoc web-pge. 279 * 280 * <DIV CLASS="HTML">{@code 281 * <!-- In Java-Doc Generated HTML-Description Web-Pages, the top "DL" HTML Element looks like: --> 282 * <dl> 283 * <dt>All Implemented Interfaces:</dt> 284 * <dd>java.io.Serializable, java.lang.CharSequence, java.lang.Cloneable</dd> 285 * </dl> 286 * <dl> 287 * <dt>Direct Known Subclasses:</dt> 288 * <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> 289 * </dl> 290 * }</DIV> 291 * 292 * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP"> 293 * 294 * @see CommentNodeFind 295 * @see TagNodeFindInclusive 296 * @see TextComparitor 297 */ 298 public static Vector<DotPair> allTopDLs(Vector<HTMLNode> javaDocHTMLCIETPage) 299 { 300 int sPos = CommentNodeFind.first 301 (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA =="); 302 303 if (sPos == -1) return null; 304 305 int ePos = TagNodeFind.first(javaDocHTMLCIETPage, sPos, -1, TC.OpeningTags, "hr"); 306 307 if (ePos == -1) return null; 308 309 return TagNodeFindInclusive.all(javaDocHTMLCIETPage, sPos, ePos, "dl"); 310 } 311 312}