Commits

Anonymous committed a4e0a74

Document TreeReference.anchor() with JavaDoc.

Comments (0)

Files changed (1)

core/src/org/javarosa/core/model/instance/TreeReference.java

 		}
 	}
 	
-	
-	//very similar to parent(), but assumes contextRef refers to a singular, existing node in the model
-	//this means we can do '/a/b/c + ../../d/e/f = /a/d/e/f', which we couldn't do in parent()
-	//return null if context ref is not absolute, or we parent up past the root node
-	//NOTE: this function still works even when contextRef contains INDEX_UNBOUND multiplicites... conditions depend on this behavior,
-	//  even though it's slightly icky
-	public TreeReference anchor (TreeReference contextRef) {
+	/**
+	 * This is very similar to {@link #parent()}, but assumes that
+	 * contextRef refers to a singular, existing node in the model.
+	 * <p>
+	 * This means we can do '/a/b/c + ../../d/e/f = /a/d/e/f', which we
+	 * couldn't do in parent().
+	 * <p>
+	 * NOTE: this function still works even when contextRef contains
+	 * INDEX_UNBOUND multiplicites... conditions depend on this behavior,
+	 * even though it's slightly icky.
+	 * 
+	 * @return An absolute version of ourself. If it's already
+	 * {@link #isAbsolute() absolute}, that's just a clone of ourself.
+	 * Otherwise the contextRef is used to make our path absolute.
+	 * Returns null if neither ourself nor the contextRef is absolute,
+	 * or our own relative path takes us past the root node of the
+	 * contextRef.
+	 * 
+	 * @param contextRef Used if this {@link TreeReference} is not already
+	 * absolute, to provide the context to make it absolute.
+	 */
+	public TreeReference anchor(TreeReference contextRef) {
 		if (isAbsolute()) {
 			return this.clone();
 		} else if (!contextRef.isAbsolute()) {