You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by sl...@apache.org on 2020/07/04 14:18:56 UTC
[maven-doxia-sitetools] branch master updated: [DOXIASITETOOLS-219]
Fix javadoc issues with JDK 8 when generating documentation
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-doxia-sitetools.git
The following commit(s) were added to refs/heads/master by this push:
new 1b301e6 [DOXIASITETOOLS-219] Fix javadoc issues with JDK 8 when generating documentation
1b301e6 is described below
commit 1b301e6d8b9d8b446270d90c77d8778af2d42e56
Author: Abel Salgado Romero <ab...@gmail.com>
AuthorDate: Sat Jul 4 15:32:25 2020 +0200
[DOXIASITETOOLS-219] Fix javadoc issues with JDK 8 when generating documentation
---
doxia-decoration-model/src/main/mdo/decoration.mdo | 2 +-
doxia-doc-renderer/pom.xml | 12 +++++++
.../maven/doxia/docrenderer/DocumentRenderer.java | 1 -
.../docrenderer/itext/AbstractITextRender.java | 6 ++--
.../apache/maven/doxia/tools/ReportComparator.java | 4 +--
.../org/apache/maven/doxia/tools/SiteTool.java | 2 +-
.../doxia/siterenderer/DefaultSiteRenderer.java | 6 ++--
.../apache/maven/doxia/siterenderer/Renderer.java | 41 +++++++++++-----------
.../doxia/siterenderer/SiteRenderingContext.java | 2 +-
9 files changed, 44 insertions(+), 32 deletions(-)
diff --git a/doxia-decoration-model/src/main/mdo/decoration.mdo b/doxia-decoration-model/src/main/mdo/decoration.mdo
index 5053933..bfed6b8 100644
--- a/doxia-decoration-model/src/main/mdo/decoration.mdo
+++ b/doxia-decoration-model/src/main/mdo/decoration.mdo
@@ -610,7 +610,7 @@ under the License.
<field xml.attribute="true">
<name>inheritAsRef</name>
<description><![CDATA[
- If this is a reference, setting <inheritAsRef>true</inheritAsRef> means that it will be populated
+ If this is a reference, setting {@literal <inheritAsRef>true</inheritAsRef>} means that it will be populated
in the project, whereas if it is false, it is populated in the parent and then inherited.
]]></description>
<version>1.0.0+</version>
diff --git a/doxia-doc-renderer/pom.xml b/doxia-doc-renderer/pom.xml
index ae55387..d3768fa 100644
--- a/doxia-doc-renderer/pom.xml
+++ b/doxia-doc-renderer/pom.xml
@@ -134,6 +134,18 @@ under the License.
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <configuration>
+ <tags>
+ <tag>
+ <name>plexus.requirement</name>
+ <placement>f</placement>
+ </tag>
+ </tags>
+ </configuration>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<!-- To be sure that JVM will implement AWT in software -->
diff --git a/doxia-doc-renderer/src/main/java/org/apache/maven/doxia/docrenderer/DocumentRenderer.java b/doxia-doc-renderer/src/main/java/org/apache/maven/doxia/docrenderer/DocumentRenderer.java
index 6f151c5..2022309 100644
--- a/doxia-doc-renderer/src/main/java/org/apache/maven/doxia/docrenderer/DocumentRenderer.java
+++ b/doxia-doc-renderer/src/main/java/org/apache/maven/doxia/docrenderer/DocumentRenderer.java
@@ -65,7 +65,6 @@ public interface DocumentRenderer
* If the model is null, render all files from baseDirectory individually.
* @throws org.apache.maven.doxia.docrenderer.DocumentRendererException if any
* @throws java.io.IOException if any
-// * @deprecated since 1.1.2, use {@link #render(File, File, DocumentModel, DocumentRendererContext)}
*/
void render( File baseDirectory, File outputDirectory, DocumentModel documentModel )
throws DocumentRendererException, IOException;
diff --git a/doxia-doc-renderer/src/main/java/org/apache/maven/doxia/docrenderer/itext/AbstractITextRender.java b/doxia-doc-renderer/src/main/java/org/apache/maven/doxia/docrenderer/itext/AbstractITextRender.java
index e672b80..c18545e 100644
--- a/doxia-doc-renderer/src/main/java/org/apache/maven/doxia/docrenderer/itext/AbstractITextRender.java
+++ b/doxia-doc-renderer/src/main/java/org/apache/maven/doxia/docrenderer/itext/AbstractITextRender.java
@@ -291,10 +291,10 @@ public abstract class AbstractITextRender
}
/**
- * Generate an ouput file with the iText framework
+ * Generate an output file from the contents of an input with the iText framework
*
- * @param iTextFile
- * @param iTextOutput
+ * @param iTextFile input file
+ * @param iTextOutput output file
* @throws org.apache.maven.doxia.docrenderer.DocumentRendererException if any
* @throws java.io.IOException if any
*/
diff --git a/doxia-integration-tools/src/main/java/org/apache/maven/doxia/tools/ReportComparator.java b/doxia-integration-tools/src/main/java/org/apache/maven/doxia/tools/ReportComparator.java
index 2a3b245..eef9a21 100644
--- a/doxia-integration-tools/src/main/java/org/apache/maven/doxia/tools/ReportComparator.java
+++ b/doxia-integration-tools/src/main/java/org/apache/maven/doxia/tools/ReportComparator.java
@@ -29,8 +29,8 @@ import org.apache.maven.reporting.MavenReport;
* Sorts reports.
*
* @author <a href="mailto:brett@apache.org">Brett Porter</a>
- * @todo move to reporting API?
- * @todo allow reports to define their order in some other way?
+ * TODO move to reporting API?
+ * TODO allow reports to define their order in some other way?
*/
public class ReportComparator
implements Comparator<MavenReport>
diff --git a/doxia-integration-tools/src/main/java/org/apache/maven/doxia/tools/SiteTool.java b/doxia-integration-tools/src/main/java/org/apache/maven/doxia/tools/SiteTool.java
index e7ead65..3366105 100644
--- a/doxia-integration-tools/src/main/java/org/apache/maven/doxia/tools/SiteTool.java
+++ b/doxia-integration-tools/src/main/java/org/apache/maven/doxia/tools/SiteTool.java
@@ -89,7 +89,7 @@ public interface SiteTool
/**
* Interpolating several expressions in the site descriptor content. Actually, the expressions can be in
* the project, the environment variables and the specific properties like <code>encoding</code>.
- * <p/>
+ * <p>
* For instance:
* <dl>
* <dt>${project.name}</dt>
diff --git a/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java b/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java
index 6950b60..84ac037 100644
--- a/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java
+++ b/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java
@@ -536,9 +536,9 @@ public class DefaultSiteRenderer
/**
* Create a Velocity Context for a Doxia document, containing every information about rendered document.
*
- * @param sink the site renderer sink for the document
+ * @param renderingContext the document's RenderingContext
* @param siteRenderingContext the site rendering context
- * @return
+ * @return a Velocity tools managed context
*/
protected Context createDocumentVelocityContext( RenderingContext renderingContext,
SiteRenderingContext siteRenderingContext )
@@ -622,7 +622,7 @@ public class DefaultSiteRenderer
*
* @param content the document content to be merged into the template
* @param siteRenderingContext the site rendering context
- * @return
+ * @return a Velocity tools managed context
*/
protected Context createSiteTemplateVelocityContext( DocumentContent content,
SiteRenderingContext siteRenderingContext )
diff --git a/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/Renderer.java b/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/Renderer.java
index 148cef9..3e7bc89 100644
--- a/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/Renderer.java
+++ b/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/Renderer.java
@@ -77,7 +77,7 @@ public interface Renderer // TODO rename to SiteRenderer
* i.e. merge the document content into the site template.
*
* @param writer the Writer to use.
- * @param content the document content to be merged
+ * @param content the document content to be merged.
* @param siteRenderingContext the SiteRenderingContext to use.
* @throws RendererException if it bombs.
* @since 1.8
@@ -88,12 +88,13 @@ public interface Renderer // TODO rename to SiteRenderer
/**
* Create a Site Rendering Context for a site using a skin.
*
- * @param skin
- * @param attributes
- * @param decoration
- * @param defaultWindowTitle
- * @param locale
+ * @param skin a skin
+ * @param attributes attributes to use
+ * @param decoration a decoration model
+ * @param defaultWindowTitle default window title
+ * @param locale locale to use
* @return a SiteRenderingContext.
+ * @throws RendererException if it bombs.
* @throws java.io.IOException if it bombs.
* @since 1.7.3 was previously with skin as File instead of Artifact
*/
@@ -104,16 +105,16 @@ public interface Renderer // TODO rename to SiteRenderer
/**
* Create a Site Rendering Context for a site using a local template.
*
- * @param templateFile
- * @param attributes
- * @param decoration
- * @param defaultWindowTitle
- * @param locale
+ * @param templateFile template file
+ * @param attributes attributes to use
+ * @param decoration a decoration model
+ * @param defaultWindowTitle default window title
+ * @param locale locale to use
* @return a SiteRenderingContext.
* @throws MalformedURLException if it bombs.
* @since 1.7, had an additional skinFile parameter before
* @deprecated Deprecated without replacement, use skins only.
- * @see #createContextForSkin(File, Map, DecorationModel, String, Locale)
+ * @see #createContextForSkin(Artifact, Map, DecorationModel, String, Locale)
*/
@Deprecated
SiteRenderingContext createContextForTemplate( File templateFile, Map<String, ?> attributes,
@@ -124,9 +125,9 @@ public interface Renderer // TODO rename to SiteRenderer
/**
* Copy resource files.
*
- * @param siteRenderingContext
- * @param resourcesDirectory
- * @param outputDirectory
+ * @param siteRenderingContext the SiteRenderingContext to use
+ * @param resourcesDirectory resources directory as file
+ * @param outputDirectory output directory as file
* @throws IOException if it bombs.
* @deprecated since 1.7, use copyResources without resourcesDirectory parameter
*/
@@ -136,8 +137,8 @@ public interface Renderer // TODO rename to SiteRenderer
/**
* Copy resource files from skin, template, and site resources.
*
- * @param siteRenderingContext
- * @param outputDirectory
+ * @param siteRenderingContext the SiteRenderingContext to use.
+ * @param outputDirectory output directory as file
* @throws IOException if it bombs.
* @since 1.7
*/
@@ -147,7 +148,7 @@ public interface Renderer // TODO rename to SiteRenderer
/**
* Locate Doxia document source files in the site source context.
*
- * @param siteRenderingContext
+ * @param siteRenderingContext the SiteRenderingContext to use
* @return the Doxia document renderers in a Map keyed by output file name.
* @throws IOException if it bombs.
* @throws RendererException if it bombs.
@@ -159,8 +160,8 @@ public interface Renderer // TODO rename to SiteRenderer
/**
* Locate Doxia document source files in the site source context.
*
- * @param siteRenderingContext
- * @param mark Doxia document renderer as editable? (should not mark editable if generated Doxia source)
+ * @param siteRenderingContext the SiteRenderingContext to use
+ * @param editable Doxia document renderer as editable? (should not set editable if generated Doxia source)
* @return the Doxia document renderers in a Map keyed by output file name.
* @throws IOException if it bombs.
* @throws RendererException if it bombs.
diff --git a/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/SiteRenderingContext.java b/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/SiteRenderingContext.java
index 994e2a1..8a6079d 100644
--- a/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/SiteRenderingContext.java
+++ b/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/SiteRenderingContext.java
@@ -463,7 +463,7 @@ public class SiteRenderingContext
/**
* Set the root directory.
*
- * @param rootDirectory
+ * @param rootDirectory the root directory
* @since 1.8
*/
public void setRootDirectory( File rootDirectory )