Class DetailsParts


  • public class DetailsParts
    extends java.lang.Object
    Java Doc HTML-File Reader: Find and retrieve the various parts of any Java Doc CIET File Details Section.

    This will scour and retrieve the parts of a vectorized-HTML Java Documentation File "Details Section" item for it's various sub-parts. Each JavaDoc generated HTML Page 'Details' contains some or all of the following sections:

    • Name
    • Signature
    • Description
    • Parameter Descriptions
    • Throws Types and Explanations
    • A 'see further' list of links
    • Returns Information
    • etc...

    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.


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
  • 13 Method(s), 13 declared static
  • 0 Field(s)


    • Method Detail

      • name

        🡇    
        public static DotPair name​
                    (java.util.Vector<HTMLNode> javaDocDetailItemHTML)
        
        This should be the HTML sub-section of a JavaDoc '.html' page which describes the functionality of a single item in a java class. It can be retrieved by a call to HNLIIterator.next() (after retrieving the HTML Inclusive Iterator for a specific 'Details Section' - using class Details).

        This retrieves the name vectorized-HTML. The HTML Snippet Below depicts exactly what HTML is being retrieved.

        HTML Elements:
         <h4> [Name] </h4>
        


        The above HTML, when rendered with CSS, looks like:



        name




        Parameters:
        javaDocDetailItemHTML - This method should be used in conjunction with the Details sections for methods, fields, constructors etc... The details sections are the JavaDoc entries that describe how these entities work, using HTML. By finding the location of the HTML for each part of the description text, that HTML may be decorated with CSS, or modified by the user with any customizations needed.
        Returns:
        DotPair pointing to HTML for the name part.
        See Also:
        TagNodeFindInclusive
        Code:
        Exact Method Body:
         return TagNodeFindInclusive.first(javaDocDetailItemHTML, "h4");
        
      • signature

        🡅  🡇    
        public static DotPair signature​
                    (java.util.Vector<HTMLNode> javaDocDetailItemHTML)
        
        This should be the HTML sub-section of a JavaDoc '.html' page which describes the functionality of a single item in a java class. It can be retrieved by a call to HNLIIterator.next() (after retrieving the HTML Inclusive Iterator for a specific 'Details Section' - using class Details).

        This retrieves the Signature vectorized-HTML. The HTML Snippet Below depicts exactly what HTML is being retrieved.

        HTML Elements:
         <h4> [Name] </h4>
         <pre class="xxxSignature"> ... </pre>
        


        The above HTML, when rendered with CSS, looks like:



        public static DotPair name​
                (java.util.Vector<HTMLNode> javaDocDetailItemHTML)
        



        Parameters:
        javaDocDetailItemHTML - This method should be used in conjunction with the Details sections for methods, fields, constructors etc... The details sections are the JavaDoc entries that describe how these entities work, using HTML. By finding the location of the HTML for each part of the description text, that HTML may be decorated with CSS, or modified by the user with any customizations needed.
        Returns:
        DotPair pointing to HTML for the Signature part.
        See Also:
        TagNodeFindInclusive
        Code:
        Exact Method Body:
         return TagNodeFindInclusive.first(javaDocDetailItemHTML, "pre");
        
      • description

        🡅  🡇    
        public static DotPair description​
                    (java.util.Vector<HTMLNode> javaDocDetailItemHTML)
        
        This should be the HTML sub-section of a JavaDoc '.html' page which describes the functionality of a single item in a java class. It can be retrieved by a call to HNLIIterator.next() (after retrieving the HTML Inclusive Iterator for a specific 'Details Section' - using class Details).

        This retrieves the Description vectorized-HTML. The HTML Snippet Below depicts exactly what HTML is being retrieved.

        HTML Elements:
         <div class="block"> ... [Textual Description of Item] ... </div>
        


        The above HTML, when rendered with CSS, looks like:



          
        -- Some Method, Field, Constructor etc... 'Detail Description' --



        Parameters:
        javaDocDetailItemHTML - This method should be used in conjunction with the Details sections for methods, fields, constructors etc... The details sections are the JavaDoc entries that describe how these entities work, using HTML. By finding the location of the HTML for each part of the description text, that HTML may be decorated with CSS, or modified by the user with any customizations needed.
        Returns:
        DotPair pointing to HTML for the Description part.

        Null will be returned if this HTML CIET description page for the item that is passed does not contain a 'Description' section.
        See Also:
        InnerTagFindInclusive
        Code:
        Exact Method Body:
         return InnerTagFindInclusive.first
             (javaDocDetailItemHTML, "div", "class", TextComparitor.C, "block");
        
      • parameters

        🡅  🡇    
        public static DotPair parameters​
                    (java.util.Vector<HTMLNode> javaDocDetailItemHTML)
        
        This should be the HTML sub-section of a JavaDoc '.html' page which describes the functionality of a single item in a java class. It can be retrieved by a call to HNLIIterator.next() (after retrieving the HTML Inclusive Iterator for a specific 'Details Section' - using class Details).

        This retrieves the Parameters: vectorized-HTML. The HTML Snippet Below depicts exactly what HTML is being retrieved.

        HTML Elements:
         <dt><span class="paramLabel">Parameters:</span></dt>
         <dd>...
        


        The above HTML, when rendered with CSS, looks like:

        Parameters:
        Parameters:
        javaDocDetailItemHTML - This method should be used in conjunction with the Details sections for methods, fields, constructors etc... The details sections are the JavaDoc entries that describe how these entities work, using HTML. By finding the location of the HTML for each part of the description text, that HTML may be decorated with CSS, or modified by the user with any customizations needed.
        Returns:
        DotPair pointing to HTML for the 'Parameters:' part.

        Null will be returned if this HTML CIET description page for the item that is passed does not contain a 'Parameters:' section.
        See Also:
        getParametersSpanSection(Vector, boolean)
        Code:
        Exact Method Body:
         return getParametersSpanSection(javaDocDetailItemHTML, false);
        
      • typeParameters

        🡅  🡇    
        public static DotPair typeParameters​
                    (java.util.Vector<HTMLNode> javaDocDetailItemHTML)
        
        This should be the HTML sub-section of a JavaDoc '.html' page which describes the functionality of a single item in a java class. It can be retrieved by a call to HNLIIterator.next() (after retrieving the HTML Inclusive Iterator for a specific 'Details Section' - using class Details).

        This retrieves the Type Parameters: vectorized-HTML. The HTML Snippet Below depicts exactly what HTML is being retrieved.

        HTML Elements:
         <dt><span class="paramLabel">Type Parameters:</span></dt>
         <dd>...
        


        The above HTML, when rendered with CSS, looks like:

        Type Parameters:
        Parameters:
        javaDocDetailItemHTML - This method should be used in conjunction with the Details sections for methods, fields, constructors etc... The details sections are the JavaDoc entries that describe how these entities work, using HTML. By finding the location of the HTML for each part of the description text, that HTML may be decorated with CSS, or modified by the user with any customizations needed.
        Returns:
        DotPair pointing to HTML for the 'Type Parameters:' part.

        Null will be returned if this HTML CIET description page for the item that is passed does not contain a 'Type Parameters:' section.
        See Also:
        getParametersSpanSection(Vector, boolean)
        Code:
        Exact Method Body:
         return getParametersSpanSection(javaDocDetailItemHTML, true);
        
      • returns

        🡅  🡇    
        public static DotPair returns​
                    (java.util.Vector<HTMLNode> javaDocDetailItemHTML)
        
        This should be the HTML sub-section of a JavaDoc '.html' page which describes the functionality of a single item in a java class. It can be retrieved by a call to HNLIIterator.next() (after retrieving the HTML Inclusive Iterator for a specific 'Details Section' - using class Details).

        This retrieves the Returns: vectorized-HTML. The HTML Snippet Below depicts exactly what HTML is being retrieved.

        HTML Elements:
         <dt><span class="returnLabel">Returns:</span></dt>
         <dd>...
        


        The above HTML, when rendered with CSS, looks like:

        Returns:
        Parameters:
        javaDocDetailItemHTML - This method should be used in conjunction with the Details sections for methods, fields, constructors etc... The details sections are the JavaDoc entries that describe how these entities work, using HTML. By finding the location of the HTML for each part of the description text, that HTML may be decorated with CSS, or modified by the user with any customizations needed.
        Returns:
        DotPair pointing to HTML for the 'Returns:' part.

        Null will be returned if this HTML class description page for the item that is passed does not contain a 'Returns:' section.
        See Also:
        getSpanSection(Vector, String)
        Code:
        Exact Method Body:
         return getSpanSection(javaDocDetailItemHTML, "returnLabel");
        
      • throwing

        🡅  🡇    
        public static DotPair throwing​
                    (java.util.Vector<HTMLNode> javaDocDetailItemHTML)
        
        This should be the HTML sub-section of a JavaDoc '.html' page which describes the functionality of a single item in a java class. It can be retrieved by a call to HNLIIterator.next() (after retrieving the HTML Inclusive Iterator for a specific 'Details Section' - using class Details).

        This retrieves the Throws: vectorized-HTML. The HTML Snippet Below depicts exactly what HTML is being retrieved.

        HTML Elements:
         <dt><span class="throwsLabel">Throws:</span></dt>
         <dd>...
        


        The above HTML, when rendered with CSS, looks like:

        Throws:
        Parameters:
        javaDocDetailItemHTML - This method should be used in conjunction with the Details sections for methods, fields, constructors etc... The details sections are the JavaDoc entries that describe how these entities work, using HTML. By finding the location of the HTML for each part of the description text, that HTML may be decorated with CSS, or modified by the user with any customizations needed.
        Returns:
        DotPair pointing to HTML for the 'Throws:' part.

        Null will be returned if this HTML class description page for the item that is passed does not contain a 'Throws:' section.
        See Also:
        getSpanSection(Vector, String)
        Code:
        Exact Method Body:
         return getSpanSection(javaDocDetailItemHTML, "throwsLabel");
        
      • see

        🡅  🡇    
        public static DotPair see​
                    (java.util.Vector<HTMLNode> javaDocDetailItemHTML)
        
        This should be the HTML sub-section of a JavaDoc '.html' page which describes the functionality of a single item in a java class. It can be retrieved by a call to HNLIIterator.next() (after retrieving the HTML Inclusive Iterator for a specific 'Details Section' - using class Details).

        This retrieves the 'See Also' vectorized-HTML. The HTML Snippet Below depicts exactly what HTML is being retrieved.

        HTML Elements:
         <dt><span class="seeLabel">See Also:</span></dt>
         <dd>...
        


        The above HTML, when rendered with CSS, looks like:

        See Also:
        Parameters:
        javaDocDetailItemHTML - This method should be used in conjunction with the Details sections for methods, fields, constructors etc... The details sections are the JavaDoc entries that describe how these entities work, using HTML. By finding the location of the HTML for each part of the description text, that HTML may be decorated with CSS, or modified by the user with any customizations needed.
        Returns:
        DotPair pointing to HTML for the 'See Also:' part.

        Null will be returned if this HTML class description page for the item that is passed does not contain a 'See Also:' section.
        See Also:
        getSpanSection(Vector, String)
        Code:
        Exact Method Body:
         return getSpanSection(javaDocDetailItemHTML, "seeLabel");
        
      • overrideSpecify

        🡅  🡇    
        public static java.util.stream.Stream<DotPairoverrideSpecify​
                    (java.util.Vector<HTMLNode> javaDocDetailItemHTML)
        
        This should be the HTML sub-section of a JavaDoc '.html' page which describes the functionality of a single item in a java class. It can be retrieved by a call to HNLIIterator.next() (after retrieving the HTML Inclusive Iterator for a specific 'Details Section' - using class Details).

        This retrieves the 'Specified By' and the 'Overrides' Vectorized-HTML. The HTML Snippet Below depicts exactly what HTML is being retrieved.

        HTML Elements:
         <dt><span class="overrideSpecifyLabel">Overrides:</span></dt>
         <dd>...
         
         <!-- There are two of these possible ("Overrides" and "Specified By") -->
         <dt><span class="overrideSpecifyLabel">Specified By:</span></dt>
         <dd>...
        


        The above HTML, when rendered with CSS, looks like:

        Overrides:
        Specified By:
        Parameters:
        javaDocDetailItemHTML - This method should be used in conjunction with the Details sections for methods, fields, constructors etc... The details sections are the JavaDoc entries that describe how these entities work, using HTML. By finding the location of the HTML for each part of the description text, that HTML may be decorated with CSS, or modified by the user with any customizations needed.
        Returns:
        A java.util.stream.Stream<DotPair> that contains a list of DotPair's each of which point to HTML for the 'overrideSpecifyLabel' part.

        An empty Stream will be returned if this HTML class description page for the item that is passed contains niether a 'Specified By' section, nor an 'Overrides' section.
        See Also:
        getSpanSections(Vector, String)
        Code:
        Exact Method Body:
         return getSpanSections(javaDocDetailItemHTML, "overrideSpecifyLabel");
        
      • defaultLabel

        🡅  🡇    
        public static DotPair defaultLabel​
                    (java.util.Vector<HTMLNode> javaDocAnnotationElemHTML)
        
        This should be the HTML sub-section of a JavaDoc '.html' page which describes the functionality of a single item in a java class. It can be retrieved by a call to HNLIIterator.next() (after retrieving the HTML Inclusive Iterator for a specific 'Details Section' - using class Details).

        This retrieves the "Default:" vectorized-HTML section. The HTML Snippet Below depicts exactly what HTML is being retrieved.

        HTML Elements:
         <dl>
         <dt>Default:</dt>
         <dd>{}</dd>
         </dl>
        


        The above HTML, when rendered with CSS, looks like:

        Default:
        Parameters:
        javaDocAnnotationElemHTML - This method should be used in conjunction with the Details sections for methods, fields, constructors etc... The details sections are the JavaDoc entries that describe how these entities work, using HTML. By finding the location of the HTML for each part of the description text, that HTML may be decorated with CSS, or modified by the user with any customizations needed.
        Returns:
        DotPair pointing to HTML for the 'Default:' part.

        Null will be returned if this HTML class description page for the Annotation-Element that is passed does not contain a 'Default:' section.
        See Also:
        TagNodeFindInclusive, TextNodeFind, Surrounding.first(Vector, int, String[])
        Code:
        Exact Method Body:
         // There is a surrounding "<DL>" element around the entire @returns, @see, @param, and
         // @throws section
         DotPair dlDP = TagNodeFindInclusive.first(javaDocAnnotationElemHTML, "dl");
        
         // If this was null, just return null, perhaps one day, this might ought to be an
         // exception throw.
         if (dlDP == null) return null;
        
         int defPos = TextNodeFind.first
             (javaDocAnnotationElemHTML, dlDP.start, dlDP.end, s -> s.equals("Default:"));
        
         if (defPos == -1) return null;
        
         DotPair dtDP = Surrounding.first(javaDocAnnotationElemHTML, defPos, "dt");
        
         return dtDP;
        
      • getSpanSection

        🡅  🡇    
        protected static DotPair getSpanSection​
                    (java.util.Vector<HTMLNode> javaDocDetailHTML,
                     java.lang.String sectionSpanClassName)
        
        This finds a the requested subsection identified by sectionSpanClassName.
        Parameters:
        javaDocDetailHTML - This should be the HTML sub-section of a JavaDoc page that describes the functionality of a single detailed-element in a java class.
        sectionSpanClassName - This is the name of the sub-section we are looking for. Valid values are limited to 'throwsLabel,' 'returnLabel' and also 'paramLabel.' These are three sections inside of an HTML method description from a Java-Doc generated HTML page.
        Returns:
        The pointers to the starting and ending index of the relevant section, or null if it were not found.
        See Also:
        TagNodeFindInclusive, InnerTagFind, TagNodeFind
        Code:
        Exact Method Body:
         // DetailsException.check(javaDocDetailHTML);
        
         // There is a surrounding "<DL>" element around the entire @returns, @see, @param, and
         // @throws section
         DotPair dlDP = TagNodeFindInclusive.first(javaDocDetailHTML, "dl");
        
         // If this was null, just return null, perhaps one day, this might ought to be an
         // exception throw.
         if (dlDP == null) return null;
        
         // The @see, @param, @throws, @returns, etc... starts with a <SPAN CLASS="seeLabel">
         // ... (or throwsLabel, returnLabel, paramLabel...)
         int spanPos = InnerTagFind.first(
             javaDocDetailHTML, dlDP.start, dlDP.end, "span", "class",
             TextComparitor.C, sectionSpanClassName
         );
        
         // If not found, return null;
         if (spanPos == -1) return null;
        
         // The particular section we are observing ends as soon as another section begins, or we
         // encounter a </DL> element.  a <DT> element implies a new section is starting.
        
         int dlPos = TagNodeFind.first(javaDocDetailHTML, spanPos, -1, TC.ClosingTags, "dl");
         int dtPos = TagNodeFind.first(javaDocDetailHTML, spanPos, -1, TC.OpeningTags, "dt");
        
         // 3 out of 4 times, a "new section begin" is how the previous section ends.  However, if
         // the section being observed is the last section, then a </DL> element will be found, and
         // the <DT> search will have returned a value of '-1'.  Since Math.min() is being, used,
         // the '-1' must be changed.
        
         if (dtPos == -1) dtPos = javaDocDetailHTML.size();
             // Set to maximum size, if not found.
        
         // Whichever comes first... </DL> or another <DT>
         int ePos = Math.min(dlPos, dtPos) - 1;
        
         // Back up through any TextNodes - which are usually just a '\n' newline character.
         while (! (javaDocDetailHTML.elementAt(ePos) instanceof TagNode)) ePos--;
        
         // NOTE: The element before the span-pos is the <DT> element.
         DotPair ret = new DotPair(spanPos - 1, ePos);
        
         HTMLNode start = javaDocDetailHTML.elementAt(ret.start);
         HTMLNode end = javaDocDetailHTML.elementAt(ret.end);
        
         if (    (! (start instanceof TagNode))
             ||  (! ((TagNode) start).tok.equals("dt"))
             ||  ((TagNode) start).isClosing
         )
             // YES, THIS WILL ULTIMATELY BE HANDLED / TREATED AS AN "UNEXPECTED ERROR" BY THE
             // MAIN & EXTRA FILES PROCESSOR.  THIS IS BECAUSE, IN MY CODE, THIS SHOULD NEVER HAPPEN,
             // AND IF IT DOES, IT COULD MEAN THAT JAVADOC, ITSELF, CHANGED.  THAT'S MY FAULT, NOT
             // THEIRS
             throw new DetailsException(
                 "Something went wrong.  Not able to return a proper " + sectionSpanClassName + ".  " +
                 "First node was not a <DT> Element: [" + start.getClass().getSimpleName() + ": " +
                 start.str + "]"
             );
        
         if (    (! (end instanceof TagNode))
             ||  (! ((TagNode) end).tok.equals("dd"))
             ||  (! ((TagNode) end).isClosing)
         )
             throw new DetailsException(
                 "Something went wrong.  Not able to return a proper " + sectionSpanClassName + ".  " +
                 "Last node was not a </DD> Element: [" + end.getClass().getSimpleName() + ": " +
                 end.str + "]"
             );
        
         return ret;
        
      • getSpanSections

        🡅  🡇    
        protected static java.util.stream.Stream<DotPairgetSpanSections​
                    (java.util.Vector<HTMLNode> javaDocDetailHTML,
                     java.lang.String sectionSpanClassName)
        
        This finds a the requested subsection identified by sectionSpanClassName. As of the writing of this method, the only proper-input seems to be the 'overrideSpecifyLabel'. This method will return all instances of the HTML <SPAN CLASS=sectionSpanClassName>, not just the first!
        Parameters:
        javaDocDetailHTML - This should be the HTML sub-section of a JavaDoc page that describes the functionality of a single detailed-element in a java class.
        sectionSpanClassName - This is the name of the sub-section we are looking for. The valid <SPAN> elements, right now, consist solely of the 'overrideSpecifyLabel' spanner!
        Returns:
        A java.util.stream.Stream that lists the pointers to the starting and ending indices of the relevant section, or an empty Stream if none were found.
        See Also:
        TagNodeFindInclusive, InnerTagFind, TagNodeFind
        Code:
        Exact Method Body:
         // DetailsException.check(javaDocDetailHTML);
        
         // There is a surrounding "<DL>" element around the entire @returns, @see, @param, and
         // @throws section
         DotPair dlDP = TagNodeFindInclusive.first(javaDocDetailHTML, "dl");
        
         // If this was null, just return null, perhaps one day, this might ought to be an
         // exception throw.
         if (dlDP == null) return Stream.empty();
        
         // The @see, @param, @throws, @returns, etc... starts with a <SPAN CLASS="seeLabel">
         // ... (or throwsLabel, returnLabel, paramLabel...)
         int[] spanPosArr = InnerTagFind.all(
             javaDocDetailHTML, dlDP.start, dlDP.end, "span", "class",
             TextComparitor.C, sectionSpanClassName
         );
        
         // If not found, return null;
         if (spanPosArr.length == 0) return Stream.empty();
        
         // We have to keep the list of "Results" we find in a Stream<DotPair>
         Stream.Builder<DotPair> b = Stream.builder();
        
         for (int spanPos : spanPosArr)
         {
             // The particular section we are observing ends as soon as another section begins, or we
             // encounter a </DL> element.  a <DT> element implies a new section is starting.
        
             int dlPos = TagNodeFind.first(javaDocDetailHTML, spanPos, -1, TC.ClosingTags, "dl");
             int dtPos = TagNodeFind.first(javaDocDetailHTML, spanPos, -1, TC.OpeningTags, "dt");
        
             // 3 out of 4 times, a "new section begin" is how the previous section ends.  However, if
             // the section being observed is the last section, then a </DL> element will be found, and
             // the <DT> search will have returned a value of '-1'.  Since Math.min() is being, used,
             // the '-1' must be changed.
        
             if (dtPos == -1) dtPos = javaDocDetailHTML.size();
                 // Set to maximum size, if not found.
        
             // Whichever comes first... </DL> or another <DT>
             int ePos = Math.min(dlPos, dtPos) - 1;
        
             // Back up through any TextNodes - which are usually just a '\n' newline character.
             while (! (javaDocDetailHTML.elementAt(ePos) instanceof TagNode)) ePos--;
        
             // NOTE: The element before the span-pos is the <DT> element.
             DotPair dp = new DotPair(spanPos - 1, ePos);
        
             HTMLNode start = javaDocDetailHTML.elementAt(dp.start);
             HTMLNode end = javaDocDetailHTML.elementAt(dp.end);
        
             if (    (! (start instanceof TagNode))
                 ||  (! ((TagNode) start).tok.equals("dt"))
                 ||  ((TagNode) start).isClosing
             )
                 // YES, THIS WILL ULTIMATELY BE HANDLED / TREATED AS AN "UNEXPECTED ERROR" BY THE
                 // MAIN & EXTRA FILES PROCESSOR.  THIS IS BECAUSE, IN MY CODE, THIS SHOULD NEVER HAPPEN,
                 // AND IF IT DOES, IT COULD MEAN THAT JAVADOC, ITSELF, CHANGED.  THAT'S MY FAULT, NOT
                 // THEIRS
                 throw new DetailsException(
                     "Something went wrong.  Not able to return a proper " + sectionSpanClassName + ".  " +
                     "First node was not a <DT> Element: [" + start.getClass().getSimpleName() + ": " +
                     start.str + "]"
                 );
        
             if (    (! (end instanceof TagNode))
                 ||  (! ((TagNode) end).tok.equals("dd"))
                 ||  (! ((TagNode) end).isClosing)
             )
                 throw new DetailsException(
                     "Something went wrong.  Not able to return a proper " + sectionSpanClassName + ".  " +
                     "Last node was not a </DD> Element: [" + end.getClass().getSimpleName() + ": " +
                     end.str + "]"
                 );
        
             b.accept(dp);
         }
        
         return b.build();
        
      • getParametersSpanSection

        🡅    
        protected static DotPair getParametersSpanSection​
                    (java.util.Vector<HTMLNode> javaDocDetailHTML,
                     boolean typeParameters)
        
        This finds a the requested subsection identified by "paramLabel". There are two types of parameters - normal parameters, and type parameters. Both use the same CSS class for identifying them on the page.

        NOTE: This method is nearly identical to getSpanSection(Vector, String), and performs the same operation. Here, only the "Parameters" or the "Type Parameters" definition lists may be retrieved.
        Parameters:
        javaDocDetailHTML - This should be the HTML sub-section of a JavaDoc page that describes the functionality of a single detailed-element in a java class.
        typeParameters - This boolean, when pass TRUE is meant to request that the "Type Parameters" <DL> be retrieved. When FALSE, this method will look for the regular "Parameters" HTML <DL>.
        Returns:
        The pointers to the starting and ending index of the relevant section, or null if it were not found.
        See Also:
        TagNodeFindInclusive, InnerTagFind, TagNodeFind
        Code:
        Exact Method Body:
         // DetailsException.check(javaDocDetailHTML);
        
         // There is a surrounding "<DL>" element around the entire @param section
         DotPair dlDP = TagNodeFindInclusive.first(javaDocDetailHTML, "dl");
        
         // If this was null, just return null
         if (dlDP == null) return null;
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // NOTE: This part of the method differs from
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        
         // Both the 'Type Parameters' and the regular 'Parameters' secrions are marked by a 
         // <SPAN CLASS="paramLabel">
         int[] spanPosArr = InnerTagFind.all(
             javaDocDetailHTML, dlDP.start, dlDP.end, "span", "class",
             TextComparitor.C, "paramLabel"
         );
        
         // If there aren't any HTML SPAN elements having class=paramLabel, return null;
         if (spanPosArr.length == 0) return null;
        
         String  expectedText    = typeParameters ? "Type Parameters:" : "Parameters:";
         int     spanPos         = -1;
        
         for (int pos : spanPosArr)
             if (javaDocDetailHTML.elementAt(pos + 1).str.equals(expectedText))
                 spanPos = pos;
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // The rest of this is identical tp "getSpanSection(...)"
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        
         // If not found, return null;
         if (spanPos == -1) return null;
        
         // The particular section we are observing ends as soon as another section begins, or we
         // encounter a </DL> element.  a <DT> element implies a new section is starting.
        
         int dlPos = TagNodeFind.first(javaDocDetailHTML, spanPos, -1, TC.ClosingTags, "dl");
         int dtPos = TagNodeFind.first(javaDocDetailHTML, spanPos, -1, TC.OpeningTags, "dt");
        
         // 3 out of 4 times, a "new section begin" is how the previous section ends.  However, if
         // the section being observed is the last section, then a </DL> element will be found, and
         // the <DT> search will have returned a value of '-1'.  Since Math.min() is being, used,
         // the '-1' must be changed.
        
         if (dtPos == -1) dtPos = javaDocDetailHTML.size();
         // Set to maximum size, if not found.
        
         // Whichever comes first... </DL> or another <DT>
         int ePos = Math.min(dlPos, dtPos) - 1;
        
         // Back up through any TextNodes - which are usually just a '\n' newline character.
         while (! (javaDocDetailHTML.elementAt(ePos) instanceof TagNode)) ePos--;
        
         // NOTE: The element before the span-pos is the <DT> element.
         DotPair ret = new DotPair(spanPos - 1, ePos);
        
         HTMLNode start = javaDocDetailHTML.elementAt(ret.start);
         HTMLNode end = javaDocDetailHTML.elementAt(ret.end);
        
         if (    (! (start instanceof TagNode))
             ||  (! ((TagNode) start).tok.equals("dt"))
             ||  ((TagNode) start).isClosing
         )
             // YES, THIS WILL ULTIMATELY BE HANDLED / TREATED AS AN "UNEXPECTED ERROR" BY THE
             // MAIN & EXTRA FILES PROCESSOR.  THIS IS BECAUSE, IN MY CODE, THIS SHOULD NEVER HAPPEN,
             // AND IF IT DOES, IT COULD MEAN THAT JAVADOC, ITSELF, CHANGED.  THAT'S MY FAULT, NOT
             // THEIRS
             throw new DetailsException(
                 "Something went wrong.  Not able to return a proper 'paramLabel'.  " +
                 "First node was not a <DT> Element: [" + start.getClass().getSimpleName() + ": " +
                 start.str + "]"
             );
        
         if (    (! (end instanceof TagNode))
             ||  (! ((TagNode) end).tok.equals("dd"))
             ||  (! ((TagNode) end).isClosing)
         )
             throw new DetailsException(
                 "Something went wrong.  Not able to return a proper 'paramLabel'.  " +
                 "Last node was not a </DD> Element: [" + end.getClass().getSimpleName() + ": " +
                 end.str + "]"
             );
        
         return ret;