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>

diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java
index c3d1d494899c872e992e8a3aa926784002957830..5c8b15f5a6c5ae006a5a46637b9e05978dfb06be 100644 (file)
--- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java
+++ b/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>refs/... - a ref name</li>
-        * <li>ref^n - nth parent reference</li>
-        * <li>ref~n - distance via parent reference</li>
-        * <li>ref@{n} - nth version of ref</li>
-        * <li>ref^{tree} - tree references by ref</li>
-        * <li>ref^{commit} - commit references by ref</li>
+        * <li><b>HEAD</b>, <b>MERGE_HEAD</b>, <b>FETCH_HEAD</b></li>
+        * <li><b>SHA-1</b>: a complete or abbreviated SHA-1</li>
+        * <li><b>refs/...</b>: a complete reference name</li>
+        * <li><b>short-name</b>: a short reference name under {@code refs/heads},
+        * {@code refs/tags}, or {@code refs/remotes} namespace</li>
+        * <li><b>tag-NN-gABBREV</b>: output from describe, parsed by treating
+        * {@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
         */