improve javadoc of repository api

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

@@ -57,7 +57,22 @@ import java.io.Serializable;
 
 /**
  * Shows changeset information by line for a given file.
- * Blame is also known as annotate in some SCM systems.
+ * Blame is also known as annotate in some SCM systems.<br />
+ * <br />
+ * <b>Sample:</b>
+ * <br />
+ * <br />
+ * Print each line number and code of the file scm-core/pom.xml at 
+ * revision  60c2f2783368:<br />
+ * <pre><code>
+ * BlameCommandBuilder blame = repositoryService.getBlameCommand();
+ * BlameResult result = blame.setRevision("60c2f2783368")
+ *                           .getBlameResult("scm-core/pom.xml");
+ * 
+ * for ( BlameLine line : result ){
+ *   System.out.println(line.getLineNumber() + ": " + line.getCode());
+ * }
+ * </code></pre>
  *
  * @author Sebastian Sdorra
  * @since 1.17

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

@@ -56,7 +56,21 @@ import java.io.Serializable;
 
 /**
  * BrowseCommandBuilder is able to browse the files of a {@link Repository}.
- *
+ * <br /><br />
+ * <b>Sample:</b>
+ * <br />
+ * <br />
+ * Print all paths from folder scm-core at revision 11aeec7db845:<br />
+ * <pre><code>
+ * BrowseCommandBuilder browse = repositoryService.getBrowseCommand();
+ * BrowserResult result = browse.setPath("scm-core")
+ *                              .setRevision("11aeec7db845")
+ *                              .getBrowserResult();
+ * 
+ * for ( FileObject fo : result ){
+ *   System.out.println( fo.getPath() );
+ * }
+ * </pre></code>
  *
  * @author Sebastian Sdorra
  * @since 1.17

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

@@ -54,7 +54,17 @@ import java.io.IOException;
 import java.io.OutputStream;
 
 /**
- * Shows the content of a file in the {@link Repository}.
+ * Shows the content of a file in the {@link Repository}.<br />
+ * <br />
+ * <b>Sample:</b>
+ * <br />
+ * <br />
+ * Print the content of the file core/pom.xml from revision 46a23689ac91:<br />
+ * <pre><code>
+ * CatCommandBuilder cat = repositoryService.getCatCommand();
+ * String content = cat.setRevision("46a23689ac91").getContent("core/pom.xml");
+ * System.out.println(content);
+ * </code></pre>
  *
  * @author Sebastian Sdorra
  * @since 1.17

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

@@ -54,7 +54,19 @@ import java.io.OutputStream;
 /**
  * Shows differences between revisions for a specified file or
  * the entire revision.<br />
- * <b>Note:</b> One of the parameter path or revision have to be set.
+ * <b>Note:</b> One of the parameter path or revision have to be set.<br />
+ * <br />
+ * <b>Sample:</b>
+ * <br />
+ * <br />
+ * Print the differences from revision 33b93c443867:<br />
+ * <pre><code>
+ * DiffCommandBuilder diff = repositoryService.getDiffCommand();
+ * String content = diff.setRevision("33b93c443867").getContent();
+ * System.out.println(content);
+ * </code></pre>
+ * 
+ * 
  * TODO check current behavior.
  *
  * @author Sebastian Sdorra

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

@@ -63,35 +63,23 @@ import java.io.Serializable;
  * or to get a list of changesets in a {@link ChangesetPagingResult}
  * which can be used for paging.<br />
  * <br />
- * <b>Samples</b>:
+ * <b>Samples:</b>
  * <br />
  * <br />
- * <b>Get a instance of LogCommandBuilder:</b>
- * <pre><code>
- * public class Sample {
- *
- *   {@literal @}Inject
- *   public Sample(RepositoryServiceFactory factory){
- *     LogCommandBuilder log = factory.create("repository-id").getLogCommand();
- *   }
- *
- * }
- * </code></pre>
- *
- * <b>Retrieve a single {@link Changeset}:</b>
+ * Retrieve a single {@link Changeset}:<br />
  * <pre><code>
  * LogCommand log = repositoryService.getLogCommand();
  * Changeset changeset = log.getChangeset("id-of-the-commit");
  * </code></pre>
  *
- * <b>Retrieve changesets of a {@link Repository} with paging:</b>
+ * Retrieve changesets of a {@link Repository} with paging:<br />
  * <pre><code>
  * LogCommand log = repositoryService.getLogCommand();
  * ChangesetPagingResult changesetPagingResult =
  *          log.setPagingStart(25).setPagingLimit(25).getChangesets();
  * </code></pre>
  *
- * <b>Retrieve all changesets of a file in a {@link Repository}:</b>
+ * Retrieve all changesets of a file in a {@link Repository}:<br />
  * <pre><code>
  * LogCommand log = repositoryService.getLogCommand();
  * ChangesetPagingResult changesetPagingResult =

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

@@ -86,8 +86,17 @@ import java.util.Set;
  *   }
  *
  *   public Changeset getChangeset(String repositoryId, String commitId){
- *     RepositoryService service = factory.create(repositoryId);
- *     return service.getLogCommand().getChangeset(commitId);
+ *     Changeset changeset = null;
+ *     RepositoryService service = null;
+ *     try {
+ *       service = factory.create(repositoryId);
+ *       changeset = service.getLogCommand().getChangeset(commitId);
+ *     } finally {
+ *       if ( service != null ){
+ *         service.close();
+ *       }
+ *     }
+ *     return changeset;
  *   }
  *
  * }