Class DetailsPartField

  • public class DetailsPartField
extends java.lang.Object
    JavaDoc Details-Part Field - Documentation.

    This will scour and retrieve the parts of a vectorized-HTML Java Class Documentation Field Definition for it's various sub-parts. Each JavaDoc generated HTML Page 'Field' details contains some or all of the following sections:

    • Field Name (always the same, i.e. the name of the class)
    • Field Signature
    • Field Description
    • A 'see further' list of links

    The methods in this class will return the subsection as a DotPair pointer-pair, and it shall return null if this section was not found. These methods will throw an DetailsException if passed an invalid Method-HTML-Description part.

    USES, BENEFITS: Primarily, the three classes: DetailsPartConstructor, DetailsPartMethod and DetailsPartField is to help the user avoid trolling through the HTML-Source output of the JavaDoc utility. Having already done that, providing a simple method that can return an index-pointer (vector-location) to the entry or item in a standard JavaDoc Output Page - one could easily automate a build script to insert nicer, pretty-printed HTML-based explanations to further improve their code's documentation.

    Static (Functional) API: The methods in this class are all (100%) defined with the Java Key-Word / Key-Concept 'static'. Furthermore, there is no way to obtain an instance of this class, because there are no public (nor private) constructors. Java's Spring-Boot, MVC feature is *not* utilized because it flies directly in the face of the light-weight data-classes philosophy. This has many advantages over the rather ornate Component Annotations (@Component, @Service, @AutoWired, etc... 'Java Beans') syntax:

    • The methods here use the key-word 'static' which means (by implication) that there is no internal-state. Without any 'internal state' there is no need for constructors in the first place! (This is often the complaint by MVC Programmers).
    • A 'Static' (Functional-Programming) API expects to use fewer data-classes, and light-weight data-classes, making it easier to understand and to program.
    • The Vectorized HTML data-model allows more user-control over HTML parse, search, update & scrape. Also, memory management, memory leakage, and the Java Garbage Collector ought to be intelligible through the 'reuse' of the standard JDK class Vector for storing HTML Web-Page data.

    The power that object-oriented programming extends to a user is (mostly) limited to data-representation. Thinking of "Services" as "Objects" (Spring-MVC, 'Java Beans') is somewhat 'over-applying' the Object Oriented Programming Model. Like most classes in the Java-HTML JAR Library, this class backtracks to a more C-Styled Functional Programming Model (no Objects) - by re-using (quite profusely) the key-word static with all of its methods, and by sticking to Java's well-understood class Vector

    Internal-State: A user may click on this class' source code (see link below) to view any and all internally defined fields class. A cursory inspection of the code would prove that this class has precisely zero internally defined global fields (Spaghetti). All variables used by the methods in this class are local fields only, and therefore this class ought to be though of as 'state-less'.



    • Method Detail

      • name

        public static DotPair name​(java.util.Vector<HTMLNode> javaDocFieldHTML)
        This method should be used in conjunction with Details.fieldDetailsIterator(javaDocPage);. The Iterator returned will retrieve JavaDoc entries for the 'Field Descriptions' in a JavaDoc generated vectorized-HTML web-page.

        This retrieves the field name vectorized-HTML.

        HTML Elements:
        1
2
         <h4> [Field Name] </h4>
        Parameters:
        javaDocFieldHTML - This should be the HTML sub-section of a JavaDoc '.html' page which describes the functionality of a single Field in a java class. It can be retrieved by a call to HNLIIterator.next()
        Returns:
        DotPair pointing to HTML for the 'Field Name' part.
        Throws:
        DetailsException - This does a quick check on each invocation to ensure that the vectorized-HTML parameter is actually a 'Field Details' section, retrieved via Details.fieldDetailsIterator(). The section may also be obtained manually (without using the Iterator), but the programmer must ensure the start and end-points are the same as those returned by the Iterator.
        See Also:
        DetailsException, TagNodeFindInclusive, Details.fieldDetailsIterator(Vector)
        Code:
        Exact Method Body:
        1
2
         DetailsException.check(javaDocFieldHTML);
 return TagNodeFindInclusive.first(javaDocFieldHTML, "h4");

      • signature

        public static DotPair signature​
            (java.util.Vector<HTMLNode> javaDocFieldHTML)
        This method should be used in conjunction with Details.fieldDetailsIterator(javaDocPage);. The Iterator returned will retrieve JavaDoc entries for the 'Field Descriptions' in a JavaDoc generated vectorized-HTML web-page.

        This retrieves the field signature vectorized-HTML.

        HTML Elements:
        1
2
3
         <h4> [Field Name] </h4>
 <pre> ... </pre>
        Parameters:
        javaDocFieldHTML - This should be the HTML sub-section of a JavaDoc '.html' page which describes the functionality of a single Field in a java class. It can be retrieved by a call to HNLIIterator.next()
        Returns:
        DotPair pointing to HTML for the 'Field Signature' part.
        Throws:
        DetailsException - This does a quick check on each invocation to ensure that the vectorized-HTML parameter is actually a 'Field Details' section, retrieved via Details.fieldDetailsIterator(). The section may also be obtained manually (without using the Iterator), but the programmer must ensure the start and end-points are the same as those returned by the Iterator.
        See Also:
        DetailsException, TagNodeFindInclusive, Details.fieldDetailsIterator(Vector)
        Code:
        Exact Method Body:
        1
2
         DetailsException.check(javaDocFieldHTML);
 return TagNodeFindInclusive.first(javaDocFieldHTML, "pre");

      • description

        public static DotPair description​
            (java.util.Vector<HTMLNode> javaDocFieldHTML)
        This method should be used in conjunction with Details.fieldDetailsIterator(javaDocPage);. The Iterator returned will retrieve JavaDoc entries for the 'Field Descriptions' in a JavaDoc generated vectorized-HTML web-page.

        This retrieves the field description vectorized-HTML.

        HTML Elements:
        1
2
         <div class="block"> ... [Textual Description of Field] ... </div>
        Parameters:
        javaDocFieldHTML - This should be the HTML sub-section of a JavaDoc '.html' page which describes the functionality of a single Field in a java class. It can be retrieved by a call to HNLIIterator.next()
        Returns:
        DotPair pointing to HTML for the 'Field Description' part.
        Throws:
        DetailsException - This does a quick check on each invocation to ensure that the vectorized-HTML parameter is actually a 'Field Details' section, retrieved via Details.fieldDetailsIterator(). The section may also be obtained manually (without using the Iterator), but the programmer must ensure the start and end-points are the same as those returned by the Iterator.
        See Also:
        DetailsException, InnerTagFindInclusive, Details.fieldDetailsIterator(Vector)
        Code:
        Exact Method Body:
        1
2
3
         DetailsException.check(javaDocFieldHTML);
 return InnerTagFindInclusive.first
     (javaDocFieldHTML, "div", "class", TextComparitor.C, "block");

      • see

        public static DotPair see​(java.util.Vector<HTMLNode> javaDocFieldHTML)
        This method should be used in conjunction with Details.fieldDetailsIterator(javaDocPage);. The Iterator returned will retrieve JavaDoc entries for the 'Field Descriptions' in a JavaDoc generated vectorized-HTML web-page.

        This retrieves the field see also vectorized-HTML.

        HTML Elements:
        1
2
3
         <dt><span class="seeLabel">See Also:</span></dt>
 <dd>...
        Parameters:
        javaDocFieldHTML - This should be the HTML sub-section of a JavaDoc '.html' page which describes the functionality of a single Field in a java class. It can be retrieved by a call to HNLIIterator.next()
        Returns:
        DotPair pointing to HTML for the 'Field See Also' part.

        Null will be returned if this HTML class description page for the Field that is passed does not contain a 'see also' section.
        Throws:
        DetailsException - This does a quick check on each invocation to ensure that the vectorized-HTML parameter is actually a 'Field Details' section, retrieved via Details.fieldDetailsIterator(). The section may also be obtained manually (without using the Iterator), but the programmer must ensure the start and end-points are the same as those returned by the Iterator.
        See Also:
        HELPER.getSpanSection(Vector, String)
        Code:
        Exact Method Body:
        1
         return HELPER.getSpanSection(javaDocFieldHTML, "seeLabel");

      • overrideSpecify

        public static DotPair overrideSpecify​
            (java.util.Vector<HTMLNode> javaDocFieldHTML)
        This method should be used in conjunction with Details.fieldDetailsIterator(javaDocPage);. The Iterator returned will retrieve JavaDoc entries for the 'Field Descriptions' in a JavaDoc generated vectorized-HTML web-page.

        This retrieves the field "Specified by" vectorized-HTML.

        HTML Elements:
        1
2
3
         <dt><span class="overrideSpecifyLabel">Overrides:</span></dt>
 <dd>...
        Parameters:
        javaDocFieldHTML - This should be the HTML sub-section of a JavaDoc '.html' page which describes the functionality of a single Field in a java class. It can be retrieved by a call to HNLIIterator.next()
        Returns:
        DotPair pointing to HTML for the 'Field Specified By' part.

        Null will be returned if this HTML class description page for the Field that is passed does not contain a 'specified by' section.
        Throws:
        DetailsException - This does a quick check on each invocation to ensure that the vectorized-HTML parameter is actually a 'Field Details' section, retrieved via Details.fieldDetailsIterator(). The section may also be obtained manually (without using the Iterator), but the programmer must ensure the start and end-points are the same as those returned by the Iterator.
        See Also:
        HELPER.getSpanSection(Vector, String)
        Code:
        Exact Method Body:
        1
         return HELPER.getSpanSection(javaDocFieldHTML, "overrideSpecifyLabel");