Improve description of isBare and NoWorkTreeException

Alex pointed out that my description of a bare repository might be
confusing for some readers.  Reword the description of the error,
and make it consistent throughout the Repository class's API.

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

1 files changed, 17 insertions, 10 deletions

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 a60cba56fa..d1e6cae6e9 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java
@@ -161,8 +161,8 @@ public abstract class Repository {
 	 * directories.
 	 *
 	 * @param bare
-	 *            if true, a bare repository is created.
-	 *
+	 *            if true, a bare repository (a repository without a working
+	 *            directory) is created.
 	 * @throws IOException
 	 *             in case of IO problem
 	 */
@@ -863,7 +863,8 @@ public abstract class Repository {
 	 * @throws IOException
 	 *             if the index can not be read
 	 * @throws NoWorkTreeException
-	 *             if this is bare (see {@link #isBare()})
+	 *             if this is bare, which implies it has no working directory.
+	 *             See {@link #isBare()}.
 	 */
 	public GitIndex getIndex() throws IOException, NoWorkTreeException {
 		if (isBare())
@@ -880,7 +881,8 @@ public abstract class Repository {
 	/**
 	 * @return the index file location
 	 * @throws NoWorkTreeException
-	 *             if this is bare (see {@link #isBare()})
+	 *             if this is bare, which implies it has no working directory.
+	 *             See {@link #isBare()}.
 	 */
 	public File getIndexFile() throws NoWorkTreeException {
 		if (isBare())
@@ -898,7 +900,8 @@ public abstract class Repository {
 	 * @return a cache representing the contents of the specified index file (if
 	 *         it exists) or an empty cache if the file does not exist.
 	 * @throws NoWorkTreeException
-	 *             if the repository is bare (lacks a working directory).
+	 *             if this is bare, which implies it has no working directory.
+	 *             See {@link #isBare()}.
 	 * @throws IOException
 	 *             the index file is present but could not be read.
 	 * @throws CorruptObjectException
@@ -920,7 +923,8 @@ public abstract class Repository {
 	 * @return a cache representing the contents of the specified index file (if
 	 *         it exists) or an empty cache if the file does not exist.
 	 * @throws NoWorkTreeException
-	 *             if the repository is bare (lacks a working directory).
+	 *             if this is bare, which implies it has no working directory.
+	 *             See {@link #isBare()}.
 	 * @throws IOException
 	 *             the index file is present but could not be read, or the lock
 	 *             could not be obtained.
@@ -1072,7 +1076,7 @@ public abstract class Repository {
 	}
 
 	/**
-	 * @return the "bare"-ness of this Repository
+	 * @return true if this is bare, which implies it has no working directory.
 	 */
 	public boolean isBare() {
 		return workTree == null;
@@ -1082,7 +1086,8 @@ public abstract class Repository {
 	 * @return the root directory of the working tree, where files are checked
 	 *         out for viewing and editing.
 	 * @throws NoWorkTreeException
-	 *             if the repository is bare and has no working directory.
+	 *             if this is bare, which implies it has no working directory.
+	 *             See {@link #isBare()}.
 	 */
 	public File getWorkTree() throws NoWorkTreeException {
 		if (isBare())
@@ -1130,7 +1135,8 @@ public abstract class Repository {
 	 *         {@code null} if this file doesn't exist
 	 * @throws IOException
 	 * @throws NoWorkTreeException
-	 *             if the repository is "bare"
+	 *             if this is bare, which implies it has no working directory.
+	 *             See {@link #isBare()}.
 	 */
 	public String readMergeCommitMsg() throws IOException, NoWorkTreeException {
 		if (isBare() || getDirectory() == null)
@@ -1156,7 +1162,8 @@ public abstract class Repository {
 	 *         exists but is empty {@code null} will be returned
 	 * @throws IOException
 	 * @throws NoWorkTreeException
-	 *             if the repository is "bare"
+	 *             if this is bare, which implies it has no working directory.
+	 *             See {@link #isBare()}.
 	 */
 	public List<ObjectId> readMergeHeads() throws IOException, NoWorkTreeException {
 		if (isBare() || getDirectory() == null)