Class Locate


  • @Deprecated
    public class Locate
    extends java.lang.Object
    Deprecated.
    JavaDoc Locate - Documentation.

    Finds details and summary sections, based on an integer "index-pointer" (a node-location). When a method in this class is presented with a given node in a vectorized-html JavaDoc Generated HTML Documentation Page, the search will identify in which details section this node is located.

    This Java-Documentation Assistant Package has copious amounts of comments, itself. Possibly, this may seem like "Recursive Logic" (TLDR) - but since this package is used to improve the quality of code-comments, primarily by adding code-hiliting sections, providing examples really does seem important. The logic for how all this works (the code in this package) is trivial. However, because implementing these routines involves using many methods and classes from HTML.*; and HTML.NodeSearch.*; explaining each line of code to a new user who has not used anything in Torello...* explaining each line of code becomes important.

    This is a little similar to writing a C-Compiler or C++ Compiler using the C or C++ language In any case, there are numerous programming tutorial websites on the internet, and every one of them provides copious amounts of code-samples and code-snippets along with their detailed explanation. That is the primary goal of the HTML.Tools.JavaDoc.* package.

    This particular class simply accepts a vector index and returns a sub-list, as an instance of class DotPair, that contains the index (node-pointer) provided by a user. In the process of hiliting code-snippets in code comments, finding a code-snippet before knowing which method, field or constructor to which the snippet explains / applies means that searching for which summary or details the index belongs. This class will find what detail or summary section an index belongs Deprecation Note: This class is being deprecated, as the newer class "JavaDocHTMLFile" performs these operations.



    • Field Detail

      • METHOD

        public static final int METHOD
        Deprecated.
        A marker used to indicate that the return-value represents a Method-Section from a JavaDoc HTML page
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
        1
        public static final int METHOD = 1;
        
      • FIELD

        public static final int FIELD
        Deprecated.
        A marker used to indicate that the return-value represents a Field-Section from a JavaDoc HTML page
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
        1
        public static final int FIELD = 2;
        
      • CONSTRUCTOR

        public static final int CONSTRUCTOR
        Deprecated.
        A marker used to indicate that the return-value represents a Constructor-Section from a JavaDoc HTML page
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
        1
        public static final int CONSTRUCTOR = 3;
        
    • Method Detail

      • findDetails

        public static Ret2<DotPair,​java.lang.Integer> findDetails​
                    (java.util.Vector<HTMLNode> javaDocPage,
                     int index)
        
        Deprecated.
        This will search through any and all "Details" Sections of a Java-Doc Generated Web-Page to find which section encloses a particular index. For instance, if int index == 123 (which would be the one-hundred and twenty-third HTMLNode element of the vector-parameter 'javaDocPage', this method will request all field-details sections to see if any of the field-details portion of the HTML page contains this index. If this index does not point to any field-details portion of the passed parameter 'javaDocPage', then the methods will be searched, and afterwards the constructors. If this index-point does not match any details section of constructors, methods or fields - then this method shall return null.
        Parameters:
        javaDocPage - This should be a vectorized-HTML JavaDoc-Generated Web-Page.
        index - Any index that points to an element in javaDocPage. This may be any type of HTMLNode. Specifically, javaDocPage.elementAt(index) may contain an instanceof: TagNode, TextNode, or CommentNode.
        Returns:
        This will return the starting-position and ending-position of the identified Java-Doc details section as a DotPair. The second value of the Ret2 instance will take on the values of the public constants defined at the top of this page.

        • Ret2.a, a DotPair instance, and will contain the start and end index of the Details section returned
        • Ret2.b, will contain one of three values: Locate.METHOD, Locate.FIELD, or Locate.CONSTRUCTOR.


        NOTE: If this index does not pass the DotPair.isInside(index) for *any* details section then this method returns null.
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - If index is not between 0 and javaDocPage.size()
        Code:
        Exact Method Body:
         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
         if (index < 0) throw new ArrayIndexOutOfBoundsException
             (   "The index value you have passed is negative: [" + index + "]"  );
            
         if (index >= javaDocPage.size()) throw new ArrayIndexOutOfBoundsException
             (   "The index value you have passed [" + index + "], " +
                 "is greater than the length of the vector parameter: javaDocPage.size() = [" + javaDocPage.size() + "]" ); 
        
         DotPair dp;
        
         // This iterator will return DotPair (Sublist endpoint-boundaries) for every
         // "Field Details" section of a particular class, interface, or enumerated type of a
         // JavaDoc Generated HTML Page.  Search each sub-list to see if it contains the index
         // the user has provided to parameter "index."  If it is "insideOf" a field DotPair, 
         // return it.
         HNLIInclusive iter = Details.fieldDetailsIterator(javaDocPage);
         while (iter.hasNext())
             if ((dp = iter.nextDotPair()).isInside(index))
                 return new Ret2<DotPair, Integer>(dp, FIELD);
        
         // This iterator will do the same thing as the previous iterator, but will check
         // "Method Details" for each method defined in the HTML Page.  Make sure to pass the
         // "METHOD" constant field to let the user know that this Details section represents a
         // "Method Details"
         iter = Details.methodDetailsIterator(javaDocPage);
         while (iter.hasNext())
             if ((dp = iter.nextDotPair()).isInside(index))
                 return new Ret2<DotPair, Integer>(dp, METHOD);
        
         // This will check constructors, if there is match for "isInside" then return it.
         // Make sure to return the CONSTRUCTOR constant marker to let the user know this is a
         // "Constructor Details" match.
         iter = Details.constructorDetailsIterator(javaDocPage);
         while (iter.hasNext())
             if ((dp = iter.nextDotPair()).isInside(index))
                 return new Ret2<DotPair, Integer>(dp, CONSTRUCTOR);
        
         // No matches, return null
         return null;
        
      • findSummary

        public static Ret2<DotPair,​java.lang.Integer> findSummary​
                    (java.util.Vector<HTMLNode> javaDocPage,
                     int index)
        
        Deprecated.
        This does the exact same thing as findDetails(...), except that it searches for potential sub-list matches by request Method, Constructor, and Field summaries sections, not details sections.
        Parameters:
        javaDocPage - This should be a vectorized-HTML JavaDoc-Generated Web-Page.
        index - Any index that points to an element in javaDocPage. This may be any type of HTMLNode. Specifically, javaDocPage.elementAt(index) may contain an instanceof: TagNode, TextNode, or CommentNode.
        Returns:
        This will return the starting-position and ending-position of the identified Java-Doc details section as a DotPair. The second value of the Ret2 instance will take on the values of the public constants defined at the top of this page.

        • Ret2.a, a DotPair instance, and will contain the start and end index of the Details section returned
        • Ret2.b, will contain one of three values: Locate.METHOD, Locate.FIELD, or Locate.CONSTRUCTOR.


        NOTE: If this index does not pass the DotPair.isInside(index) for *any* details section then this method returns null.
        Code:
        Exact Method Body:
         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
         if (index < 0) throw new ArrayIndexOutOfBoundsException
             ("The index value you have passed is negative: [" + index + "]");
            
         if (index >= javaDocPage.size()) throw new ArrayIndexOutOfBoundsException(
             "The index value you have passed [" + index + "], " +
             "is greater than the length of the vector parameter: javaDocPage.size() = " +
             "[" + javaDocPage.size() + "]"
         ); 
        
         DotPair dp;
        
         // Comments for findSummary are identical to comments for findDetails.  Here we request a
         // field-summary iterator, rather than a field-detail iterator.
         HNLIInclusive iter = Summaries.fieldSummaryIterator(javaDocPage);
         while (iter.hasNext())
             if ((dp = iter.nextDotPair()).isInside(index))
                 return new Ret2<DotPair, Integer>(dp, FIELD);
        
         // method-summary-iterator.  Make sure to pass the "METHOD" constant field to let the
         // user know that this Details section represents a "Method Details"
         iter = Summaries.methodSummaryIterator(javaDocPage);
         while (iter.hasNext())
             if ((dp = iter.nextDotPair()).isInside(index))
                 return new Ret2<DotPair, Integer>(dp, METHOD);
        
         // constructor-summary-iterator, if there is match for "isInside" then return it.
         // Make sure to return the CONSTRUCTOR constant marker to let the user know this is
         // a "Constructor Details" match.
         iter = Summaries.constructorSummaryIterator(javaDocPage);
         while (iter.hasNext())
             if ((dp = iter.nextDotPair()).isInside(index))
                 return new Ret2<DotPair, Integer>(dp, CONSTRUCTOR);
        
         // No matches, return null
         return null;