sboag 00/12/17 09:40:04
Modified: java/src/org/apache/xpath/axes AncestorOrSelfWalker.java
AncestorWalker.java AttributeWalker.java
AttributeWalkerOneStep.java AxesWalker.java
ChildWalker.java ChildWalkerMultiStep.java
ChildWalkerOneStep.java ContextNodeList.java
DescendantOrSelfWalker.java DescendantWalker.java
FollowingSiblingWalker.java FollowingWalker.java
LocPathIterator.java NamespaceWalker.java
ParentWalker.java PrecedingSiblingWalker.java
PrecedingWalker.java ReverseAxesWalker.java
RootWalker.java SelfWalker.java
SelfWalkerOneStep.java SubContextList.java
UnionPathIterator.java
Log:
Java doc.
Revision Changes Path
1.4 +3 -3
xml-xalan/java/src/org/apache/xpath/axes/AncestorOrSelfWalker.java
Index: AncestorOrSelfWalker.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/AncestorOrSelfWalker.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- AncestorOrSelfWalker.java 2000/12/09 03:49:38 1.3
+++ AncestorOrSelfWalker.java 2000/12/17 17:40:00 1.4
@@ -75,7 +75,7 @@
/**
* Construct an AncestorOrSelfWalker using a LocPathWalker.
*
- * NEEDSDOC @param locPathIterator
+ * @param locPathIterator The location path iterator that 'owns' this
walker.
*/
public AncestorOrSelfWalker(LocPathIterator locPathIterator)
{
@@ -85,7 +85,7 @@
/**
* Push the ancestor nodes.
*
- * NEEDSDOC @param n
+ * @param n The context node.
*/
protected void pushAncestors(Node n)
{
@@ -108,7 +108,7 @@
/**
* Tell what's the maximum level this axes can descend to.
*
- * NEEDSDOC ($objectName$) @return
+ * @return An estimation of the maximum level this axes can descend to.
*/
protected int getLevelMax()
{
1.4 +6 -4
xml-xalan/java/src/org/apache/xpath/axes/AncestorWalker.java
Index: AncestorWalker.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/AncestorWalker.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- AncestorWalker.java 2000/12/09 03:49:38 1.3
+++ AncestorWalker.java 2000/12/17 17:40:00 1.4
@@ -75,7 +75,7 @@
/**
* Construct an AncestorWalker using a LocPathWalker.
*
- * NEEDSDOC @param locPathIterator
+ * @param locPathIterator The location path iterator that 'owns' this
walker.
*/
public AncestorWalker(LocPathIterator locPathIterator)
{
@@ -122,7 +122,7 @@
/**
* The root node of the TreeWalker.
*
- * NEEDSDOC @param root
+ * @param root The context node of this step.
*/
public void setRoot(Node root)
{
@@ -148,7 +148,9 @@
return setCurrentIfNotNull(next);
}
- /** NEEDSDOC Field m_ancestors */
+ /** Stack of ancestors. We have to do this instead of
+ * just using getParent on the fly, because we have to walk the ancestors
+ * in document order. */
protected Stack m_ancestors;
/** The position within the stack */
@@ -157,7 +159,7 @@
/**
* Tell what's the maximum level this axes can descend to.
*
- * NEEDSDOC ($objectName$) @return
+ * @return An estimation of the maximum level this axes can descend to.
*/
protected int getLevelMax()
{
1.6 +3 -3
xml-xalan/java/src/org/apache/xpath/axes/AttributeWalker.java
Index: AttributeWalker.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/AttributeWalker.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- AttributeWalker.java 2000/12/16 17:16:25 1.5
+++ AttributeWalker.java 2000/12/17 17:40:00 1.6
@@ -73,7 +73,7 @@
/**
* Construct an AttributeWalker using a LocPathWalker.
*
- * NEEDSDOC @param locPathIterator
+ * @param locPathIterator The location path iterator that 'owns' this
walker.
*/
public AttributeWalker(LocPathIterator locPathIterator)
{
@@ -83,7 +83,7 @@
/**
* The root node of the TreeWalker.
*
- * NEEDSDOC @param root
+ * @param root The context node of this step.
*/
public void setRoot(Node root)
{
@@ -161,7 +161,7 @@
/**
* Tell what's the maximum level this axes can descend to.
*
- * NEEDSDOC ($objectName$) @return
+ * @return An estimation of the maximum level this axes can descend to.
*/
protected int getLevelMax()
{
1.6 +8 -18
xml-xalan/java/src/org/apache/xpath/axes/AttributeWalkerOneStep.java
Index: AttributeWalkerOneStep.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/AttributeWalkerOneStep.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- AttributeWalkerOneStep.java 2000/12/16 17:16:25 1.5
+++ AttributeWalkerOneStep.java 2000/12/17 17:40:00 1.6
@@ -63,19 +63,20 @@
import org.apache.xpath.patterns.NodeTestFilter;
/**
- * <meta name="usage" content="internal"/>
- * NEEDSDOC Class AttributeWalkerOneStep <needs-comment/>
+ * <meta name="usage" content="advanced"/>
+ * This walker should be used when the walker is at the end of a location
+ * path, or is the only step. It has a much simplified nextNode() method.
*/
public class AttributeWalkerOneStep extends AxesWalker
{
- /** NEEDSDOC Field m_attributeList */
+ /** The attribute list from the context node. */
transient NamedNodeMap m_attributeList;
- /** NEEDSDOC Field m_attrListPos */
+ /** The current index into m_attributeList. -1 to start. */
int m_attrListPos;
- /** NEEDSDOC Field m_nAttrs */
+ /** The number of attributes in m_attributeList, or -2 if no attributes. */
int m_nAttrs;
/**
@@ -103,7 +104,7 @@
/**
* Construct an AxesWalker using a LocPathIterator.
*
- * NEEDSDOC @param locPathIterator
+ * @param locPathIterator The location path iterator that 'owns' this
walker.
*/
public AttributeWalkerOneStep(LocPathIterator locPathIterator)
{
@@ -111,20 +112,9 @@
}
/**
- * Set the analysis ID.
- * @see org.apache.xpath.axes.WalkerFactory
- *
- * NEEDSDOC @param a
- */
- void setAnalysis(int a)
- {
- super.setAnalysis(a);
- }
-
- /**
* Get the next node in document order on the axes.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The next node in the itteration, or null.
*/
public Node nextNode()
{
1.15 +126 -116 xml-xalan/java/src/org/apache/xpath/axes/AxesWalker.java
Index: AxesWalker.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xpath/axes/AxesWalker.java,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- AxesWalker.java 2000/12/16 17:16:25 1.14
+++ AxesWalker.java 2000/12/17 17:40:00 1.15
@@ -94,32 +94,37 @@
// public static boolean DEBUG_LOCATED = true;
// public static boolean DEBUG_PREDICATECOUNTING = false;
- /** NEEDSDOC Field DEBUG */
+ /** General static debug flag. Setting this to false will suppress some
+ * of the output messages caused by the other debug categories. */
static final boolean DEBUG = false;
- /** NEEDSDOC Field DEBUG_WAITING */
+ /** If true, diagnostic messages about the waiting queue will be posted.
*/
static final boolean DEBUG_WAITING = false;
- /** NEEDSDOC Field DEBUG_TRAVERSAL */
+ /** For diagnostic purposes, tells if we already did a subtree dump. */
+ static boolean m_didDumpAll = false;
+
+ /** If true, diagnostic messages about the tree traversal will be posted.
*/
static final boolean DEBUG_TRAVERSAL = false;
- /** NEEDSDOC Field DEBUG_LOCATED */
+ /** If true, diagnostic messages about the nodes that have
+ * been 'located' will be posted. */
static final boolean DEBUG_LOCATED = false;
- /** NEEDSDOC Field DEBUG_PREDICATECOUNTING */
+ /** If true, diagnostic messages about predicate execution will be posted.
*/
static final boolean DEBUG_PREDICATECOUNTING = false;
- /** NEEDSDOC Field FEATURE_NODETESTFILTER */
+ /** String passed to [EMAIL PROTECTED] org.w3c.dom.Node#isSupported} to
see if it implements
+ * a [EMAIL PROTECTED] org.apache.xpath.patterns.NodeTestFilter}
interface. */
public static final String FEATURE_NODETESTFILTER = "NodeTestFilter";
- /** NEEDSDOC Field m_lpi */
+ /** The owning location path iterator. */
protected LocPathIterator m_lpi;
/**
- * NEEDSDOC Method getLocPathIterator
- *
+ * Get the owning location path iterator.
*
- * NEEDSDOC (getLocPathIterator) @return
+ * @return the owning location path iterator, which should not be null.
*/
public LocPathIterator getLocPathIterator()
{
@@ -148,11 +153,12 @@
}
/**
- * Init an AxesWalker.
+ * Initialize an AxesWalker during the parse of the XPath expression.
*
- * NEEDSDOC @param compiler
- * NEEDSDOC @param opPos
- * NEEDSDOC @param stepType
+ * @param compiler The Compiler object that has information about this
+ * walker in the op map.
+ * @param opPos The op code position of this location step.
+ * @param stepType The type of location step.
*
* @throws javax.xml.transform.TransformerException
*/
@@ -267,10 +273,11 @@
private int m_stepType;
/**
- * NEEDSDOC Method getStepType
+ * The the step type op code.
*
*
- * NEEDSDOC (getStepType) @return
+ * @return An integer that represents an axes traversal opcode found in
+ * [EMAIL PROTECTED] org.apache.xpath.compiler.OpCodes}.
*/
protected int getStepType()
{
@@ -279,14 +286,15 @@
/**
* The arg length of the XPath step. Does not change after the constructor.
+ * TODO: Can this be removed since it is only valuable at compile time?
*/
private int m_argLen;
/**
- * NEEDSDOC Method getArgLen
+ * Get the argument length of the location step in the opcode map.
+ * TODO: Can this be removed since it is only valuable at compile time?
*
- *
- * NEEDSDOC (getArgLen) @return
+ * @return The argument length of the location step in the opcode map.
*/
protected int getArgLen()
{
@@ -294,16 +302,17 @@
}
/**
- * The type of this walker based on the pattern analysis.
+ * The analysis pattern built by the WalkerFactory.
+ * TODO: Move to LocPathIterator.
* @see org.apache.xpath.axes.WalkerFactory
*/
protected int m_analysis = 0x00000000;
/**
- * NEEDSDOC Method getAnalysis
- *
+ * Get the analysis pattern built by the WalkerFactory.
+ * TODO: Move to LocPathIterator.
*
- * NEEDSDOC (getAnalysis) @return
+ * @return The analysis pattern built by the WalkerFactory.
*/
int getAnalysis()
{
@@ -311,10 +320,10 @@
}
/**
- * NEEDSDOC Method setAnalysis
+ * Set the analysis pattern built by the WalkerFactory.
+ * TODO: Move to LocPathIterator.
*
- *
- * NEEDSDOC @param a
+ * @param a The analysis pattern built by the WalkerFactory.
*/
void setAnalysis(int a)
{
@@ -330,7 +339,7 @@
/**
* Get the current sub-context position.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The node position of this walker in the sub-context node list.
*/
public int getProximityPosition()
{
@@ -342,9 +351,9 @@
/**
* Get the current sub-context position.
*
- * NEEDSDOC @param xctxt
+ * @param xctxt The XPath runtime context.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The node position of this walker in the sub-context node list.
*/
public int getProximityPosition(XPathContext xctxt)
{
@@ -354,9 +363,10 @@
/**
* Get the current sub-context position.
*
- * NEEDSDOC @param predicateIndex
+ * @param predicateIndex The index of the predicate where the proximity
+ * should be taken from.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The node position of this walker in the sub-context node list.
*/
protected int getProximityPosition(int predicateIndex)
{
@@ -386,7 +396,7 @@
/**
* Init the proximity position to zero for a forward axes.
*
- * NEEDSDOC @param i
+ * @param i The index into the m_proximityPositions array.
*
* @throws javax.xml.transform.TransformerException
*/
@@ -398,7 +408,8 @@
/**
* Count forward one proximity position.
*
- * NEEDSDOC @param i
+ * @param i The index into the m_proximityPositions array, where the
increment
+ * will occur.
*/
protected void countProximityPosition(int i)
{
@@ -409,7 +420,7 @@
/**
* Tells if this is a reverse axes.
*
- * NEEDSDOC ($objectName$) @return
+ * @return false, unless a derived class overrides.
*/
public boolean isReverseAxes()
{
@@ -422,10 +433,9 @@
int m_predicateIndex = -1;
/**
- * Get which predicate is executing. Returns
- * -1 if no predicate is executing.
+ * Get which predicate is executing.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The current predicate index, or -1 if no predicate is executing.
*/
public int getPredicateIndex()
{
@@ -435,10 +445,10 @@
/**
* Process the predicates.
*
- * NEEDSDOC @param context
- * NEEDSDOC @param xctxt
+ * @param context The current context node.
+ * @param xctxt The XPath runtime context.
*
- * NEEDSDOC ($objectName$) @return
+ * @return the result of executing the predicate expressions.
*
* @throws javax.xml.transform.TransformerException
*/
@@ -536,7 +546,7 @@
/**
* Get the number of predicates that this walker has.
*
- * NEEDSDOC ($objectName$) @return
+ * @return the number of predicates that this walker has.
*/
public int getPredicateCount()
{
@@ -546,7 +556,7 @@
/**
* Set the number of predicates that this walker has.
*
- * NEEDSDOC @param count
+ * @param count The number of predicates.
*/
public void setPredicateCount(int count)
{
@@ -556,8 +566,9 @@
/**
* Init predicate info.
*
- * NEEDSDOC @param compiler
- * NEEDSDOC @param opPos
+ * @param compiler The Compiler object that has information about this
+ * walker in the op map.
+ * @param opPos The op code position of this location step.
*
* @throws javax.xml.transform.TransformerException
*/
@@ -571,16 +582,17 @@
m_predicateCount = (null == m_predicates) ? 0 : m_predicates.length;
}
- /** NEEDSDOC Field m_predicates */
+ /** The list of predicate expressions. Is static and does not need
+ * to be deep cloned. */
private Expression[] m_predicates;
/**
- * NEEDSDOC Method getPredicate
+ * Get a predicate expression at the given index.
*
*
- * NEEDSDOC @param index
+ * @param index Index of the predicate.
*
- * NEEDSDOC (getPredicate) @return
+ * @return A predicate expression.
*/
Expression getPredicate(int index)
{
@@ -591,9 +603,10 @@
* Tell if the given node is a parent of the
* step context, or the step context node itself.
*
- * NEEDSDOC @param n
+ * @param n The node being tested.
*
- * NEEDSDOC ($objectName$) @return
+ * @return true if n is a parent of the step context, or the step context
+ * itself.
*/
boolean isAncestorOfRootContext(Node n)
{
@@ -620,21 +633,21 @@
* The root node of the TreeWalker, as specified in setRoot(Node root).
* Note that this may actually be below the current node.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The context node of the step.
*/
public Node getRoot()
{
return m_root;
}
- /** NEEDSDOC Field m_isFresh */
+ /** True if an itteration has not begun. */
boolean m_isFresh;
/**
* Set the root node of the TreeWalker.
* (Not part of the DOM2 TreeWalker interface).
*
- * NEEDSDOC @param root
+ * @param root The context node of this step.
*/
public void setRoot(Node root)
{
@@ -678,7 +691,8 @@
* current view by applying the filters in the requested direction (not
* changing currentNode where no traversal is possible).
*
- * NEEDSDOC ($objectName$) @return
+ * @return The node at which the TreeWalker is currently positioned, only
null
+ * if setRoot has not yet been called.
* @exception DOMException
* NOT_SUPPORTED_ERR: Raised if the specified <code>currentNode</code>
* is<code>null</code> .
@@ -691,7 +705,7 @@
/**
* Set the current node.
*
- * NEEDSDOC @param currentNode
+ * @param currentNode The current itteration node, should not be null.
*
* @throws DOMException
*/
@@ -703,7 +717,7 @@
/**
* Set the current node if it's not null.
*
- * NEEDSDOC @param currentNode
+ * @param currentNode The current node or null.
* @return The node passed in.
*
* @throws DOMException
@@ -720,7 +734,7 @@
/**
* The filter used to screen nodes.
*
- * NEEDSDOC ($objectName$) @return
+ * @return This AxesWalker.
*/
public NodeFilter getFilter()
{
@@ -739,7 +753,7 @@
* entity expansion, use the whatToShow flags to show the entity
* reference node and set expandEntityReferences to false.
*
- * NEEDSDOC ($objectName$) @return
+ * @return true.
*/
public boolean getExpandEntityReferences()
{
@@ -826,14 +840,14 @@
throw new RuntimeException("previousNode not supported!");
}
- /** NEEDSDOC Field m_nextWalker */
+ /** The next walker in the location step chain. */
protected AxesWalker m_nextWalker;
/**
- * NEEDSDOC Method setNextWalker
+ * Set the next walker in the location step chain.
*
*
- * NEEDSDOC @param walker
+ * @param walker Reference to AxesWalker derivative, or may be null.
*/
public void setNextWalker(AxesWalker walker)
{
@@ -841,24 +855,25 @@
}
/**
- * NEEDSDOC Method getNextWalker
+ * Get the next walker in the location step chain.
*
*
- * NEEDSDOC (getNextWalker) @return
+ * @return Reference to AxesWalker derivative, or null.
*/
public AxesWalker getNextWalker()
{
return m_nextWalker;
}
- /** NEEDSDOC Field m_prevWalker */
+ /** The previous walker in the location step chain, or null. */
AxesWalker m_prevWalker;
/**
- * NEEDSDOC Method setPrevWalker
+ * Set or clear the previous walker reference in the location step chain.
*
*
- * NEEDSDOC @param walker
+ * @param walker Reference to previous walker reference in the location
+ * step chain, or null.
*/
public void setPrevWalker(AxesWalker walker)
{
@@ -866,10 +881,11 @@
}
/**
- * NEEDSDOC Method getPrevWalker
+ * Get the previous walker reference in the location step chain.
*
*
- * NEEDSDOC (getPrevWalker) @return
+ * @return Reference to previous walker reference in the location
+ * step chain, or null.
*/
public AxesWalker getPrevWalker()
{
@@ -877,9 +893,9 @@
}
/**
- * Diagnostics.
+ * Diagnostic string for this walker.
*
- * NEEDSDOC ($objectName$) @return
+ * @return Diagnostic string for this walker.
*/
public String toString()
{
@@ -922,9 +938,9 @@
/**
* Diagnostics.
*
- * NEEDSDOC @param n
+ * @param n Node to give diagnostic information about, or null.
*
- * NEEDSDOC ($objectName$) @return
+ * @return Informative string about the argument.
*/
protected String nodeToString(Node n)
{
@@ -942,11 +958,12 @@
}
/**
- * Diagnostics.
+ * This is simply a way to bottle-neck the return of the next node, for
+ * diagnostic purposes.
*
- * NEEDSDOC @param n
+ * @param n Node to return, or null.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The argument.
*/
private Node returnNextNode(Node n)
{
@@ -964,9 +981,9 @@
}
/**
- * Diagnostics.
+ * Print a diagnostics string, adding a line break before the print.
*
- * NEEDSDOC @param s
+ * @param s String to print.
*/
private void printDebug(String s)
{
@@ -996,10 +1013,10 @@
}
/**
- * Do a diagnostics dump of the entire document.
+ * Do a diagnostics dump of an entire subtree.
*
- * NEEDSDOC @param node
- * NEEDSDOC @param indent
+ * @param node The top of the subtree.
+ * @param indent The amount to begin the indenting at.
*/
private void dumpAll(Node node, int indent)
{
@@ -1061,9 +1078,9 @@
}
/**
- * Diagnostics.
+ * Print a diagnostic string without adding a line break.
*
- * NEEDSDOC @param s
+ * @param s The string to print.
*/
private void printDebugAdd(String s)
{
@@ -1127,28 +1144,25 @@
}
}
- // short-lived flag.
-
- /** NEEDSDOC Field m_waitingForNext */
- private boolean m_waitingForNext = false;
-
/**
- * Tell what's the maximum level this axes can descend to.
+ * Tell what's the maximum level this axes can descend to. This method is
+ * meant to be overloaded by derived classes.
*
- * NEEDSDOC ($objectName$) @return
+ * @return An estimation of the maximum level this axes can descend to.
*/
protected int getLevelMax()
{
return 0;
}
- /** NEEDSDOC Field m_nextLevelAmount */
+ /** An estimation of the next level that this walker will traverse to.
Not
+ * always accurate. */
protected int m_nextLevelAmount;
/**
* Tell what's the next level this axes can descend to.
*
- * NEEDSDOC ($objectName$) @return
+ * @return An estimation of the next level that this walker will traverse
to.
*/
protected int getNextLevelAmount()
{
@@ -1158,16 +1172,14 @@
/**
* Tell if it's OK to traverse to the next node, following document
* order, or if the walker should wait for a condition to occur.
- * @prevStepWalker The previous walker in the location path.
- * @testWalker The walker being tested, but the state may not be intact,
+ *
+ * @param prevStepWalker The previous walker in the location path.
+ * @param testWalker The walker being tested, but the state may not be
intact,
* so only static information can be obtained from it.
+ * @param currentTestNode The current node being testing.
+ * @param nextLevelAmount An estimation of the next level to traverse to.
*
- * NEEDSDOC @param prevStepWalker
- * NEEDSDOC @param testWalker
- * NEEDSDOC @param currentTestNode
- * NEEDSDOC @param nextLevelAmount
- *
- * NEEDSDOC ($objectName$) @return
+ * @return True if it's OK for testWalker to traverse to nextLevelAmount.
*/
protected boolean checkOKToTraverse(AxesWalker prevStepWalker,
AxesWalker testWalker,
@@ -1232,7 +1244,7 @@
return ok;
}
- /** NEEDSDOC Field m_didSwitch */
+ /** Fairly short lived flag to tell if we switched to a waiting walker. */
private boolean m_didSwitch = false;
/**
@@ -1298,7 +1310,7 @@
* We have to do something to get things moving along,
* so get the earliest (in doc order) waiter.
*
- * NEEDSDOC ($objectName$) @return
+ * @return the earliest (in doc order) waiting walker.
*/
private AxesWalker getEarliestWaiting()
{
@@ -1337,9 +1349,9 @@
/**
* Tell if the given walker is already on the waiting list.
*
- * NEEDSDOC @param walker
+ * @param walker Reference to walker that is the subject of the test.
*
- * NEEDSDOC ($objectName$) @return
+ * @return True if the walker argument is on the waiting list.
*/
boolean isWaiting(AxesWalker walker)
{
@@ -1371,9 +1383,9 @@
* Check if a given walker needs to wait for the previous walker to
* catch up.
*
- * NEEDSDOC @param walker
+ * @param walker The walker being checked.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The walker or the previous walker.
*/
AxesWalker checkNeedsToWait(AxesWalker walker)
{
@@ -1407,21 +1419,22 @@
addToWaitList(walker);
walker = walker.m_prevWalker;
-
- walker.printEntryDebug();
+
+ if (DEBUG_WAITING)
+ walker.printEntryDebug();
}
}
return walker;
}
- /** NEEDSDOC Field m_isDone */
+ /** True if this walker has found it's last node. */
boolean m_isDone = false;
/**
* Get the next node in document order on the axes.
*
- * NEEDSDOC ($objectName$) @return
+ * @return the next node in document order on the axes, or null.
*/
protected Node getNextNode()
{
@@ -1455,12 +1468,9 @@
return next;
}
- /** NEEDSDOC Field m_prevReturned */
+ /** The node last returned from nextNode(). */
transient Node m_prevReturned;
- /** NEEDSDOC Field m_didDumpAll */
- static boolean m_didDumpAll = false;
-
/**
* Moves the <code>TreeWalker</code> to the next visible node in document
* order relative to the current node, and returns the new node. If the
@@ -1641,12 +1651,12 @@
//============= End TreeWalker Implementation =============
/**
- * NEEDSDOC Method getLastPos
+ * Get the index of the last node that can be itterated to.
*
*
- * NEEDSDOC @param xctxt
+ * @param xctxt XPath runtime context.
*
- * NEEDSDOC (getLastPos) @return
+ * @return the index of the last node that can be itterated to.
*/
public int getLastPos(XPathContext xctxt)
{
1.4 +3 -3 xml-xalan/java/src/org/apache/xpath/axes/ChildWalker.java
Index: ChildWalker.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/ChildWalker.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ChildWalker.java 2000/10/30 18:58:45 1.3
+++ ChildWalker.java 2000/12/17 17:40:00 1.4
@@ -72,7 +72,7 @@
/**
* Construct an ChildWalker using a LocPathIterator.
*
- * NEEDSDOC @param locPathIterator
+ * @param locPathIterator The location path iterator that 'owns' this
walker.
*/
public ChildWalker(LocPathIterator locPathIterator)
{
@@ -82,7 +82,7 @@
/**
* The root node of the TreeWalker.
*
- * NEEDSDOC @param root
+ * @param root The context node of this step.
*/
public void setRoot(Node root)
{
@@ -139,7 +139,7 @@
/**
* Tell what's the maximum level this axes can descend to.
*
- * NEEDSDOC ($objectName$) @return
+ * @return An estimation of the maximum level this axes can descend to.
*/
protected int getLevelMax()
{
1.4 +1 -1
xml-xalan/java/src/org/apache/xpath/axes/ChildWalkerMultiStep.java
Index: ChildWalkerMultiStep.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/ChildWalkerMultiStep.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ChildWalkerMultiStep.java 2000/11/15 19:41:06 1.3
+++ ChildWalkerMultiStep.java 2000/12/17 17:40:00 1.4
@@ -62,7 +62,7 @@
import org.apache.xpath.patterns.NodeTestFilter;
/**
- * <meta name="usage" content="internal"/>
+ * <meta name="usage" content="advanced"/>
* Class ChildWalkerMultiStep
* <needs-description/>
*
1.3 +5 -16
xml-xalan/java/src/org/apache/xpath/axes/ChildWalkerOneStep.java
Index: ChildWalkerOneStep.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/ChildWalkerOneStep.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ChildWalkerOneStep.java 2000/10/30 18:58:47 1.2
+++ ChildWalkerOneStep.java 2000/12/17 17:40:00 1.3
@@ -62,8 +62,8 @@
import org.apache.xpath.patterns.NodeTestFilter;
/**
- * <meta name="usage" content="internal"/>
- * NEEDSDOC Class ChildWalkerOneStep <needs-comment/>
+ * <meta name="usage" content="advanced"/>
+ * Walker to use when we only have one step, but it has a predicate.
*/
public class ChildWalkerOneStep extends AxesWalker
{
@@ -71,7 +71,7 @@
/**
* Construct an AxesWalker using a LocPathIterator.
*
- * NEEDSDOC @param locPathIterator
+ * @param locPathIterator The location path iterator that 'owns' this
walker.
*/
public ChildWalkerOneStep(LocPathIterator locPathIterator)
{
@@ -81,7 +81,7 @@
/**
* Tell what's the maximum level this axes can descend to.
*
- * NEEDSDOC ($objectName$) @return
+ * @return An estimation of the maximum level this axes can descend to.
*/
protected int getLevelMax()
{
@@ -89,20 +89,9 @@
}
/**
- * Set the analysis ID.
- * @see org.apache.xpath.axes.WalkerFactory
- *
- * NEEDSDOC @param a
- */
- void setAnalysis(int a)
- {
- super.setAnalysis(a);
- }
-
- /**
* Get the next node in document order on the axes.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The next node in the walk, or null.
*/
public Node nextNode()
{
1.5 +33 -14
xml-xalan/java/src/org/apache/xpath/axes/ContextNodeList.java
Index: ContextNodeList.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/ContextNodeList.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- ContextNodeList.java 2000/11/14 23:15:10 1.4
+++ ContextNodeList.java 2000/12/17 17:40:00 1.5
@@ -60,17 +60,19 @@
import org.w3c.dom.traversal.NodeIterator;
/**
- * <meta name="usage" content="internal"/>
- * NEEDSDOC Interface ContextNodeList
+ * <meta name="usage" content="advanced"/>
+ * Classes who implement this interface can be a
+ * <a href="http://www.w3.org/TR/xslt#dt-current-node-list";>current node
list</a>,
+ * also refered to here as a <term>context node list</term>.
*/
public interface ContextNodeList
{
/**
- * NEEDSDOC Method getCurrentNode
+ * Get the <a href="http://www.w3.org/TR/xslt#dt-current-node";>current
node</a>.
*
*
- * NEEDSDOC (getCurrentNode) @return
+ * @return The current node, or null.
*/
public Node getCurrentNode();
@@ -80,7 +82,9 @@
* you call getCurrentPos() and the return is 0, the next
* fetch will take place at index 1.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The position of the
+ * <a href="http://www.w3.org/TR/xslt#dt-current-node";>current node</a>
+ * in the <a
href="http://www.w3.org/TR/xslt#dt-current-node-list";>current node list</a>.
*/
public int getCurrentPos();
@@ -93,7 +97,7 @@
* If setShouldCacheNodes(true) is called, then nodes will
* be cached. They are not cached by default.
*
- * NEEDSDOC @param b
+ * @param b true if the nodes should be cached.
*/
public void setShouldCacheNodes(boolean b);
@@ -103,7 +107,8 @@
* m_next to the index. If the index argument is -1, this
* signals that the iterator should be run to the end.
*
- * NEEDSDOC @param index
+ * @param index The index to run to, or -1 if the iterator should be run
+ * to the end.
*/
public void runTo(int index);
@@ -116,7 +121,7 @@
/**
* Get the length of the list.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The number of nodes in this node list.
*/
public int size();
@@ -125,29 +130,43 @@
* the first nextNode() that is called will return the
* first node in the set.
*
- * NEEDSDOC ($objectName$) @return
+ * @return true if the iteration of this list has not yet begun.
*/
public boolean isFresh();
/**
- * Get a cloned Iterator.
+ * Get a cloned Iterator that is reset to the start of the iteration.
*
- * NEEDSDOC ($objectName$) @return
+ * @return A clone of this iteration that has been reset.
*
* @throws CloneNotSupportedException
*/
public NodeIterator cloneWithReset() throws CloneNotSupportedException;
/**
- * NEEDSDOC Method clone
+ * Get a clone of this iterator. Be aware that this operation may be
+ * somewhat expensive.
*
*
- * NEEDSDOC (clone) @return
+ * @return A clone of this object.
*
* @throws CloneNotSupportedException
*/
public Object clone() throws CloneNotSupportedException;
-
+
+ /**
+ * Get the index of the last node in this list.
+ *
+ *
+ * @return the index of the last node in this list.
+ */
public int getLast();
+
+ /**
+ * Set the index of the last node in this list.
+ *
+ *
+ * @param last the index of the last node in this list.
+ */
public void setLast(int last);
}
1.3 +3 -4
xml-xalan/java/src/org/apache/xpath/axes/DescendantOrSelfWalker.java
Index: DescendantOrSelfWalker.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/DescendantOrSelfWalker.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- DescendantOrSelfWalker.java 2000/10/30 18:58:48 1.2
+++ DescendantOrSelfWalker.java 2000/12/17 17:40:00 1.3
@@ -72,7 +72,7 @@
/**
* Construct a DescendantOrSelfWalker using a LocPathIterator.
*
- * NEEDSDOC @param locPathIterator
+ * @param locPathIterator The location path iterator that 'owns' this
walker.
*/
public DescendantOrSelfWalker(LocPathIterator locPathIterator)
{
@@ -82,7 +82,7 @@
/**
* Set the root node of the TreeWalker.
*
- * NEEDSDOC @param root
+ * @param root The context node of this step.
*/
public void setRoot(Node root)
{
@@ -104,7 +104,6 @@
{
// Follow my made-up rule about returning the self node as a child.
- // (only in this case, it isn't the self).
if (!m_processedSelf)
{
m_processedSelf = true;
@@ -115,6 +114,6 @@
return super.firstChild();
}
- /** NEEDSDOC Field m_processedSelf */
+ /** True if the self (root, context node) has been returned. */
boolean m_processedSelf;
}
1.4 +3 -3
xml-xalan/java/src/org/apache/xpath/axes/DescendantWalker.java
Index: DescendantWalker.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/DescendantWalker.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- DescendantWalker.java 2000/12/15 02:30:39 1.3
+++ DescendantWalker.java 2000/12/17 17:40:00 1.4
@@ -72,7 +72,7 @@
/**
* Construct an DescendantWalker using a LocPathIterator.
*
- * NEEDSDOC @param locPathIterator
+ * @param locPathIterator The location path iterator that 'owns' this
walker.
*/
public DescendantWalker(LocPathIterator locPathIterator)
{
@@ -82,7 +82,7 @@
/**
* Set the root node of the TreeWalker.
*
- * NEEDSDOC @param root
+ * @param root The context node of this step.
*/
public void setRoot(Node root)
{
@@ -160,7 +160,7 @@
/**
* Tell what's the maximum level this axes can descend to.
*
- * NEEDSDOC ($objectName$) @return
+ * @return Short.MAX_VALUE.
*/
protected int getLevelMax()
{
1.3 +2 -2
xml-xalan/java/src/org/apache/xpath/axes/FollowingSiblingWalker.java
Index: FollowingSiblingWalker.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/FollowingSiblingWalker.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- FollowingSiblingWalker.java 2000/10/30 18:58:49 1.2
+++ FollowingSiblingWalker.java 2000/12/17 17:40:01 1.3
@@ -72,7 +72,7 @@
/**
* Construct a FollowingSiblingWalker using a LocPathIterator.
*
- * NEEDSDOC @param locPathIterator
+ * @param locPathIterator The location path iterator that 'owns' this
walker.
*/
public FollowingSiblingWalker(LocPathIterator locPathIterator)
{
@@ -100,7 +100,7 @@
/**
* Tell what's the maximum level this axes can descend to.
*
- * NEEDSDOC ($objectName$) @return
+ * @return An estimation of the maximum level this axes can descend to.
*/
protected int getLevelMax()
{
1.5 +6 -5
xml-xalan/java/src/org/apache/xpath/axes/FollowingWalker.java
Index: FollowingWalker.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/FollowingWalker.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- FollowingWalker.java 2000/12/16 17:16:25 1.4
+++ FollowingWalker.java 2000/12/17 17:40:01 1.5
@@ -75,7 +75,7 @@
/**
* Construct a FollowingWalker using a LocPathIterator.
*
- * NEEDSDOC @param locPathIterator
+ * @param locPathIterator The location path iterator that 'owns' this
walker.
*/
public FollowingWalker(LocPathIterator locPathIterator)
{
@@ -85,7 +85,7 @@
/**
* Set the root node of the TreeWalker.
*
- * NEEDSDOC @param root
+ * @param root The context node of this step.
*/
public void setRoot(Node root)
{
@@ -119,7 +119,7 @@
m_nextLevelAmount = 0;
}
- /** NEEDSDOC Field m_ancestors */
+ /** Stack of ancestors of the root/context node. */
transient protected Stack m_ancestors = new Stack();
/**
@@ -218,13 +218,14 @@
return setCurrentIfNotNull(n);
}
- /** NEEDSDOC Field m_currentAncestor */
+ /** What this is is frankly a little unclear. It is used in getParent
+ * to see if we should continue to climb the tree. */
transient Node m_currentAncestor;
/**
* Tell what's the maximum level this axes can descend to.
*
- * NEEDSDOC ($objectName$) @return
+ * @return Short.MAX_VALUE.
*/
protected int getLevelMax()
{
1.20 +6 -6
xml-xalan/java/src/org/apache/xpath/axes/LocPathIterator.java
Index: LocPathIterator.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/LocPathIterator.java,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- LocPathIterator.java 2000/12/16 17:16:26 1.19
+++ LocPathIterator.java 2000/12/17 17:40:01 1.20
@@ -278,7 +278,7 @@
}
/**
- * <meta name="usage" content="internal"/>
+ * <meta name="usage" content="advanced"/>
* Set if this is an iterator at the upper level of
* the XPath.
*/
@@ -789,7 +789,7 @@
}
/**
- * <meta name="usage" content="internal"/>
+ * <meta name="usage" content="advanced"/>
* Get the head of the walker list.
*
* @return The head of the walker list, or null
@@ -801,7 +801,7 @@
}
/**
- * <meta name="usage" content="internal"/>
+ * <meta name="usage" content="advanced"/>
* Set the last used walker.
*
* @param walker The last used walker, or null.
@@ -812,7 +812,7 @@
}
/**
- * <meta name="usage" content="internal"/>
+ * <meta name="usage" content="advanced"/>
* Get the last used walker.
*
* @return The last used walker, or null.
@@ -823,7 +823,7 @@
}
/**
- * <meta name="usage" content="internal"/>
+ * <meta name="usage" content="advanced"/>
* Add a walker to the waiting list.
*
* @param walker A walker that is waiting for
@@ -838,7 +838,7 @@
}
/**
- * <meta name="usage" content="internal"/>
+ * <meta name="usage" content="advanced"/>
* Remove a walker from the waiting list.
*
* @param walker A walker that is no longer waiting.
1.4 +5 -5
xml-xalan/java/src/org/apache/xpath/axes/NamespaceWalker.java
Index: NamespaceWalker.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/NamespaceWalker.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- NamespaceWalker.java 2000/12/16 17:16:26 1.3
+++ NamespaceWalker.java 2000/12/17 17:40:01 1.4
@@ -75,7 +75,7 @@
/**
* Construct an NamespaceWalker using a LocPathIterator.
*
- * NEEDSDOC @param locPathIterator
+ * @param locPathIterator The location path iterator that 'owns' this
walker.
*/
public NamespaceWalker(LocPathIterator locPathIterator)
{
@@ -85,7 +85,7 @@
/**
* Get a cloned AxesWalker.
*
- * NEEDSDOC ($objectName$) @return
+ * @return A cloned NamespaceWalker.
*
* @throws CloneNotSupportedException
*/
@@ -105,7 +105,7 @@
/**
* Set the root node of the TreeWalker.
*
- * NEEDSDOC @param root
+ * @param root The context node of this step.
*/
public void setRoot(Node root)
{
@@ -177,13 +177,13 @@
return this.setCurrentIfNotNull(next);
}
- /** NEEDSDOC Field m_namespaces */
+ /** Stack of namespace decl nodes (xmlns attributes). */
transient Stack m_namespaces;
/**
* Tell what's the maximum level this axes can descend to.
*
- * NEEDSDOC ($objectName$) @return
+ * @return An estimation of the maximum level this axes can descend to.
*/
protected int getLevelMax()
{
1.4 +4 -4
xml-xalan/java/src/org/apache/xpath/axes/ParentWalker.java
Index: ParentWalker.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/ParentWalker.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ParentWalker.java 2000/10/30 18:58:51 1.3
+++ ParentWalker.java 2000/12/17 17:40:01 1.4
@@ -72,7 +72,7 @@
/**
* Construct a ParentWalker using a LocPathIterator.
*
- * NEEDSDOC @param locPathIterator
+ * @param locPathIterator The location path iterator that 'owns' this
walker.
*/
public ParentWalker(LocPathIterator locPathIterator)
{
@@ -82,7 +82,7 @@
/**
* Set the root node of the TreeWalker.
*
- * NEEDSDOC @param root
+ * @param root The context node of this step.
*/
public void setRoot(Node root)
{
@@ -119,13 +119,13 @@
return null;
}
- /** NEEDSDOC Field m_gotParent */
+ /** True if we already obtained the parent node. */
boolean m_gotParent;
/**
* Tell what's the maximum level this axes can descend to.
*
- * NEEDSDOC ($objectName$) @return
+ * @return An estimation of the maximum level this axes can descend to.
*/
protected int getLevelMax()
{
1.4 +2 -2
xml-xalan/java/src/org/apache/xpath/axes/PrecedingSiblingWalker.java
Index: PrecedingSiblingWalker.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/PrecedingSiblingWalker.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- PrecedingSiblingWalker.java 2000/12/15 09:12:22 1.3
+++ PrecedingSiblingWalker.java 2000/12/17 17:40:01 1.4
@@ -72,7 +72,7 @@
/**
* Construct a PrecedingSiblingWalker using a LocPathIterator.
*
- * NEEDSDOC @param locPathIterator
+ * @param locPathIterator The location path iterator that 'owns' this
walker.
*/
public PrecedingSiblingWalker(LocPathIterator locPathIterator)
{
@@ -127,7 +127,7 @@
/**
* Tell what's the maximum level this axes can descend to.
*
- * NEEDSDOC ($objectName$) @return
+ * @return An estimation of the maximum level this axes can descend to.
*/
protected int getLevelMax()
{
1.6 +4 -4
xml-xalan/java/src/org/apache/xpath/axes/PrecedingWalker.java
Index: PrecedingWalker.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/PrecedingWalker.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- PrecedingWalker.java 2000/12/16 17:16:26 1.5
+++ PrecedingWalker.java 2000/12/17 17:40:01 1.6
@@ -77,7 +77,7 @@
/**
* Construct a PrecedingWalker using a LocPathIterator.
*
- * NEEDSDOC @param locPathIterator
+ * @param locPathIterator The location path iterator that 'owns' this
walker.
*/
public PrecedingWalker(LocPathIterator locPathIterator)
{
@@ -88,7 +88,7 @@
* Set the root node of the TreeWalker. If we follow an attribute:: or
namespace::
* axis, we operate relative to the parent node.
*
- * NEEDSDOC @param root
+ * @param root The context node of this step.
*/
public void setRoot(Node root)
{
@@ -233,13 +233,13 @@
return setCurrentIfNotNull(next);
}
- /** NEEDSDOC Field m_doc */
+ /** The document owner node. */
transient Node m_doc;
/**
* Tell what's the maximum level this axes can descend to.
*
- * NEEDSDOC ($objectName$) @return
+ * @return Short.MAX_VALUE.
*/
protected int getLevelMax()
{
1.5 +11 -10
xml-xalan/java/src/org/apache/xpath/axes/ReverseAxesWalker.java
Index: ReverseAxesWalker.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/ReverseAxesWalker.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- ReverseAxesWalker.java 2000/12/09 03:50:46 1.4
+++ ReverseAxesWalker.java 2000/12/17 17:40:01 1.5
@@ -79,7 +79,7 @@
/**
* Construct an AxesWalker using a LocPathIterator.
*
- * NEEDSDOC @param locPathIterator
+ * @param locPathIterator The location path iterator that 'owns' this
walker.
*/
public ReverseAxesWalker(LocPathIterator locPathIterator)
{
@@ -87,9 +87,9 @@
}
/**
- * Tells if this is a reverse axes.
+ * Tells if this is a reverse axes. Overrides AxesWalker#isReverseAxes.
*
- * NEEDSDOC ($objectName$) @return
+ * @return true for this class.
*/
public boolean isReverseAxes()
{
@@ -99,7 +99,7 @@
/**
* Set the root node of the TreeWalker.
*
- * NEEDSDOC @param root
+ * @param root The context node of this step.
*/
public void setRoot(Node root)
{
@@ -113,9 +113,9 @@
* the nodes searched, but, for the moment, this case is probably
* rare enough that the added complexity isn't worth it.
*
- * NEEDSDOC @param predicateIndex
+ * @param predicateIndex The predicate index of the proximity position.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The pridicate index, or -1.
*/
protected int getProximityPosition(int predicateIndex)
{
@@ -169,7 +169,7 @@
/**
* Count backwards one proximity position.
*
- * NEEDSDOC @param i
+ * @param i The predicate index.
*/
protected void countProximityPosition(int i)
{
@@ -178,12 +178,13 @@
}
/**
- * NEEDSDOC Method getLastPos
+ * Get the number of nodes in this node list. The function is probably ill
+ * named?
*
*
- * NEEDSDOC @param xctxt
+ * @param xctxt The XPath runtime context.
*
- * NEEDSDOC (getLastPos) @return
+ * @return the number of nodes in this node list.
*/
public int getLastPos(XPathContext xctxt)
{
1.4 +3 -3 xml-xalan/java/src/org/apache/xpath/axes/RootWalker.java
Index: RootWalker.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xpath/axes/RootWalker.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- RootWalker.java 2000/11/02 22:42:59 1.3
+++ RootWalker.java 2000/12/17 17:40:01 1.4
@@ -74,7 +74,7 @@
/**
* Construct a RootWalker using a LocPathIterator.
*
- * NEEDSDOC @param locPathIterator
+ * @param locPathIterator The location path iterator that 'owns' this
walker.
*/
public RootWalker(LocPathIterator locPathIterator)
{
@@ -126,13 +126,13 @@
return null;
}
- /** NEEDSDOC Field m_processedRoot */
+ /** True if the root node has been processed. */
boolean m_processedRoot = false;
/**
* Tell what's the maximum level this axes can descend to.
*
- * NEEDSDOC ($objectName$) @return
+ * @return Always 1.
*/
protected int getLevelMax()
{
1.4 +5 -5 xml-xalan/java/src/org/apache/xpath/axes/SelfWalker.java
Index: SelfWalker.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xpath/axes/SelfWalker.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- SelfWalker.java 2000/10/30 18:58:55 1.3
+++ SelfWalker.java 2000/12/17 17:40:01 1.4
@@ -67,13 +67,13 @@
* @see <a href="http://www.w3.org/TR/xpath#axes";>XPath axes descriptions</a>
*/
public class SelfWalker extends AxesWalker
- implements java.io.Serializable
+ implements java.io.Serializable
{
/**
* Construct a SelfWalker using a LocPathIterator.
*
- * NEEDSDOC @param locPathIterator
+ * @param locPathIterator The location path iterator that 'owns' this
walker.
*/
public SelfWalker(LocPathIterator locPathIterator)
{
@@ -86,7 +86,7 @@
/**
* Set the root node of the TreeWalker.
*
- * NEEDSDOC @param root
+ * @param root The context node of this step.
*/
public void setRoot(Node root)
{
@@ -118,13 +118,13 @@
return null;
}
- /** NEEDSDOC Field m_processedSelf */
+ /** True if the self node has been processed. */
boolean m_processedSelf;
/**
* Tell what's the maximum level this axes can descend to.
*
- * NEEDSDOC ($objectName$) @return
+ * @return An estimation of the maximum level this axes can descend to.
*/
protected int getLevelMax()
{
1.3 +1 -1
xml-xalan/java/src/org/apache/xpath/axes/SelfWalkerOneStep.java
Index: SelfWalkerOneStep.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/SelfWalkerOneStep.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- SelfWalkerOneStep.java 2000/10/30 18:58:55 1.2
+++ SelfWalkerOneStep.java 2000/12/17 17:40:01 1.3
@@ -60,7 +60,7 @@
import org.w3c.dom.traversal.NodeFilter;
/**
- * <meta name="usage" content="internal"/>
+ * <meta name="usage" content="advanced"/>
* Class SelfWalkerOneStep
* <needs-description/>
*
1.4 +9 -7
xml-xalan/java/src/org/apache/xpath/axes/SubContextList.java
Index: SubContextList.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/SubContextList.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- SubContextList.java 2000/10/30 18:58:56 1.3
+++ SubContextList.java 2000/12/17 17:40:01 1.4
@@ -61,28 +61,30 @@
import org.w3c.dom.Node;
/**
- * <meta name="usage" content="internal"/>
- * NEEDSDOC Interface SubContextList
+ * <meta name="usage" content="advanced"/>
+ * A class that implements this interface is a sub context node list,
meaning it
+ * is a node list for a location path step for a predicate.
*/
public interface SubContextList
{
/**
- * NEEDSDOC Method getLastPos
+ * Get the number of nodes in the node list, which, in the XSLT 1 based
+ * counting system, is the last index position.
*
*
- * NEEDSDOC @param xctxt
+ * @param xctxt The XPath runtime context.
*
- * NEEDSDOC (getLastPos) @return
+ * @return the number of nodes in the node list.
*/
public int getLastPos(XPathContext xctxt);
/**
* Get the current sub-context position.
*
- * NEEDSDOC @param xctxt
+ * @param xctxt The XPath runtime context.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The position of the current node in the list.
*/
public int getProximityPosition(XPathContext xctxt);
}
1.12 +59 -41
xml-xalan/java/src/org/apache/xpath/axes/UnionPathIterator.java
Index: UnionPathIterator.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xpath/axes/UnionPathIterator.java,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- UnionPathIterator.java 2000/12/16 17:16:26 1.11
+++ UnionPathIterator.java 2000/12/17 17:40:01 1.12
@@ -101,10 +101,11 @@
}
/**
- * NEEDSDOC Method initContext
+ * Initialize the context values for this expression
+ * after it is cloned.
*
- *
- * NEEDSDOC @param execContext
+ * @param execContext The XPath runtime context for this
+ * transformation.
*/
public void initContext(XPathContext execContext)
{
@@ -149,16 +150,18 @@
m_pool.freeInstance(this);
}
- /** NEEDSDOC Field m_pool */
+ /** Pool of UnionPathIterators. (The need for this has to be
re-evaluated. -sb) */
transient ObjectPool m_pool = new ObjectPool(this.getClass());
/**
- * NEEDSDOC Method execute
- *
+ * Execute this iterator, meaning create a clone that can
+ * store state, and initialize it for fast execution from
+ * the current runtime state. When this is called, no actual
+ * query from the current context node is performed.
*
- * NEEDSDOC @param xctxt
+ * @param xctxt The XPath execution context.
*
- * NEEDSDOC (execute) @return
+ * @return An XNodeSet reference that holds this iterator.
*
* @throws javax.xml.transform.TransformerException
*/
@@ -182,17 +185,20 @@
return null;
}
- /** NEEDSDOC Field m_cachedNodes */
+ /** If this iterator needs to cache nodes that are fetched, they
+ * are stored here. */
transient NodeSet m_cachedNodes = null;
- /** NEEDSDOC Field m_next */
+ /** The index of the next node to be fetched. Useful if this
+ * is a cached iterator, and is being used as random access
+ * NodeList. */
protected int m_next = 0;
/**
* If setShouldCacheNodes(true) is called, then nodes will
* be cached. They are not cached by default.
*
- * NEEDSDOC @param b
+ * @param b True if this iterator should cache nodes.
*/
public void setShouldCacheNodes(boolean b)
{
@@ -222,7 +228,7 @@
/**
* Get the length of the list.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The length of this list, or zero is this is not a cached list.
*/
public int size()
{
@@ -238,7 +244,7 @@
* the first nextNode() that is called will return the
* first node in the set.
*
- * NEEDSDOC ($objectName$) @return
+ * @return True if the iteration has not yet begun.
*/
public boolean isFresh()
{
@@ -269,7 +275,8 @@
* iterator. The available set of constants is defined in the
* <code>NodeFilter</code> interface.
*
- * NEEDSDOC ($objectName$) @return
+ * @return A bit set that tells what node types to show
(NodeFilter.SHOW_ALL at
+ * the iterator level).
*/
public int getWhatToShow()
{
@@ -281,7 +288,7 @@
/**
* The filter used to screen nodes.
*
- * NEEDSDOC ($objectName$) @return
+ * @return null.
*/
public NodeFilter getFilter()
{
@@ -291,7 +298,7 @@
/**
* The root node of the Iterator, as specified when it was created.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The context node of this iterator.
*/
public Node getRoot()
{
@@ -310,7 +317,7 @@
* expansion, use the whatToShow flags to show the entity reference node
* and set expandEntityReferences to false.
*
- * NEEDSDOC ($objectName$) @return
+ * @return true.
*/
public boolean getExpandEntityReferences()
{
@@ -320,7 +327,7 @@
/**
* Add an iterator to the union list.
*
- * NEEDSDOC @param iter
+ * @param iter non-null reference to a location path iterator.
*/
public void addIterator(LocPathIterator iter)
{
@@ -346,10 +353,14 @@
}
/**
- * Constructor.
- *
- * NEEDSDOC @param compiler
- * NEEDSDOC @param opPos
+ * Create a UnionPathIterator object, including creation
+ * of location path iterators from the opcode list, and call back
+ * into the Compiler to create predicate expressions.
+ *
+ * @param compiler The Compiler which is creating
+ * this expression.
+ * @param opPos The position of this iterator in the
+ * opcode list from the compiler.
*
* @throws javax.xml.transform.TransformerException
*/
@@ -365,9 +376,10 @@
}
/**
- * Get a cloned UnionPathIterator.
+ * Get a cloned Iterator that is reset to the beginning
+ * of the query.
*
- * NEEDSDOC ($objectName$) @return
+ * @return A cloned NodeIterator set of the start of the query.
*
* @throws CloneNotSupportedException
*/
@@ -382,9 +394,10 @@
}
/**
- * Get a cloned UnionPathIterator.
+ * Get a cloned LocPathIterator that holds the same
+ * position as this iterator.
*
- * NEEDSDOC ($objectName$) @return
+ * @return A clone of this iterator that holds the same node position.
*
* @throws CloneNotSupportedException
*/
@@ -423,11 +436,13 @@
}
/**
- * Initialize the location path iterators.
+ * Initialize the location path iterators. Recursive.
*
- * NEEDSDOC @param compiler
- * NEEDSDOC @param opPos
- * NEEDSDOC @param count
+ * @param compiler The Compiler which is creating
+ * this expression.
+ * @param opPos The position of this iterator in the
+ * opcode list from the compiler.
+ * @param count The insert position of the iterator.
*
* @throws javax.xml.transform.TransformerException
*/
@@ -475,10 +490,11 @@
/**
* Create a new location path iterator.
*
- * NEEDSDOC @param compiler
- * NEEDSDOC @param opPos
+ * @param compiler The Compiler which is creating
+ * this expression.
+ * @param opPos The position of this iterator in the
*
- * NEEDSDOC ($objectName$) @return
+ * @return New location path iterator.
*
* @throws javax.xml.transform.TransformerException
*/
@@ -488,7 +504,7 @@
return WalkerFactory.newLocPathIterator(compiler, opPos);
}
- /** NEEDSDOC Field m_lastFetched */
+ /** The last node that was fetched, usually by nextNode. */
transient Node m_lastFetched;
/**
@@ -580,7 +596,8 @@
* m_next to the index. If the index argument is -1, this
* signals that the iterator should be run to the end.
*
- * NEEDSDOC @param index
+ * @param index The index to run to, or -1 if the iterator
+ * should run to the end.
*/
public void runTo(int index)
{
@@ -603,7 +620,8 @@
* you call getCurrentPos() and the return is 0, the next
* fetch will take place at index 1.
*
- * NEEDSDOC ($objectName$) @return
+ * @return A value greater than or equal to zero that indicates the next
+ * node position to fetch.
*/
public int getCurrentPos()
{
@@ -611,9 +629,9 @@
}
/**
- * Return the last fetched node. Needed to support the UnionPathIterator.
+ * Return the last fetched node.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The last fetched node, or null if the last fetch was null.
*/
public Node getCurrentNode()
{
@@ -642,10 +660,10 @@
transient protected Node m_currentContextNode;
/**
- * NEEDSDOC Method getCurrentContextNode
- *
+ * The node context from where the expression is being
+ * executed from (i.e. for current() support).
*
- * NEEDSDOC (getCurrentContextNode) @return
+ * @return The top-level node context of the entire expression.
*/
public Node getCurrentContextNode()
{
