Document that path parameters should use '/' as separator

Bug: 421600
Change-Id: I505d994518aa608aaa797252433b6c97e2def5b4
Signed-off-by: Robin Stocker <robin@nibor.org>

14 files changed, 36 insertions, 22 deletions

diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/AddCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/AddCommand.java
index ef2e987b4e..c23256c74b 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/api/AddCommand.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/AddCommand.java
@@ -93,11 +93,15 @@ public class AddCommand extends GitCommand<DirCache> {
 	}
 
 	/**
+	 * Add a path to a file/directory whose content should be added.
+	 * <p>
+	 * A directory name (e.g. <code>dir</code> to add <code>dir/file1</code> and
+	 * <code>dir/file2</code>) can also be given to add all files in the
+	 * directory, recursively. Fileglobs (e.g. *.c) are not yet supported.
+	 *
 	 * @param filepattern
-	 *            File to add content from. Also a leading directory name (e.g.
-	 *            dir to add dir/file1 and dir/file2) can be given to add all
-	 *            files in the directory, recursively. Fileglobs (e.g. *.c) are
-	 *            not yet supported.
+	 *            repository-relative path of file/directory to add (with
+	 *            <code>/</code> as separator)
 	 * @return {@code this}
 	 */
 	public AddCommand addFilepattern(String filepattern) {
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/BlameCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/BlameCommand.java
index 12be64bb02..11dfd1c585 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/api/BlameCommand.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/BlameCommand.java
@@ -86,9 +86,10 @@ public class BlameCommand extends GitCommand<BlameResult> {
 	}
 
 	/**
-	 * Set file path
+	 * Set file path.
 	 *
 	 * @param filePath
+	 *            file path (with <code>/</code> as separator)
 	 * @return this command
 	 */
 	public BlameCommand setFilePath(String filePath) {
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/CheckoutCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/CheckoutCommand.java
index eb447f3142..8dfd211a08 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/api/CheckoutCommand.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/CheckoutCommand.java
@@ -305,15 +305,16 @@ public class CheckoutCommand extends GitCommand<Ref> {
 	}
 
 	/**
-	 * Add a single path to the list of paths to check out. To check out all
-	 * paths, use {@link #setAllPaths(boolean)}.
+	 * Add a single slash-separated path to the list of paths to check out. To
+	 * check out all paths, use {@link #setAllPaths(boolean)}.
 	 * <p>
 	 * If this option is set, neither the {@link #setCreateBranch(boolean)} nor
 	 * {@link #setName(String)} option is considered. In other words, these
 	 * options are exclusive.
 	 *
 	 * @param path
-	 *            path to update in the working tree and index
+	 *            path to update in the working tree and index (with
+	 *            <code>/</code> as separator)
 	 * @return {@code this}
 	 */
 	public CheckoutCommand addPath(String path) {
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/CleanCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/CleanCommand.java
index b42c80f67b..f273eafe1f 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/api/CleanCommand.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/CleanCommand.java
@@ -174,7 +174,7 @@ public class CleanCommand extends GitCommand<Set<String>> {
 	 * If paths are set, only these paths are affected by the cleaning.
 	 *
 	 * @param paths
-	 *            the paths to set
+	 *            the paths to set (with <code>/</code> as separator)
 	 * @return {@code this}
 	 */
 	public CleanCommand setPaths(Set<String> paths) {
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/CommitCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/CommitCommand.java
index 399d78e095..21d7138c9f 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/api/CommitCommand.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/CommitCommand.java
@@ -667,14 +667,14 @@ public class CommitCommand extends GitCommand<RevCommit> {
 	}
 
 	/**
-	 * Commit dedicated path only
-	 *
+	 * Commit dedicated path only.
+	 * <p>
 	 * This method can be called several times to add multiple paths. Full file
 	 * paths are supported as well as directory paths; in the latter case this
-	 * commits all files/ directories below the specified path.
+	 * commits all files/directories below the specified path.
 	 *
 	 * @param only
-	 *            path to commit
+	 *            path to commit (with <code>/</code> as separator)
 	 * @return {@code this}
 	 */
 	public CommitCommand setOnly(String only) {
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/LogCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/LogCommand.java
index 51a233458f..9690f799c1 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/api/LogCommand.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/LogCommand.java
@@ -282,11 +282,11 @@ public class LogCommand extends GitCommand<Iterable<RevCommit>> {
 
 	/**
 	 * Show only commits that affect any of the specified paths. The path must
-	 * either name a file or a directory exactly. Note that regex expressions or
-	 * wildcards are not supported.
+	 * either name a file or a directory exactly and use <code>/</code> (slash)
+	 * as separator. Note that regex expressions or wildcards are not supported.
 	 *
 	 * @param path
-	 *            a path is relative to the top level of the repository
+	 *            a repository-relative path (with <code>/</code> as separator)
 	 * @return {@code this}
 	 */
 	public LogCommand addPath(String path) {
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/ResetCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/ResetCommand.java
index 3a1c209a2d..7c2192dd9f 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/api/ResetCommand.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/ResetCommand.java
@@ -279,16 +279,17 @@ public class ResetCommand extends GitCommand<Ref> {
 	}
 
 	/**
-	 * @param file
-	 *            the file to add
+	 * @param path
+	 *            repository-relative path of file/directory to reset (with
+	 *            <code>/</code> as separator)
 	 * @return this instance
 	 */
-	public ResetCommand addPath(String file) {
+	public ResetCommand addPath(String path) {
 		if (mode != null)
 			throw new JGitInternalException(MessageFormat.format(
 					JGitText.get().illegalCombinationOfArguments, "<paths>...",
 					"[--mixed | --soft | --hard]")); //$NON-NLS-1$
-		filepaths.add(file);
+		filepaths.add(path);
 		return this;
 	}
 
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/RmCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/RmCommand.java
index ac30ffcb7d..c70b4aeaf2 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/api/RmCommand.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/RmCommand.java
@@ -104,7 +104,8 @@ public class RmCommand extends GitCommand<DirCache> {
 
 	/**
 	 * @param filepattern
-	 *            File to remove.
+	 *            repository-relative path of file to remove (with
+	 *            <code>/</code> as separator)
 	 * @return {@code this}
 	 */
 	public RmCommand addFilepattern(String filepattern) {
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/StatusCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/StatusCommand.java
index eaf5483671..dee0a31b91 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/api/StatusCommand.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/StatusCommand.java
@@ -89,7 +89,8 @@ public class StatusCommand extends GitCommand<Status> {
 	 * supported.
 	 *
 	 * @param path
-	 *            a path is relative to the top level of the repository
+	 *            repository-relative path of file/directory to show status for
+	 *            (with <code>/</code> as separator)
 	 * @return {@code this}
 	 * @since 3.1
 	 */
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleAddCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleAddCommand.java
index bfef053d85..09e4cf0a1b 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleAddCommand.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleAddCommand.java
@@ -93,6 +93,7 @@ public class SubmoduleAddCommand extends
 	 * Set repository-relative path of submodule
 	 *
 	 * @param path
+	 *            (with <code>/</code> as separator)
 	 * @return this command
 	 */
 	public SubmoduleAddCommand setPath(final String path) {
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleInitCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleInitCommand.java
index e799bfb8bd..0ed02acc82 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleInitCommand.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleInitCommand.java
@@ -83,6 +83,7 @@ public class SubmoduleInitCommand extends GitCommand<Collection<String>> {
 	 * Add repository-relative submodule path to initialize
 	 *
 	 * @param path
+	 *            (with <code>/</code> as separator)
 	 * @return this command
 	 */
 	public SubmoduleInitCommand addPath(final String path) {
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleStatusCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleStatusCommand.java
index bbc01adbae..6e89f9873e 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleStatusCommand.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleStatusCommand.java
@@ -83,6 +83,7 @@ public class SubmoduleStatusCommand extends
 	 * Add repository-relative submodule path to limit status reporting to
 	 *
 	 * @param path
+	 *            (with <code>/</code> as separator)
 	 * @return this command
 	 */
 	public SubmoduleStatusCommand addPath(final String path) {
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleSyncCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleSyncCommand.java
index 11d3c5acca..e7fe71a890 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleSyncCommand.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleSyncCommand.java
@@ -85,6 +85,7 @@ public class SubmoduleSyncCommand extends GitCommand<Map<String, String>> {
 	 * Add repository-relative submodule path to synchronize
 	 *
 	 * @param path
+	 *            (with <code>/</code> as separator)
 	 * @return this command
 	 */
 	public SubmoduleSyncCommand addPath(final String path) {
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleUpdateCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleUpdateCommand.java
index 40f6a9f9a4..e2f356a08e 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleUpdateCommand.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleUpdateCommand.java
@@ -110,6 +110,7 @@ public class SubmoduleUpdateCommand extends
 	 * Add repository-relative submodule path to initialize
 	 *
 	 * @param path
+	 *            (with <code>/</code> as separator)
 	 * @return this command
 	 */
 	public SubmoduleUpdateCommand addPath(final String path) {