Merge pull request #327 from spring-io/doc

Add class-level Javadoc to sagan-site production classes
spring-attic · May 30, 2014 · 78d93eb · 78d93eb
2 parents 14141c8 + cba334d
commit 78d93eb
Show file tree

Hide file tree

Showing 82 changed files with 414 additions and 311 deletions.
diff --git a/sagan-common/src/main/java/sagan/blog/Post.java b/sagan-common/src/main/java/sagan/blog/Post.java
@@ -23,6 +23,9 @@
 
 import org.springframework.util.StringUtils;
 
+/**
+ * JPA Entity representing an individual blog post.
+ */
 @Entity
 @SuppressWarnings("serial")
 public class Post implements Serializable {

diff --git a/sagan-common/src/main/java/sagan/blog/PostCategory.java b/sagan-common/src/main/java/sagan/blog/PostCategory.java
@@ -1,5 +1,8 @@
 package sagan.blog;
 
+/**
+ * Available categories for blog posts.
+ */
 public enum PostCategory {
 
     ENGINEERING("Engineering", "engineering"),
@@ -30,5 +33,4 @@ public String getId() {
     public String toString() {
         return getDisplayName();
     }
-
 }
diff --git a/sagan-common/src/main/java/sagan/blog/PostMovedException.java b/sagan-common/src/main/java/sagan/blog/PostMovedException.java
@@ -1,7 +1,14 @@
 package sagan.blog;
 
+/**
+ * Exception thrown when requesting a blog post whose slug has changed. See
+ * {@code BlogController} for handling logic.
+ *
+ * @see sagan.blog.support.BlogService#getPublishedPost(String)
+ */
 @SuppressWarnings("serial")
 public class PostMovedException extends RuntimeException {
+
     private String publicSlug;
 
     public PostMovedException(String publicSlug) {

diff --git a/sagan-common/src/main/java/sagan/blog/PostNotFoundException.java b/sagan-common/src/main/java/sagan/blog/PostNotFoundException.java
@@ -2,6 +2,13 @@
 
 import sagan.support.ResourceNotFoundException;
 
+/**
+ * Exception thrown when requesting a non existent (or no-longer existent) blog post. See
+ * sagan-site's {@code MvcConfig#handleException} for handling logic.
+ *
+ * @see sagan.blog.support.BlogService#getPost(Long)
+ * @see sagan.blog.support.BlogService#getPublishedPost(String)
+ */
 @SuppressWarnings("serial")
 public class PostNotFoundException extends ResourceNotFoundException {
 

diff --git a/sagan-common/src/main/java/sagan/blog/support/DefaultMarkdownService.java b/sagan-common/src/main/java/sagan/blog/support/DefaultMarkdownService.java
@@ -5,6 +5,9 @@
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Service;
 
+/**
+ * A {@link MarkdownService} based on the GitHub Markdown rendering API.
+ */
 @Service
 class DefaultMarkdownService implements MarkdownService {
 
@@ -16,7 +19,7 @@ public DefaultMarkdownService(GitHubClient gitHub) {
     }
 
     /**
-     * Process the given markdown through GitHub's Markdown Rendering API. See
+     * Process the given markdown through GitHub's Markdown rendering API. See
      * http://developer.github.com/v3/markdown
      */
     @Override

diff --git a/sagan-common/src/main/java/sagan/blog/support/MarkdownService.java b/sagan-common/src/main/java/sagan/blog/support/MarkdownService.java
@@ -1,5 +1,8 @@
 package sagan.blog.support;
 
+/**
+ * Abstraction representing a service capable of translating markdown to HTML.
+ */
 interface MarkdownService {
     String renderToHtml(String markdownSource);
 }
diff --git a/sagan-common/src/main/java/sagan/guides/AbstractGuide.java b/sagan-common/src/main/java/sagan/guides/AbstractGuide.java
@@ -7,7 +7,7 @@ abstract class AbstractGuide extends AbstractDocument implements Guide {
     private final GuideMetadata metadata;
     private final ImageProvider imageProvider;
 
-    @SuppressWarnings("rawtypes") 
+    @SuppressWarnings("rawtypes")
     public AbstractGuide(GuideMetadata metadata, ContentProvider contentProvider, ImageProvider imageProvider) {
         super(contentProvider);
         this.metadata = metadata;

diff --git a/sagan-common/src/main/java/sagan/guides/support/UnderstandingDocs.java b/sagan-common/src/main/java/sagan/guides/support/UnderstandingDocs.java
@@ -5,7 +5,6 @@
 import sagan.support.ResourceNotFoundException;
 import sagan.support.github.RepoContent;
 
-import java.util.ArrayList;
 import java.util.List;
 import java.util.stream.Collectors;
 

diff --git a/sagan-common/src/main/java/sagan/search/support/SearchResultParser.java b/sagan-common/src/main/java/sagan/search/support/SearchResultParser.java
@@ -2,7 +2,6 @@
 
 import java.util.ArrayList;
 import java.util.Collections;
-import java.util.Comparator;
 import java.util.List;
 
 import org.springframework.data.domain.PageImpl;

diff --git a/sagan-common/src/main/java/sagan/tools/Release.java b/sagan-common/src/main/java/sagan/tools/Release.java
@@ -12,8 +12,8 @@ public class Release {
     @Attribute
     private String name;
 
-	@Attribute(required = false)
-	private String whatsnew;
+    @Attribute(required = false)
+    private String whatsnew;
 
     @ElementList(name = "download", type = Download.class, inline = true)
     private List<Download> downloads;
@@ -26,15 +26,15 @@ public void setName(String name) {
         this.name = name;
     }
 
-	public String getWhatsnew() {
-		return whatsnew;
-	}
+    public String getWhatsnew() {
+        return whatsnew;
+    }
 
-	public void setWhatsnew(String whatsnew) {
-		this.whatsnew = whatsnew;
-	}
+    public void setWhatsnew(String whatsnew) {
+        this.whatsnew = whatsnew;
+    }
 
-	public List<Download> getDownloads() {
+    public List<Download> getDownloads() {
         return downloads;
     }
 

diff --git a/sagan-common/src/main/java/sagan/tools/ToolSuiteDownloads.java b/sagan-common/src/main/java/sagan/tools/ToolSuiteDownloads.java
@@ -13,15 +13,15 @@ public class ToolSuiteDownloads {
     private final List<UpdateSiteArchive> archives;
     private final String shortName;
     private final String releaseName;
-	private final String whatsNew;
+    private final String whatsNew;
 
     public ToolSuiteDownloads(String shortName, String releaseName, String whatsNew,
                               Map<String, ToolSuitePlatform> platforms, List<UpdateSiteArchive> archives) {
         this.shortName = shortName;
         this.releaseName = releaseName;
         this.platforms = platforms;
         this.archives = archives;
-	    this.whatsNew = whatsNew;
+        this.whatsNew = whatsNew;
     }
 
     public List<ToolSuitePlatform> getPlatformList() {
@@ -68,11 +68,11 @@ public String getDisplayName() {
         return String.format("%s %s", shortName, releaseName);
     }
 
-	public String getWhatsNew() {
-		return whatsNew;
-	}
+    public String getWhatsNew() {
+        return whatsNew;
+    }
 
-	public boolean hasPlatforms() {
+    public boolean hasPlatforms() {
         return platforms.size() > 0;
     }
 }
diff --git a/sagan-common/src/main/java/sagan/tools/support/EclipseDownloadsBuilder.java b/sagan-common/src/main/java/sagan/tools/support/EclipseDownloadsBuilder.java
@@ -1,7 +1,6 @@
 package sagan.tools.support;
 
 import sagan.tools.Architecture;
-import sagan.tools.DownloadLink;
 import sagan.tools.EclipseDownloads;
 import sagan.tools.EclipsePackage;
 import sagan.tools.EclipsePlatform;

diff --git a/sagan-common/src/main/java/sagan/tools/support/ToolSuiteBuilder.java b/sagan-common/src/main/java/sagan/tools/support/ToolSuiteBuilder.java
@@ -23,17 +23,17 @@ class ToolSuiteBuilder {
     private Map<String, EclipseVersion> eclipseVersionMap = new LinkedHashMap<>();
     private Map<String, Architecture> architectureMap = new LinkedHashMap<>();
     private String releaseName;
-	private String whatsNew;
+    private String whatsNew;
 
     public ToolSuiteBuilder(String shortName) {
         this.shortName = shortName;
     }
 
-	public void setWhatsNew(String whatsNew) {
-		this.whatsNew = whatsNew;
-	}
+    public void setWhatsNew(String whatsNew) {
+        this.whatsNew = whatsNew;
+    }
 
-	public void addDownload(Download download) {
+    public void addDownload(Download download) {
         if (download.getOs().equals("all")) {
             extractArchive(download);
         } else {

diff --git a/sagan-common/src/main/java/sagan/tools/support/ToolXmlConverter.java b/sagan-common/src/main/java/sagan/tools/support/ToolXmlConverter.java
@@ -1,6 +1,5 @@
 package sagan.tools.support;
 
-import sagan.tools.Download;
 import sagan.tools.Release;
 import sagan.tools.ToolSuiteDownloads;
 
@@ -19,5 +18,4 @@ public ToolSuiteDownloads convert(ToolSuiteXml toolSuiteXml, String toolSuiteNam
 
         return state.build();
     }
-
 }
diff --git a/sagan-common/src/test/java/sagan/blog/support/BlogService_ValidPostTests.java b/sagan-common/src/test/java/sagan/blog/support/BlogService_ValidPostTests.java
@@ -16,9 +16,7 @@
 import org.junit.rules.ExpectedException;
 import org.junit.runner.RunWith;
 import org.mockito.Mock;
-import org.mockito.invocation.InvocationOnMock;
 import org.mockito.runners.MockitoJUnitRunner;
-import org.mockito.stubbing.Answer;
 
 import org.springframework.test.util.ReflectionTestUtils;
 

diff --git a/sagan-common/src/test/java/sagan/guides/support/DynamicSidebarTests.java b/sagan-common/src/test/java/sagan/guides/support/DynamicSidebarTests.java
@@ -1,12 +1,12 @@
 package sagan.guides.support;
 
-import org.junit.Ignore;
 import sagan.support.github.GitHubClient;
 
 import java.io.IOException;
 import java.io.InputStream;
 
 import org.junit.Before;
+import org.junit.Ignore;
 import org.junit.Test;
 import org.mockito.Mock;
 

diff --git a/sagan-common/src/test/java/sagan/tools/support/ToolSuiteTests.java b/sagan-common/src/test/java/sagan/tools/support/ToolSuiteTests.java
@@ -111,6 +111,7 @@ private ToolSuiteDownloads buildToolSuite() {
                 linuxArchitectures))));
 
         List<UpdateSiteArchive> archives = Collections.emptyList();
-        return new ToolSuiteDownloads("ShortName", "3.1.2.RELEASE", "http://static.springsource.org/sts/nan/latest/NewAndNoteworthy.html",platforms, archives);
+        return new ToolSuiteDownloads("ShortName", "3.1.2.RELEASE",
+                "http://static.springsource.org/sts/nan/latest/NewAndNoteworthy.html", platforms, archives);
     }
 }
diff --git a/sagan-common/src/test/java/sagan/tools/support/ToolSuiteXmlParsingTests.java b/sagan-common/src/test/java/sagan/tools/support/ToolSuiteXmlParsingTests.java
@@ -1,6 +1,5 @@
 package sagan.tools.support;
 
-import org.mockito.Matchers;
 import sagan.support.Fixtures;
 import sagan.tools.Release;
 
@@ -23,6 +22,6 @@ public void unmarshal() throws Exception {
         assertThat(toolSuiteXml.getReleases().size(), equalTo(8));
         Release release = toolSuiteXml.getReleases().get(0);
         assertThat(release.getDownloads().size(), equalTo(16));
-	    assertThat(release.getWhatsnew(), notNullValue());
+        assertThat(release.getWhatsnew(), notNullValue());
     }
 }
diff --git a/sagan-common/src/test/java/sagan/tools/support/ToolsServiceTests.java b/sagan-common/src/test/java/sagan/tools/support/ToolsServiceTests.java
@@ -52,9 +52,9 @@ public void testGetStsDownloads() throws Exception {
         ToolSuiteDownloads toolSuite = service.getStsGaDownloads();
         assertThat(toolSuite, notNullValue());
 
-	    assertThat(
-			    toolSuite.getWhatsNew(),
-			    equalTo("http://static.springsource.org/sts/nan/v330/NewAndNoteworthy.html"));
+        assertThat(
+                toolSuite.getWhatsNew(),
+                equalTo("http://static.springsource.org/sts/nan/v330/NewAndNoteworthy.html"));
 
         List<ToolSuitePlatform> platforms = toolSuite.getPlatformList();
         assertThat(platforms.size(), equalTo(3));
@@ -94,9 +94,9 @@ public void testGetGgtsDownloads() throws Exception {
         ToolSuiteDownloads toolSuite = service.getGgtsGaDownloads();
         assertThat(toolSuite, notNullValue());
 
-	    assertThat(
-			    toolSuite.getWhatsNew(),
-			    equalTo("http://static.springsource.org/ggts/nan/v330/NewAndNoteworthy.html"));
+        assertThat(
+                toolSuite.getWhatsNew(),
+                equalTo("http://static.springsource.org/ggts/nan/v330/NewAndNoteworthy.html"));
 
         List<ToolSuitePlatform> platforms = toolSuite.getPlatformList();
         assertThat(platforms.size(), equalTo(3));

diff --git a/sagan-indexer/src/main/java/sagan/docs/support/ProjectDocumentationIndexer.java b/sagan-indexer/src/main/java/sagan/docs/support/ProjectDocumentationIndexer.java
@@ -8,7 +8,6 @@
 import sagan.search.support.CrawlerService;
 import sagan.search.support.SearchService;
 
-import java.util.ArrayList;
 import java.util.List;
 import java.util.stream.Collectors;
 

diff --git a/sagan-indexer/src/main/java/sagan/staticpage/support/StaticPageIndexer.java b/sagan-indexer/src/main/java/sagan/staticpage/support/StaticPageIndexer.java
@@ -7,9 +7,7 @@
 import sagan.support.StaticPagePathFinder;
 
 import java.io.IOException;
-import java.util.ArrayList;
 import java.util.HashSet;
-import java.util.List;
 import java.util.Set;
 import java.util.stream.Collectors;
 

diff --git a/sagan-indexer/src/test/java/sagan/guides/support/GuideSearchEntryMapperTests.java b/sagan-indexer/src/test/java/sagan/guides/support/GuideSearchEntryMapperTests.java
@@ -4,7 +4,6 @@
 import sagan.guides.DefaultGuideMetadata;
 import sagan.guides.GettingStartedGuide;
 import sagan.guides.Guide;
-import sagan.guides.ImageProvider;
 import sagan.search.SearchEntry;
 
 import org.junit.Before;

diff --git a/sagan-indexer/src/test/java/sagan/guides/support/UnderstandingDocMapperTests.java b/sagan-indexer/src/test/java/sagan/guides/support/UnderstandingDocMapperTests.java
@@ -1,6 +1,5 @@
 package sagan.guides.support;
 
-import sagan.guides.ContentProvider;
 import sagan.guides.UnderstandingDoc;
 import sagan.search.SearchEntry;
 import sagan.support.Fixtures;

diff --git a/sagan-site/src/it/java/sagan/blog/support/BlogAtomFeedsTests.java b/sagan-site/src/it/java/sagan/blog/support/BlogAtomFeedsTests.java
@@ -4,7 +4,6 @@
 import sagan.blog.PostBuilder;
 import sagan.blog.PostCategory;
 import sagan.support.DateFactory;
-import sagan.support.nav.SiteUrl;
 import saganx.AbstractIntegrationTests;
 
 import java.io.ByteArrayInputStream;

diff --git a/sagan-site/src/it/java/sagan/blog/support/BlogIndexTests.java b/sagan-site/src/it/java/sagan/blog/support/BlogIndexTests.java
@@ -8,7 +8,6 @@
 import java.util.ArrayList;
 import java.util.Calendar;
 import java.util.List;
-import java.util.stream.Collectors;
 
 import org.jsoup.Jsoup;
 import org.jsoup.nodes.Document;

diff --git a/sagan-site/src/it/java/sagan/blog/support/BlogServiceCachingTests.java b/sagan-site/src/it/java/sagan/blog/support/BlogServiceCachingTests.java
@@ -3,8 +3,6 @@
 import sagan.DatabaseConfig;
 import saganx.AbstractIntegrationTests;
 
-import java.lang.reflect.Method;
-
 import org.junit.Test;
 
 import org.springframework.aop.Advisor;
@@ -57,5 +55,4 @@ public void blogServiceIsAdvisedForCaching() {
                 }
             });
     }
-
 }
diff --git a/sagan-site/src/it/java/sagan/blog/support/BlogService_QueryTests.java b/sagan-site/src/it/java/sagan/blog/support/BlogService_QueryTests.java
@@ -1,8 +1,8 @@
 package sagan.blog.support;
 
-import sagan.blog.PostNotFoundException;
 import sagan.blog.Post;
 import sagan.blog.PostBuilder;
+import sagan.blog.PostNotFoundException;
 import sagan.search.support.SearchService;
 import sagan.support.DateFactory;
 import sagan.support.nav.PageableFactory;

diff --git a/sagan-site/src/it/java/sagan/blog/support/CreateBlogPostTests.java b/sagan-site/src/it/java/sagan/blog/support/CreateBlogPostTests.java
@@ -14,8 +14,6 @@
 
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.test.web.servlet.MockMvc;
-import org.springframework.test.web.servlet.MvcResult;
-import org.springframework.test.web.servlet.ResultMatcher;
 import org.springframework.test.web.servlet.request.MockHttpServletRequestBuilder;
 import org.springframework.test.web.servlet.setup.MockMvcBuilders;
 import org.springframework.web.context.WebApplicationContext;

diff --git a/sagan-site/src/it/java/sagan/blog/support/DeleteBlogPostTests.java b/sagan-site/src/it/java/sagan/blog/support/DeleteBlogPostTests.java
@@ -10,8 +10,6 @@
 
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.test.web.servlet.MockMvc;
-import org.springframework.test.web.servlet.MvcResult;
-import org.springframework.test.web.servlet.ResultMatcher;
 import org.springframework.test.web.servlet.request.MockHttpServletRequestBuilder;
 import org.springframework.test.web.servlet.setup.MockMvcBuilders;
 import org.springframework.web.context.WebApplicationContext;

diff --git a/sagan-site/src/it/java/sagan/blog/support/EditBlogPostTests.java b/sagan-site/src/it/java/sagan/blog/support/EditBlogPostTests.java
@@ -10,8 +10,6 @@
 
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.test.web.servlet.MockMvc;
-import org.springframework.test.web.servlet.MvcResult;
-import org.springframework.test.web.servlet.ResultMatcher;
 import org.springframework.test.web.servlet.request.MockHttpServletRequestBuilder;
 import org.springframework.test.web.servlet.setup.MockMvcBuilders;
 import org.springframework.web.context.WebApplicationContext;