Cleanup and correct resolve Javadoc

We didn't fully cover what we support and what we don't.  It was
also a bit hard to follow the syntaxes supported.  Clean that up
by documenting it.

Change-Id: I7b96fa6cbefcc2364a51f336712ad361ae42df2d
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>

org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java

@@ -374,20 +374,34 @@ public abstract class Repository {
 	/**
 	 * Parse a git revision string and return an object id.
 	 *
-	 * Currently supported is combinations of these.
+	 * Combinations of these operators are supported:
 	 * <ul>
-	 * <li>SHA-1 - a SHA-1</li>
+	 * <li><b>HEAD</b>, <b>MERGE_HEAD</b>, <b>FETCH_HEAD</b></li>
-	 * <li>refs/... - a ref name</li>
+	 * <li><b>SHA-1</b>: a complete or abbreviated SHA-1</li>
-	 * <li>ref^n - nth parent reference</li>
+	 * <li><b>refs/...</b>: a complete reference name</li>
-	 * <li>ref~n - distance via parent reference</li>
+	 * <li><b>short-name</b>: a short reference name under {@code refs/heads},
-	 * <li>ref@{n} - nth version of ref</li>
+	 * {@code refs/tags}, or {@code refs/remotes} namespace</li>
-	 * <li>ref^{tree} - tree references by ref</li>
+	 * <li><b>tag-NN-gABBREV</b>: output from describe, parsed by treating
-	 * <li>ref^{commit} - commit references by ref</li>
+	 * {@code ABBREV} as an abbreviated SHA-1.</li>
+	 * <li><i>id</i><b>^</b>: first parent of commit <i>id</i>, this is the same
+	 * as {@code id^1}</li>
+	 * <li><i>id</i><b>^0</b>: ensure <i>id</i> is a commit</li>
+	 * <li><i>id</i><b>^n</b>: n-th parent of commit <i>id</i></li>
+	 * <li><i>id</i><b>~n</b>: n-th historical ancestor of <i>id</i>, by first
+	 * parent. {@code id~3} is equivalent to {@code id^1^1^1} or {@code id^^^}.</li>
+	 * <li><i>id</i><b>:path</b>: Lookup path under tree named by <i>id</i></li>
+	 * <li><i>id</i><b>^{commit}</b>: ensure <i>id</i> is a commit</li>
+	 * <li><i>id</i><b>^{tree}</b>: ensure <i>id</i> is a tree</li>
+	 * <li><i>id</i><b>^{tag}</b>: ensure <i>id</i> is a tag</li>
+	 * <li><i>id</i><b>^{blob}</b>: ensure <i>id</i> is a blob</li>
 	 * </ul>
 	 *
-	 * Not supported is:
+	 * <p>
+	 * The following operators are specified by Git conventions, but are not
+	 * supported by this method:
 	 * <ul>
-	 * <li>timestamps in reflogs, ref@{full or relative timestamp}</li>
+	 * <li><b>ref@{n}</b>: n-th version of ref as given by its reflog</li>
+	 * <li><b>ref@{time}</b>: value of ref at the designated time</li>
 	 * </ul>
 	 *
 	 * @param revstr
@@ -397,6 +411,12 @@ public abstract class Repository {
 	 *             {@code revstr} contains an abbreviated ObjectId and this
 	 *             repository contains more than one object which match to the
 	 *             input abbreviation.
+	 * @throws IncorrectObjectTypeException
+	 *             the id parsed does not meet the type required to finish
+	 *             applying the operators in the expression.
+	 * @throws RevisionSyntaxException
+	 *             the expression is not supported by this implementation, or
+	 *             does not meet the standard syntax.
 	 * @throws IOException
 	 *             on serious errors
 	 */