Class TopDescription


  • public class TopDescription
    extends java.lang.Object
    Java Doc HTML-File Reader: Find and retrieve any of the parts inside the header section of a Java Doc CIET web-page.

    This class is used to manipulate the class, interface, or enumerated-type description at the top. For instance, these words you are reading right now are located in the "Top Description" for class TopDescription .


Stateless Class: This class neither contains any program-state, nor can it be instantiated. The @StaticFunctional Annotation may also be called 'The Spaghetti Report'. Static-Functional classes are, essentially, C-Styled Files, without any constructors or non-static member field. It is very similar to the Java-Bean @Stateless Annotation.
  • 1 Constructor(s), 1 declared private, zero-argument constructor
  • 8 Method(s), 8 declared static
  • 0 Field(s)
  • Fields excused from final modifier (with explanation):


    • Method Detail

      • descriptionAtTop

        🡇    
        public static DotPair descriptionAtTop​
                    (java.util.Vector<HTMLNode> javaDocHTMLCIETPage)
        
        This will return the "class or interface (or enumerated-type 'enum')" that is always printed at the very top of any JavaDoc generated documentation file. The example included in this method description shall be the javadoc generated "description" for class 'Torello.Java.FileRW'

        HTML Elements:
        <!-- The following HTML was just copied/lifted from the documentation of the FileRW class on June 1st, 2019 -->
        <!-- It may have changed since then, but unlikely -->
        
        </a></div>
        <!-- ========= END OF TOP NAVBAR ========= -->
        <!-- ======== START OF CLASS DATA ======== -->
        <div class="header">
        <div class="subTitle">Torello.Java</div>
        <h2 title="Class FileRW" class="title">Class FileRW</h2>
        </div>
        <div class="contentContainer">
        <ul class="inheritance">
        <li>java.lang.Object</li>
        <li>
        <ul class="inheritance">
        <li>Torello.Java.FileRW</li>
        </ul>
        </li>
        </ul>
        <div class="description"> <!-- THIS RIGHT HERE IS THE HTML 'DIVIDER' whose 'innerHTML' CONTENTS HOLD THE CLASS DESCRIPTION. -->
        <ul class="blockList">
        <li class="blockList">
        <hr>
        <br>
        <pre>public class <a href="../../src-html/Torello/Java/FileRW.html#line.25">FileRW</a>
        extends java.lang.Object</pre>
        <div class="block">The purpose of this class is to simplify quite a few of the standard java.io.* file operations.  The operations that Java provides are
        mostly "pretty useful" - however, if one is <i>not concerned with the optimization of read's or write's</i>, what this package provides
        is many orders of <b>code simplification.</b>  Many of the append and write operations instantiate a <code>java.io.File and
        java.io.OutputStream</code>, and open and close those objects/classes in the same method/function body.
        
        <BR /><BR />
        <b>FileRW.append()</b> for instance, opens the File-Pointer, writes the String, and then closes it immediately.  However, the 4 or 5
        lines of code that each of these methods/functions eliminate make text-processing code and language-translation code a lot easier to read.
        With text-processing and language-translation, I find myself writing file data once a day, and never for very long.  A few milliseconds is
        expended by opening and closing these file-pointers, but the code that I have written is world's easier to read.
        
        <BR /><BR />
        <b>FileRW.writeObjectToFile()</b> for instance, allows a user who is writing Vector<String> <i>(which for all intents-and-purposes is
        Java's way of saying "data-file" (object-serialization))</i>, to write the Vector-Class to a file in a single line of code.  This utilizes Java's
        object-serialization code, compression code, and file-io code in a single method, efficiently.</div>
        </li>
        </ul>
        </div>
        <div class="summary">
        <ul class="blockList">
        <li class="blockList">
        <!-- ======== CONSTRUCTOR SUMMARY ======== -->
        <ul class="blockList">
        

        NOTE: An example of what this looks like would include the entire information & description that sits at the top of any Java Doc Class web-page, and likely would 'overflow' the look of this desciption box, so an image is not provided here.
        Parameters:
        javaDocHTMLCIETPage - This should be a vectorized-HTML Java-Doc Generated Documentation Page for a CIET (Class, Interface, or Enumerated-Type). Load a Vector of HTMLNode for JavaDoc generated page the exact same way that any other HTML Page is vectorized into TagNode, TextNode, and CommentNode.
        Returns:
        A '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, ... to the class-description section at the top of the page.

        NOTE: If any insertion of HTML is going to happen, it is usually better to insert such elements inside of an <LI>...</LI> pair inside the HTML Un-Ordered List - which is the only element inside the HTML DIV element in a javadoc generated HTML class-description page.
        See Also:
        dividerInsideDescriptionAtTop(Vector), InnerTagFindInclusive, TextComparitor
        Code:
        Exact Method Body:
         return InnerTagFindInclusive.first
             (javaDocHTMLCIETPage, "div", "class", TextComparitor.C, "description");
        
      • dividerInsideDescriptionAtTop

        🡅  🡇    
        public static DotPair dividerInsideDescriptionAtTop​
                    (java.util.Vector<HTMLNode> javaDocHTMLCIETPage)
        
        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" (<DIV ...> </DIV>) element. If, by some chance, a programmer has decided to insert HTML into the top of an HTML java-doc class-description file, and he 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 is not formatted the same way, using the same fonts as the rest of the text in the class-description

        SUMMARY: If a programmer wants to 'borrow' or 'inherit' the style & font assignments that are assigned by the CSS definition to the HTML text being inserted, use method:

        Java Method Signature:
        public static DotPair dividerInsideDescriptionAtTop(Vector<HTMLNode> javaDocHTMLCIETPage)
        

        Rather than the method:

        Java Method Signature:
        public static DotPair descriptionAtTop(Vector<HTMLNode> javaDocHTMLCIETPage)
        

        Choosing a class with a smaller yellow-boxed description, the HTML for the 'Description' <DIV> element looks as follows, for class Torello.HTML.Tools.Images.IF

        HTML Elements:
            <!-- In Java-Doc Generated HTML-Description Web-Pages, the "Description Divider" HTML looks like: -->
        <div class="block"><CODE>IF (Image Format) - Documentation.</CODE><BR/><BR/>
            This is just an enumerated-type used to ensure proper parameter-requests when downloading images.
            The type provides a simple means for storing words such as <code>'jpg,' 'png,' 'gif,' etc...</code>
            when attempting to download images.
            </div>
        


        The above HTML, when rendered with CSS (and upgrade tags), looks like:



        IF (Image Format) - Documentation.

        This is just an enumerated-type used to ensure proper parameter-requests when downloading images. The type provides a simple means for storing words such as 'jpg,' 'png,' 'gif,' etc... when attempting to download images.



        Parameters:
        javaDocHTMLCIETPage - This should be a vectorized-HTML Java-Doc Generated Documentation Page for a CIET (Class, Interface, or Enumerated-Type). Load a Vector of HTMLNode for JavaDoc generated page the exact same way that any other HTML Page is vectorized into TagNode, TextNode, and CommentNode.
        Returns:
        A '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, ... to the HTML <DIV CLASS='block'>...</DIV> class-description section at the top of the page.
        See Also:
        descriptionAtTop(Vector), InnerTagFindInclusive, TextComparitor
        Code:
        Exact Method Body:
         DotPair dp = descriptionAtTop(javaDocHTMLCIETPage);
        
         if (dp == null) return null;
        
         return InnerTagFindInclusive.first
             (javaDocHTMLCIETPage, dp.start, dp.end + 1, "div", "class", TextComparitor.C, "block");
        
      • title

        🡅  🡇    
        public static DotPair title​
                    (java.util.Vector<HTMLNode> javaDocHTMLCIETPage)
        
        This returns a DotPair (start & 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:

        HTML Elements:
        <!-- In any Java-Doc Generated HTML-Description Web-Page, the "Title" HTML looks like this: -->
        <h2 title="Class HTMLNode" class="title">Class HTMLNode</h2>
        


        The above HTML, when rendered with CSS (and upgrade tags), looks like:



        Class HTMLNode        




        Parameters:
        javaDocHTMLCIETPage - This should be a vectorized-HTML Java-Doc Generated Documentation Page for a CIET (Class, Interface, or Enumerated-Type). Load a Vector of HTMLNode for JavaDoc generated page the exact same way that any other HTML Page is vectorized into TagNode, TextNode, and CommentNode.
        Returns:
        A 'DotPair' pointer that holds pointers to the starting-position and ending-position in a vectorized-html web-page of the "title" (<h2 title="Class HTMLNode" class="title"> ... title ...</h2>) for any class, interface or enumerated-type JavaDoc Generated Web-Page.
        See Also:
        CommentNodeFind, InnerTagFindInclusive, TextComparitor
        Code:
        Exact Method Body:
         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");
        
      • titleAsString

        🡅  🡇    
        public static java.lang.String titleAsString​
                    (java.util.Vector<HTMLNode> javaDocHTMLCIETPage)
        
        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:

        HTML Elements:
        <!-- In any Java-Doc Generated HTML-Description Web-Page, the "Title" HTML looks like this: -->
        <h2 title="Class HTMLNode" class="title">Class HTMLNode</h2>
        


        The above HTML, when rendered with CSS (and upgrade tags), looks like:



        Class HTMLNode        




        Parameters:
        javaDocHTMLCIETPage - This should be a vectorized-HTML Java-Doc Generated Documentation Page for a CIET (Class, Interface, or Enumerated-Type). Load a Vector of HTMLNode for JavaDoc generated page the exact same way that any other HTML Page is vectorized into TagNode, TextNode, and CommentNode.
        Returns:
        A String that contains the actual text inside the "title" (<h2 title="Class HTMLNode" class="title"> ... title ...</h2>) for any class, interface or enumerated-type JavaDoc Generated Web-Page.
        See Also:
        Util.textNodesString(Vector), CommentNodeFind, InnerTagFindInclusive, TextComparitor
        Code:
        Exact Method Body:
         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));
        
      • inheritance

        🡅  🡇    
        public static java.util.Vector<SubSectioninheritance​
                    (java.util.Vector<HTMLNode> javaDocHTMLCIETPage)
        
        This returns a DotPair (start & 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:

        HTML Elements:
        <!-- In Java-Doc Generated HTML-Description Web-Pages: The "Inheritance List" HTML -->
        <!-- In this case, "class CommentNode" (which inherits from HTMLNode) is used      -->
        <ul class='inheritance'>
        <li>java.lang.Object</li>
        <li>
        <ul class='inheritance'>
        <li><a href="HTMLNode.html" title="class in Torello.HTML">Torello.HTML.HTMLNode</a></li>
        <li>
        <ul class='inheritance'>
        <li>Torello.HTML.CommentNode</li>
        </ul>
        </li>
        </ul>
        </li>
        </ul>
        


        The above HTML, when rendered with CSS (and upgrade tags), looks like:



        • java.lang.Object
          • Torello.HTML.HTMLNode
            • Torello.HTML.CommentNode



        Parameters:
        javaDocHTMLCIETPage - This should be a vectorized-HTML Java-Doc Generated Documentation Page for a CIET (Class, Interface, or Enumerated-Type). Load a Vector of HTMLNode for JavaDoc generated page the exact same way that any other HTML Page is vectorized into TagNode, TextNode, and CommentNode.
        Returns:
        A 'DotPair' pointer that holds pointers to the starting-position and ending-position in a vectorized-html web-page of the "inheritance Unordered List" (<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 Also:
        CommentNodeFind, InnerTagPeekInclusive, TextComparitor
        Code:
        Exact Method Body:
         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");
        
      • packageInfo

        🡅  🡇    
        public static DotPair packageInfo​
                    (java.util.Vector<HTMLNode> javaDocHTMLCIETPage)
        
        This returns a DotPair (start & end integer vector-index pointers) to the HTML Divider-Element ("<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:

        HTML Elements:
        <!-- In Java-Doc Generated HTML-Description Web-Pages, the "Containing Package" HTML looks like: -->
        <div class="subTitle">Package&nbsp;<a href="package-summary.html">Torello.HTML.Tools.JavaDoc</a></div>
        


        The above HTML, when rendered with CSS (and upgrade tags), looks like:

        Parameters:
        javaDocHTMLCIETPage - This should be a vectorized-HTML Java-Doc Generated Documentation Page for a CIET (Class, Interface, or Enumerated-Type). Load a Vector of HTMLNode for JavaDoc generated page the exact same way that any other HTML Page is vectorized into TagNode, TextNode, and CommentNode.
        Returns:
        A 'DotPair' pointer that holds pointers to the starting-position and ending-position in a vectorized-html web-page of the "Package Information" (<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 Also:
        CommentNodeFind, InnerTagFindInclusive, TextComparitor
        Code:
        Exact Method Body:
         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");
        
      • packageInfoAsString

        🡅  🡇    
        public static java.lang.String packageInfoAsString​
                    (java.util.Vector<HTMLNode> javaDocHTMLCIETPage)
        
        Rather than returning an vectorized-html sublist - which is what method 'package(Vector<HTMLNode>)' does - this method finds the "Package Name" itself and returns that as a regular java-string. This operation can be performed on a class, interface, enumerated-type etc... 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:

        HTML Elements:
        <!-- In Java-Doc Generated HTML-Description Web-Pages, the "Containing Package" HTML looks like: -->
        <div class="subTitle">Torello.HTML.Tools.JavaDoc</div>
        


        The above HTML, when rendered with CSS (and upgrade tags), looks like:

        Parameters:
        javaDocHTMLCIETPage - This should be a vectorized-HTML Java-Doc Generated Documentation Page for a CIET (Class, Interface, or Enumerated-Type). Load a Vector of HTMLNode for JavaDoc generated page the exact same way that any other HTML Page is vectorized into TagNode, TextNode, and CommentNode.
        Returns:
        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 Also:
        Util.textNodesString(Vector), CommentNodeFind, InnerTagGetInclusive, TextComparitor
        Code:
        Exact Method Body:
         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));
        
      • allTopDLs

        🡅    
        public static java.util.Vector<DotPairallTopDLs​
                    (java.util.Vector<HTMLNode> javaDocHTMLCIETPage)
        
        Returns all of the HTML Element "<DL> ... </DL>" sublists at the top of a CIET (Class, Interface, Enumerated-Type, Annotation etc..) 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 <DD> and <DT> definitions that are possible in this <DL> ... </DL> sublist occurring in the "Description-at-Top" of a javadoc web-pge.

        HTML Elements:
        <!-- 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>
        


        The above HTML, when rendered with CSS (and upgrade tags), looks like:



        All Implemented Interfaces:
        java.io.Serializable, java.lang.CharSequence, java.lang.Cloneable, java.lang.Comparable<CommentNode>



        Parameters:
        javaDocHTMLCIETPage - This should be a vectorized-HTML Java-Doc Generated Documentation Page for a CIET (Class, Interface, or Enumerated-Type). Load a Vector of HTMLNode for JavaDoc generated page the exact same way that any other HTML Page is vectorized into TagNode, TextNode, and CommentNode.
        See Also:
        CommentNodeFind, TagNodeFindInclusive, TextComparitor
        Code:
        Exact Method Body:
         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");