From afbbcfc75dbd1cc3515912ec9fed9def567d466f Mon Sep 17 00:00:00 2001 From: Sebastian Sdorra Date: Thu, 21 Jun 2012 16:06:35 +0200 Subject: [PATCH] improve javadoc of repository api --- .../repository/api/BlameCommandBuilder.java | 17 +++++++++++++++- .../repository/api/BrowseCommandBuilder.java | 16 ++++++++++++++- .../scm/repository/api/CatCommandBuilder.java | 12 ++++++++++- .../repository/api/DiffCommandBuilder.java | 14 ++++++++++++- .../scm/repository/api/LogCommandBuilder.java | 20 ++++--------------- .../api/RepositoryServiceFactory.java | 13 ++++++++++-- 6 files changed, 70 insertions(+), 22 deletions(-) diff --git a/scm-core/src/main/java/sonia/scm/repository/api/BlameCommandBuilder.java b/scm-core/src/main/java/sonia/scm/repository/api/BlameCommandBuilder.java index 868cd2e6b4..ce04f58053 100644 --- a/scm-core/src/main/java/sonia/scm/repository/api/BlameCommandBuilder.java +++ b/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.
+ *
+ * Sample: + *
+ *
+ * Print each line number and code of the file scm-core/pom.xml at + * revision 60c2f2783368:
+ * 

+ * 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());
+ * }
+ *
* * @author Sebastian Sdorra * @since 1.17 diff --git a/scm-core/src/main/java/sonia/scm/repository/api/BrowseCommandBuilder.java b/scm-core/src/main/java/sonia/scm/repository/api/BrowseCommandBuilder.java index a4df503d27..d571fd6a71 100644 --- a/scm-core/src/main/java/sonia/scm/repository/api/BrowseCommandBuilder.java +++ b/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}. - * + *

+ * Sample: + *
+ *
+ * Print all paths from folder scm-core at revision 11aeec7db845:
+ * 

+ * BrowseCommandBuilder browse = repositoryService.getBrowseCommand();
+ * BrowserResult result = browse.setPath("scm-core")
+ *                              .setRevision("11aeec7db845")
+ *                              .getBrowserResult();
+ * 
+ * for ( FileObject fo : result ){
+ *   System.out.println( fo.getPath() );
+ * }
+ *
* * @author Sebastian Sdorra * @since 1.17 diff --git a/scm-core/src/main/java/sonia/scm/repository/api/CatCommandBuilder.java b/scm-core/src/main/java/sonia/scm/repository/api/CatCommandBuilder.java index dc98c713a1..546da6c167 100644 --- a/scm-core/src/main/java/sonia/scm/repository/api/CatCommandBuilder.java +++ b/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}.
+ *
+ * Sample: + *
+ *
+ * Print the content of the file core/pom.xml from revision 46a23689ac91:
+ * 

+ * CatCommandBuilder cat = repositoryService.getCatCommand();
+ * String content = cat.setRevision("46a23689ac91").getContent("core/pom.xml");
+ * System.out.println(content);
+ *
* * @author Sebastian Sdorra * @since 1.17 diff --git a/scm-core/src/main/java/sonia/scm/repository/api/DiffCommandBuilder.java b/scm-core/src/main/java/sonia/scm/repository/api/DiffCommandBuilder.java index 35ef6b0359..072a56b927 100644 --- a/scm-core/src/main/java/sonia/scm/repository/api/DiffCommandBuilder.java +++ b/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.
- * Note: One of the parameter path or revision have to be set. + * Note: One of the parameter path or revision have to be set.
+ *
+ * Sample: + *
+ *
+ * Print the differences from revision 33b93c443867:
+ * 

+ * DiffCommandBuilder diff = repositoryService.getDiffCommand();
+ * String content = diff.setRevision("33b93c443867").getContent();
+ * System.out.println(content);
+ *
+ * + * * TODO check current behavior. * * @author Sebastian Sdorra diff --git a/scm-core/src/main/java/sonia/scm/repository/api/LogCommandBuilder.java b/scm-core/src/main/java/sonia/scm/repository/api/LogCommandBuilder.java index a04570002b..fc914d321c 100644 --- a/scm-core/src/main/java/sonia/scm/repository/api/LogCommandBuilder.java +++ b/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.
*
- * Samples: + * Samples: *
*
- * Get a instance of LogCommandBuilder: - * 

- * public class Sample {
- *
- *   {@literal @}Inject
- *   public Sample(RepositoryServiceFactory factory){
- *     LogCommandBuilder log = factory.create("repository-id").getLogCommand();
- *   }
- *
- * }
- *
- * - * Retrieve a single {@link Changeset}: + * Retrieve a single {@link Changeset}:
* 

  * LogCommand log = repositoryService.getLogCommand();
  * Changeset changeset = log.getChangeset("id-of-the-commit");
  *
* - * Retrieve changesets of a {@link Repository} with paging: + * Retrieve changesets of a {@link Repository} with paging:
* 

  * LogCommand log = repositoryService.getLogCommand();
  * ChangesetPagingResult changesetPagingResult =
  *          log.setPagingStart(25).setPagingLimit(25).getChangesets();
  *
* - * Retrieve all changesets of a file in a {@link Repository}: + * Retrieve all changesets of a file in a {@link Repository}:
* 

  * LogCommand log = repositoryService.getLogCommand();
  * ChangesetPagingResult changesetPagingResult =
diff --git a/scm-core/src/main/java/sonia/scm/repository/api/RepositoryServiceFactory.java b/scm-core/src/main/java/sonia/scm/repository/api/RepositoryServiceFactory.java
index 7e5bdf2f86..78775e678a 100644
--- a/scm-core/src/main/java/sonia/scm/repository/api/RepositoryServiceFactory.java
+++ b/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;
  *   }
  *
  * }