Add JavaDoc for API

scm-core/src/main/java/sonia/scm/repository/api/MergeCommandBuilder.java

@@ -5,40 +5,118 @@ import sonia.scm.repository.Person;
 import sonia.scm.repository.spi.MergeCommand;
 import sonia.scm.repository.spi.MergeCommandRequest;
 
+/**
+ * Use this {@link MergeCommandBuilder} to merge two branches of a repository ({@link #executeMerge()}) or to check if
+ * the branches could be merged without conflicts ({@link #dryRun()}). To do so, you have to specify the name of
+ * the target branch ({@link #setTargetBranch(String)}) and the name of the branch that should be merged
+ * ({@link #setBranchToMerge(String)}). Additionally you can specify an author that should be used for the commit
+ * ({@link #setAuthor(Person)}) if you are not doing a dry run only. If no author is specified, the logged in user
+ * will be used instead.
+ *
+ * To actually merge <code>feature_branch</code> into <code>integration_branch</code> do this:
+ * <pre><code>
+ *     repositoryService.gerMergeCommand()
+ *       .setBranchToMerge("feature_branch")
+ *       .setTargetBranch("integration_branch")
+ *       .executeMerge();
+ * </code></pre>
+ *
+ * If the merge is successful, the result will look like this:
+ * <pre><code>
+ *                            O    <- Merge result (new head of integration_branch)
+ *                            |\
+ *                            | \
+ *  old integration_branch -> O  O <- feature_branch
+ *                            |  |
+ *                            O  O
+ * </code></pre>
+ *
+ * To check whether they can be merged without conflicts beforehand do this:
+ * <pre><code>
+ *     repositoryService.gerMergeCommand()
+ *       .setBranchToMerge("feature_branch")
+ *       .setTargetBranch("integration_branch")
+ *       .dryRun()
+ *       .isMergeable();
+ * </code></pre>
+ *
+ * Keep in mind that you should <em>always</em> check the result of a merge even though you may have done a dry run
+ * beforehand, because the branches can change between the dry run and the actual merge.
+ *
+ * @since 2.0.0
+ */
 public class MergeCommandBuilder {
 
   private final MergeCommand mergeCommand;
   private final MergeCommandRequest request = new MergeCommandRequest();
 
-  public MergeCommandBuilder(MergeCommand mergeCommand) {
+  MergeCommandBuilder(MergeCommand mergeCommand) {
     this.mergeCommand = mergeCommand;
   }
 
+  /**
+   * Use this to set the branch that should be merged into the target branch.
+   *
+   * <b>This is mandatory.</b>
+   *
+   * @return This builder instance.
+   */
   public MergeCommandBuilder setBranchToMerge(String branchToMerge) {
     request.setBranchToMerge(branchToMerge);
     return this;
   }
 
+  /**
+   * Use this to set the target branch the other branch should be merged into.
+   *
+   * <b>This is mandatory.</b>
+   *
+   * @return This builder instance.
+   */
   public MergeCommandBuilder setTargetBranch(String targetBranch) {
     request.setTargetBranch(targetBranch);
     return this;
   }
 
+  /**
+   * Use this to set the author of the merge commit manually. If this is omitted, the currently logged in user will be
+   * used instead.
+   *
+   * This is optional and for {@link #executeMerge()} only.
+   *
+   * @return This builder instance.
+   */
   public MergeCommandBuilder setAuthor(Person author) {
     request.setAuthor(author);
     return this;
   }
 
+  /**
+   * Use this to reset the command.
+   * @return This builder instance.
+   */
   public MergeCommandBuilder reset() {
     request.reset();
     return this;
   }
 
+  /**
+   * Use this to actually do the merge. If an automatic merge is not possible, {@link MergeCommandResult#isSuccess()}
+   * will return <code>false</code>.
+   *
+   * @return The result of the merge.
+   */
   public MergeCommandResult executeMerge() {
     Preconditions.checkArgument(request.isValid(), "revision to merge and target revision is required");
     return mergeCommand.merge(request);
   }
 
+  /**
+   * Use this to check whether the given branches can be merged autmatically. If this is possible,
+   * {@link MergeDryRunCommandResult#isMergeable()} will return <code>true</code>.
+   *
+   * @return The result whether the given branches can be merged automatically.
+   */
   public MergeDryRunCommandResult dryRun() {
     Preconditions.checkArgument(request.isValid(), "revision to merge and target revision is required");
     return mergeCommand.dryRun(request);

scm-core/src/main/java/sonia/scm/repository/api/MergeCommandResult.java

@@ -6,6 +6,11 @@ import java.util.HashSet;
 import static java.util.Collections.emptyList;
 import static java.util.Collections.unmodifiableCollection;
 
+/**
+ * This class keeps the result of a merge of branches. Use {@link #isSuccess()} to check whether the merge was
+ * sucessfully executed. If the result is <code>false</code> the merge could not be done without conflicts. In this
+ * case you can use {@link #getFilesWithConflict()} to get a list of files with merge conflicts.
+ */
 public class MergeCommandResult {
   private final Collection<String> filesWithConflict;
 
@@ -21,10 +26,18 @@ public class MergeCommandResult {
     return new MergeCommandResult(new HashSet<>(filesWithConflict));
   }
 
+  /**
+   * If this returns <code>true</code>, the merge was successfull. If this returns <code>false</code> there were
+   * merge conflicts. In this case you can use {@link #getFilesWithConflict()} to check what files could not be merged.
+   */
   public boolean isSuccess() {
     return filesWithConflict.isEmpty();
   }
 
+  /**
+   * If the merge was not successful ({@link #isSuccess()} returns <code>false</code>) this will give you a list of
+   * file paths that could not be merged automatically.
+   */
   public Collection<String> getFilesWithConflict() {
     return unmodifiableCollection(filesWithConflict);
   }

scm-core/src/main/java/sonia/scm/repository/api/MergeDryRunCommandResult.java

@@ -1,5 +1,9 @@
 package sonia.scm.repository.api;
 
+/**
+ * This class keeps the result of a merge dry run. Use {@link #isMergeable()} to check whether an automatic merge is
+ * possible or not.
+ */
 public class MergeDryRunCommandResult {
 
   private final boolean mergeable;
@@ -8,6 +12,10 @@ public class MergeDryRunCommandResult {
     this.mergeable = mergeable;
   }
 
+  /**
+   * This will return <code>true</code>, when an automatic merge is possible <em>at the moment</em>; <code>false</code>
+   * otherwise.
+   */
   public boolean isMergeable() {
     return mergeable;
   }