diff --git a/src/main/java/org/apache/maven/plugins/site/deploy/AbstractDeployMojo.java b/src/main/java/org/apache/maven/plugins/site/deploy/AbstractDeployMojo.java
index 415e59e..2355534 100644
--- a/src/main/java/org/apache/maven/plugins/site/deploy/AbstractDeployMojo.java
+++ b/src/main/java/org/apache/maven/plugins/site/deploy/AbstractDeployMojo.java
@@ -202,7 +202,7 @@
      * can tweak algorithm to determine this top site by implementing determineTopDistributionManagementSiteUrl().
      *
      * @return the site for deployment
-     * @throws MojoExecutionException
+     * @throws MojoExecutionException in case of issue
      * @see #determineTopDistributionManagementSiteUrl()
      */
     protected String getTopDistributionManagementSiteUrl()
@@ -229,7 +229,7 @@
      * can tweak algorithm to determine this deploy site by implementing determineDeploySite().
      *
      * @return the site for deployment
-     * @throws MojoExecutionException
+     * @throws MojoExecutionException in case of issue
      * @see #determineDeploySite()
      */
     protected Site getDeploySite()
@@ -249,7 +249,7 @@
      * Find the relative path between the distribution URLs of the top site and the current project.
      *
      * @return the relative path or "./" if the two URLs are the same.
-     * @throws MojoExecutionException
+     * @throws MojoExecutionException in case of issue
      */
     protected String getDeployModuleDirectory()
         throws MojoExecutionException
diff --git a/src/main/java/org/apache/maven/plugins/site/descriptor/AbstractSiteDescriptorMojo.java b/src/main/java/org/apache/maven/plugins/site/descriptor/AbstractSiteDescriptorMojo.java
index 6583479..829f6b3 100644
--- a/src/main/java/org/apache/maven/plugins/site/descriptor/AbstractSiteDescriptorMojo.java
+++ b/src/main/java/org/apache/maven/plugins/site/descriptor/AbstractSiteDescriptorMojo.java
@@ -49,7 +49,7 @@
     /**
      * Remote repositories used for the project.
      *
-     * @todo this is used for site descriptor resolution - it should relate to the actual project but for some reason
+     * todo this is used for site descriptor resolution - it should relate to the actual project but for some reason
      *       they are not always filled in
      */
     @Parameter( defaultValue = "${project.remoteArtifactRepositories}", readonly = true )
diff --git a/src/main/java/org/apache/maven/plugins/site/descriptor/EffectiveSiteMojo.java b/src/main/java/org/apache/maven/plugins/site/descriptor/EffectiveSiteMojo.java
index 1927ee6..879a5b6 100644
--- a/src/main/java/org/apache/maven/plugins/site/descriptor/EffectiveSiteMojo.java
+++ b/src/main/java/org/apache/maven/plugins/site/descriptor/EffectiveSiteMojo.java
@@ -51,8 +51,9 @@
 {
     /**
      * Optional parameter to write the output of this help in a given file, instead of writing to the console.
-     * <br/>
+     * <p>
      * <b>Note</b>: Could be a relative path.
+     * </p>
      */
     @Parameter( property = "output" )
     protected File output;
diff --git a/src/main/java/org/apache/maven/plugins/site/descriptor/SiteDescriptorAttachMojo.java b/src/main/java/org/apache/maven/plugins/site/descriptor/SiteDescriptorAttachMojo.java
index 191b3dd..6e46c7d 100644
--- a/src/main/java/org/apache/maven/plugins/site/descriptor/SiteDescriptorAttachMojo.java
+++ b/src/main/java/org/apache/maven/plugins/site/descriptor/SiteDescriptorAttachMojo.java
@@ -34,12 +34,12 @@
 import org.codehaus.plexus.util.FileUtils;
 
 /**
- * Adds the site descriptor (<code>site.xml</code>) to the list of files to be installed/deployed.<br/>
- * For Maven-2.x this is enabled by default only when the project has <code>pom</code> packaging since it will be used
- * by modules inheriting, but this can be enabled for other projects packaging if needed.<br/>
- * This default execution has been removed from the built-in lifecycle of Maven 3.x for <code>pom</code>-projects.
+ * Adds the site descriptor (<code>site.xml</code>) to the list of files to be installed/deployed.
+ * <p>For Maven-2.x this is enabled by default only when the project has <code>pom</code> packaging since it will be
+ * used by modules inheriting, but this can be enabled for other projects packaging if needed.</p>
+ * <p>This default execution has been removed from the built-in lifecycle of Maven 3.x for <code>pom</code>-projects.
  * Users that actually use those projects to provide a common site descriptor for sub modules will need to explicitly
- * define this goal execution to restore the intended behavior.
+ * define this goal execution to restore the intended behavior.</p>
  *
  * @author <a href="mailto:brett@apache.org">Brett Porter</a>
  *
diff --git a/src/main/java/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.java b/src/main/java/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.java
index ccb2efc..16398c8 100644
--- a/src/main/java/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.java
+++ b/src/main/java/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.java
@@ -128,7 +128,7 @@
      * This directory is expected to have the same structure as <code>siteDirectory</code>
      * (ie. one directory per Doxia-source-supported markup types).
      *
-     * @todo should we deprecate in favour of reports directly using Doxia Sink API, without this Doxia source
+     * todo should we deprecate in favour of reports directly using Doxia Sink API, without this Doxia source
      * intermediate step?
      */
     @Parameter( alias = "workingDirectory", defaultValue = "${project.build.directory}/generated-site" )
@@ -448,6 +448,13 @@
      * <li>reports,</li>
      * <li>"Project Information" and "Project Reports" category summaries.</li>
      * </ul>
+     *
+     * @param context the site context
+     * @param reports the documents
+     * @param locale the locale
+     * @return the documents and their renderers
+     * @throws IOException in case of file reading issue
+     * @throws RendererException in case of Doxia rendering issue
      * @see CategorySummaryDocumentRenderer
      */
     protected Map<String, DocumentRenderer> locateDocuments( SiteRenderingContext context,
diff --git a/src/main/java/org/apache/maven/plugins/site/render/SiteMojo.java b/src/main/java/org/apache/maven/plugins/site/render/SiteMojo.java
index 7ff56ac..f4066d8 100644
--- a/src/main/java/org/apache/maven/plugins/site/render/SiteMojo.java
+++ b/src/main/java/org/apache/maven/plugins/site/render/SiteMojo.java
@@ -91,11 +91,7 @@
     private boolean validate;
 
     /**
-     * {@inheritDoc} Generate the project site
-     * <p/>
-     * throws MojoExecutionException if any
-     *
-     * @see org.apache.maven.plugin.Mojo#execute()
+     * {@inheritDoc}
      */
     public void execute()
         throws MojoExecutionException, MojoFailureException
diff --git a/src/main/java/org/apache/maven/plugins/site/run/DoxiaBean.java b/src/main/java/org/apache/maven/plugins/site/run/DoxiaBean.java
index e9db47b..792452e 100644
--- a/src/main/java/org/apache/maven/plugins/site/run/DoxiaBean.java
+++ b/src/main/java/org/apache/maven/plugins/site/run/DoxiaBean.java
@@ -39,9 +39,9 @@
     private SiteRenderingContext generatedSiteContext;
 
     /**
-     * @param context
-     * @param documents
-     * @param generatedSiteDirectory
+     * @param context context
+     * @param documents documents
+     * @param generatedSiteContext context of generated content
      */
     public DoxiaBean( SiteRenderingContext context, Map<String, DocumentRenderer> documents,
                       SiteRenderingContext generatedSiteContext )