Skip to content

Commit

Permalink
Fixed documentation to pass a Java 8 lint check.
Browse files Browse the repository at this point in the history 
git-svn-id: file:///home/tiste/MOJOHAUS-TO-GIT/SVN-MOJO-WIP/trunk/mojo/jaxb2-maven-plugin@20400 52ab4f32-60fc-0310-b215-8acea882cd1b
  • Loading branch information
@lennartj
lennartj committed Feb 8, 2015
1 parent 2bcd206 commit 0d3643b
Show file tree
Hide file tree
Showing 18 changed files with 144 additions and 119 deletions.
8 changes: 6 additions & 2 deletions src/main/java/org/codehaus/mojo/jaxb2/AbstractJaxbMojo.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -222,6 +222,10 @@ public final void execute() throws MojoExecutionException, MojoFailureException
* This method will only be called if {@code !shouldExecutionBeSkipped() && isReGenerationRequired()}.</p>
*
* @return {@code true} if the timestamp of the stale file should be updated.
* @throws MojoExecutionException if an unexpected problem occurs.
* Throwing this exception causes a "BUILD ERROR" message to be displayed.
* @throws MojoFailureException if an expected problem (such as a compilation failure) occurs.
* Throwing this exception causes a "BUILD FAILURE" message to be displayed.
*/
protected abstract boolean performExecution() throws MojoExecutionException, MojoFailureException;

Expand Down Expand Up @@ -322,13 +326,12 @@ protected final File getStaleFile() {

/**
* <p>The algorithm for finding the encoding to use is as follows (where the first non-null value found
* is used for encoding):
* is used for encoding):</p>
* <ol>
* <li>If the configuration property is explicitly given within the plugin's configuration, use that value.</li>
* <li>If the Maven property <code>project.build.sourceEncoding</code> is defined, use its value.</li>
* <li>Otherwise use the value from the system property <code>file.encoding</code>.</li>
* </ol>
* </p>
*
* @param warnIfConfiguredEncodingDiffersFromFileEncoding Defines if the configured encoding is not equal to the
* system property {@code file.encoding}, emit a warning
Expand Down Expand Up @@ -368,6 +371,7 @@ && getLog().isWarnEnabled()) {
* @param customEpisodeFileName {@code null} to indicate that the standard episode file name ("sun-jaxb.episode")
* should be used, and otherwise a non-empty name which should be used
* as the episode file name.
* @return A non-null File where the JAXB episode file should be written.
* @throws MojoExecutionException if the parent directory of the episode file could not be created.
*/
protected File getEpisodeFile(final String customEpisodeFileName) throws MojoExecutionException {
Expand Down
18 changes: 9 additions & 9 deletions src/main/java/org/codehaus/mojo/jaxb2/javageneration/AbstractJavaGeneratorMojo.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -196,13 +196,13 @@ public abstract class AbstractJavaGeneratorMojo extends AbstractJaxbMojo {
* to be copied verbatim to the XJC argument list with spaces in between:</p>
* <pre>
* <code>
* &lt;configuration>
* &lt;configuration&gt;
* ...
* &lt;arguments>
* &lt;argument>-Xfluent-api&lt;/argument>
* &lt;argument>somefile&lt;/argument>
* &lt;/arguments>
* &lt;/configuration>
* &lt;arguments&gt;
* &lt;argument&gt;-Xfluent-api&lt;/argument&gt;
* &lt;argument&gt;somefile&lt;/argument&gt;
* &lt;/arguments&gt;
* &lt;/configuration&gt;
* </code>
* </pre>
* <p>The arguments configured above yields the following extra arguments to the XJC command:
Expand Down Expand Up @@ -255,10 +255,10 @@ public abstract class AbstractJavaGeneratorMojo extends AbstractJaxbMojo {
* will be created.</p>
* <pre>
* <code>
* &lt;configuration>
* &lt;configuration&gt;
* ...
* &lt;xsdPathWithinArtifact>META-INF/jaxb/xsd&lt;/xsdPathWithinArtifact>
* &lt;/configuration>
* &lt;xsdPathWithinArtifact&gt;META-INF/jaxb/xsd&lt;/xsdPathWithinArtifact&gt;
* &lt;/configuration&gt;
* </code>
* </pre>
* <p><strong>Note</strong>: This parameter was previously called {@code includeSchemasOutputPath}
Expand Down
5 changes: 2 additions & 3 deletions src/main/java/org/codehaus/mojo/jaxb2/package-info.java
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,18 @@
/**
* <p>The jaxb2-maven-plugin wraps and adapts the <a href="https://jaxb.java.net/">JAXB reference implementation</a>
* to be useful within the Maven build process.</p>
* <p>The plugin's code is divided into 3 main blocks, each placed within a separate package structure:
* <p>The plugin's code is divided into 3 main blocks, each placed within a separate package structure:</p>
*
* <ol>
* <li><strong>javageneration</strong>. Contains code involved in creating java code from XSD or DTDs.
* This package structure adapts the plugin to using the XJC ("Xml-to-Java-Compiler">) from the
* This package structure adapts the plugin to using the XJC ("Xml-to-Java-Compiler") from the
* JAXB reference implementation.</li>
* <li><strong>schemageneration</strong>. Contains code involved in creating XSDs from annotated Java classes.
* This package structure adapts the plugin to using the schemagen tool from the JDK. (Typically found in the
* bin directory of the java installation).</li>
* <li><strong>shared</strong>. Contains shared utility classes used by both the java- and xsd-generation
* structure classes.</li>
* </ol>
* </p>
*
* @author <a href="mailto:lj@jguru.se">Lennart J&ouml;relid</a>
* @see <a href="https://jaxb.java.net/">The JAXB Reference Implementation</a>
Expand Down
10 changes: 3 additions & 7 deletions src/main/java/org/codehaus/mojo/jaxb2/schemageneration/AbstractXsdGeneratorMojo.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,9 +44,6 @@

import java.io.File;
import java.io.IOException;
import java.io.OutputStreamWriter;
import java.io.PrintStream;
import java.io.StringWriter;
import java.lang.reflect.InvocationTargetException;
import java.net.HttpURLConnection;
import java.net.URL;
Expand Down Expand Up @@ -195,8 +192,7 @@ public abstract class AbstractXsdGeneratorMojo extends AbstractJaxbMojo {
protected boolean clearOutputDir;

/**
* XSD schema files are not generated from POM projects or if no includes have been supplied.
* <p/>
* <p>XSD schema files are not generated from POM projects or if no includes have been supplied.</p>
* {@inheritDoc}
*/
@Override
Expand Down Expand Up @@ -341,7 +337,7 @@ protected boolean performExecution() throws MojoExecutionException, MojoFailureE
// Redirect the JUL Logging statements to the Maven Log.
final Logger rootLogger = Logger.getLogger("");
rootLogger.setLevel(Level.FINER);
for(Handler current : rootLogger.getHandlers()) {
for (Handler current : rootLogger.getHandlers()) {
rootLogger.removeHandler(current);
}
rootLogger.addHandler(new MavenLogHandler(getLog(), "SchemaGen", getEncoding(false)));
Expand All @@ -361,7 +357,7 @@ protected boolean performExecution() throws MojoExecutionException, MojoFailureE
errorMsgBuilder.append("|\n");

final StringBuilder builder = new StringBuilder("schemagen ");
for(String current : schemaGenArguments) {
for (String current : schemaGenArguments) {
builder.append(current).append(" ");
}

Expand Down
10 changes: 5 additions & 5 deletions ...java/org/codehaus/mojo/jaxb2/schemageneration/postprocessing/javadoc/JavaDocRenderer.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,11 +41,11 @@
* annotation into the resulting schema, yielding the following result:</p>
* <pre>
* <code>
* &lt;xs:element name="lastName" type="xs:string">
* &lt;xs:annotation>
* &lt;xs:documentation>&lt;![CDATA[The last name of the SomewhatNamedPerson.]]>&lt;/xs:documentation>
* &lt;/xs:annotation>
* &lt;/xs:element>
* &lt;xs:element name="lastName" type="xs:string"&gt;
* &lt;xs:annotation&gt;
* &lt;xs:documentation&gt;&lt;![CDATA[The last name of the SomewhatNamedPerson.]]&gt;&lt;/xs:documentation&gt;
* &lt;/xs:annotation&gt;
* &lt;/xs:element&gt;
* </code>
* </pre>
* <p>The JavaDocRenderer will create the content of the CDATA element within the XSD documentation annotation,
Expand Down
65 changes: 32 additions & 33 deletions ...g/codehaus/mojo/jaxb2/schemageneration/postprocessing/javadoc/XsdAnnotationProcessor.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,47 +51,46 @@
* not contain a JavaDoc annotation) from the corresponding member is injected as an
* annotation directly inside the element.</li>
* </ol>
* <p/>
* <p>Thus, the following 'vanilla'-generated XSD:</p>
* <pre>
* <code>
* &lt;xs:complexType name="somewhatNamedPerson">
* &lt;xs:sequence>
* &lt;xs:element name="firstName" type="xs:string" nillable="true" minOccurs="0"/>
* &lt;xs:element name="lastName" type="xs:string"/>
* &lt;/xs:sequence>
* &lt;xs:attribute name="age" type="xs:int" use="required"/>
* &lt;/xs:complexType>
* &lt;xs:complexType name="somewhatNamedPerson"&gt;
* &lt;xs:sequence&gt;
* &lt;xs:element name="firstName" type="xs:string" nillable="true" minOccurs="0"/&gt;
* &lt;xs:element name="lastName" type="xs:string"/&gt;
* &lt;/xs:sequence&gt;
* &lt;xs:attribute name="age" type="xs:int" use="required"/&gt;
* &lt;/xs:complexType&gt;
* </code>
* </pre>
* <p>... would be converted to the following annotated XSD, given a DefaultJavaDocRenderer:</p>
* <pre>
* <code>
* &lt;xs:complexType name="somewhatNamedPerson">
* &lt;xs:annotation>
* &lt;xs:documentation>&lt;![CDATA[Definition of a person with lastName and age, and optionally a firstName as well...
* &lt;xs:complexType name="somewhatNamedPerson"&gt;
* &lt;xs:annotation&gt;
* &lt;xs:documentation&gt;&lt;![CDATA[Definition of a person with lastName and age, and optionally a firstName as well...
*
* (author): &lt;a href="mailto:lj@jguru.se">Lennart J&ouml;relid&lt;/a>, jGuru Europe AB
* (custom): A custom JavaDoc annotation.]]>&lt;/xs:documentation>
* &lt;/xs:annotation>
* &lt;xs:sequence>
* &lt;xs:element minOccurs="0" name="firstName" nillable="true" type="xs:string">
* &lt;xs:annotation>
* &lt;xs:documentation>&lt;![CDATA[The first name of the SomewhatNamedPerson.]]>&lt;/xs:documentation>
* &lt;/xs:annotation>
* &lt;/xs:element>
* &lt;xs:element name="lastName" type="xs:string">
* &lt;xs:annotation>
* &lt;xs:documentation>&lt;![CDATA[The last name of the SomewhatNamedPerson.]]>&lt;/xs:documentation>
* &lt;/xs:annotation>
* &lt;/xs:element>
* &lt;/xs:sequence>
* &lt;xs:attribute name="age" type="xs:int" use="required">
* &lt;xs:annotation>
* &lt;xs:documentation>&lt;![CDATA[The age of the SomewhatNamedPerson. Must be positive.]]>&lt;/xs:documentation>
* &lt;/xs:annotation>
* &lt;/xs:attribute>
* &lt;/xs:complexType>
* (author): &lt;a href="mailto:lj@jguru.se"&gt;Lennart J&ouml;relid&lt;/a&gt;, jGuru Europe AB
* (custom): A custom JavaDoc annotation.]]&gt;&lt;/xs:documentation&gt;
* &lt;/xs:annotation&gt;
* &lt;xs:sequence&gt;
* &lt;xs:element minOccurs="0" name="firstName" nillable="true" type="xs:string"&gt;
* &lt;xs:annotation&gt;
* &lt;xs:documentation&gt;&lt;![CDATA[The first name of the SomewhatNamedPerson.]]&gt;&lt;/xs:documentation&gt;
* &lt;/xs:annotation&gt;
* &lt;/xs:element&gt;
* &lt;xs:element name="lastName" type="xs:string"&gt;
* &lt;xs:annotation&gt;
* &lt;xs:documentation&gt;&lt;![CDATA[The last name of the SomewhatNamedPerson.]]&gt;&lt;/xs:documentation&gt;
* &lt;/xs:annotation&gt;
* &lt;/xs:element&gt;
* &lt;/xs:sequence&gt;
* &lt;xs:attribute name="age" type="xs:int" use="required"&gt;
* &lt;xs:annotation&gt;
* &lt;xs:documentation&gt;&lt;![CDATA[The age of the SomewhatNamedPerson. Must be positive.]]&gt;&lt;/xs:documentation&gt;
* &lt;/xs:annotation&gt;
* &lt;/xs:attribute&gt;
* &lt;/xs:complexType&gt;
* </code>
* </pre>
* <p>... given that the Java class <code>SomewhatNamedPerson</code> has JavaDoc on its class and fields
Expand All @@ -107,7 +106,7 @@ public class XsdAnnotationProcessor implements NodeProcessor {
* The namespace schema prefix for the URI {@code http://www.w3.org/2001/XMLSchema}
* (i.e. {@code XMLConstants.W3C_XML_SCHEMA_NS_URI}).
*
* @see XMLConstants.W3C_XML_SCHEMA_NS_URI
* @see javax.xml.XMLConstants#W3C_XML_SCHEMA_NS_URI
*/
public static final String XSD_SCHEMA_NAMESPACE_PREFIX = "xs";

Expand Down
9 changes: 4 additions & 5 deletions ...mojo/jaxb2/schemageneration/postprocessing/schemaenhancement/ChangeFilenameProcessor.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,8 @@
import java.util.Map;

/**
* NodeProcessor which alters the filename for generated XML schema files.
* The ChangeNamespacePrefixProcessor alters the following:
* <p/>
* <p>NodeProcessor which alters the filename for generated XML schema files.
* The ChangeNamespacePrefixProcessor alters the following:</p>
* <dl>
* <dt>Schema Import Definitions</dt>
* <dd>&lt;xs:import namespace="http://some/namespace" schemaLocation="<strong>schema2.xsd</strong>"/&gt; is
Expand All @@ -52,8 +51,8 @@ public class ChangeFilenameProcessor implements NodeProcessor {
private Map<String, String> namespaceUriToNewFilenameMap;

/**
* Creates a new ChangeFilenameProcessor using the provided map relating namespace URIs to
* desired new filenames.
* <p>Creates a new ChangeFilenameProcessor using the provided map relating namespace URIs
* to desired new file names.</p>
*
* @param namespaceUriToNewFilenameMap A map relating namespace URIs [key] to
* new/desired schema filenames [value].
Expand Down
9 changes: 2 additions & 7 deletions ...xb2/schemageneration/postprocessing/schemaenhancement/ChangeNamespacePrefixProcessor.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,24 +27,19 @@
import javax.xml.XMLConstants;

/**
* <code>NodeProcessor</code> which alters the namespace prefix for all relevant Nodes within an XML document Node. It
* alters namespace prefixes in the following logical places:
* <p/>
* <p><code>NodeProcessor</code> which alters the namespace prefix for all relevant Nodes within an XML
* document Node. It alters namespace prefixes in the following logical places:</p>
* <dl>
* <dt>Schema Namespace Definition</dt>
* <dd>xmlns:oldPrefix="http://some/namespace" is altered to xmlns:newPrefix="http://some/namespace"</dd>
* <p/>
* <dt>Elements Namespace Prefix</dt>
* <dd>&lt;oldPrefix:someElement ... &gt; is altered to &lt;newPrefix:someElement ... &gt;</dd>
* <p/>
* <dt>Element Reference</dt>
* <dd><code>&lt;xs:element ref="oldPrefix:aRequiredElementInTheOldPrefixNamespace"/&gt;</code> is altered to
* <code>&lt;xs:element ref="newPrefix:aRequiredElementInTheOldPrefixNamespace"/&gt;</code></dd>
* <p/>
* <dt>Type Attribute</dt>
* <dd><code>&lt;xs:element type="oldPrefix:something"/&gt;</code> is altered to
* <code>&lt;xs:element type="newPrefix:something"/&gt;</code></dd>
* <p/>
* <dt>Type Extension</dt>
* <dd><code>&lt;xs:extension base="oldPrefix:something"/&gt;</code> is altered to
* <code>&lt;xs:extension base="newPrefix:something"/&gt;</code></dd>
Expand Down
9 changes: 2 additions & 7 deletions ...odehaus/mojo/jaxb2/schemageneration/postprocessing/schemaenhancement/TransformSchema.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,13 +28,13 @@
* the Jaxb2-Maven-plugin must supply a post-processing step to work around this situation.</p>
* <p>Each <code>TransformSchema</code> object holds data pertaining to changes for one namespace
* URI - either namespace prefix used within the generated XSD or resulting filename for
* the schema definition.
* the schema definition.</p>
* <ol>
* <li><strong>Namespace prefix</strong>. Each XML element within a namespace uses the supplied
* prefix. (As a reference, in the XML element <code>&lt;foo:bar/&gt;</code>, the namespace prefix
* is "foo" and the element name is "bar"). The Schemagen tool by default only generates namespace
* prefixes on the form "ns1", "ns2" etc., which means that the generated schema will contain elements
* on the form <code>&lt;xs:extension base="ns1:nazgulEntity"></code>.
* on the form <code>&lt;xs:extension base="ns1:nazgulEntity"&gt;</code>.
* Use a <code>toPrefix</code> element to change the namespace prefix of a particular XML URI to
* simplify understanding the schema.</li>
* <li><strong>Filename</strong>. By default, the Schemagen tool creates files called "schema1.xsd",
Expand All @@ -45,12 +45,10 @@
* particular XML URI. Changing the file names frequently improves overview and usability of the generated schema
* files.</li>
* </ol>
* </p>
* <h2>Example TransformSchemas</h2>
* <p>The URI element is mandatory for each TransformSchema element. The first example illustrates how
* to use the TransformSchema element to change the prefix and file name of 3 XML URIs. This is the recommended
* use of a TransformSchema - change both prefix and filename to something meaningful for each URI:</p>
* <p>
* <pre>
* &lt;transformSchemas&gt;
* &lt;transformSchema&gt;
Expand All @@ -70,13 +68,11 @@
* &lt;/transformSchema&gt;
* &lt;/transformSchemas&gt;
* </pre>
* </p>
* <p>The URI element is mandatory for each TransformSchema element, along with at least one of the other two
* elements in the TransformSchema. This implies that partial configuration for TransformSchema can be used,
* although <em>this is not recommended</em> since the readability and usability of the automatically generated
* namespace prefixes and file names are poor. The second example illustrates how to use the TransformSchema element
* to change either prefix or file name for 2 XML URIs:</p>
* <p>
* <pre>
* &lt;transformSchemas&gt;
* &lt;transformSchema&gt;
Expand All @@ -89,7 +85,6 @@
* &lt;/transformSchema&gt;
* &lt;/transformSchemas&gt;
* </pre>
* </p>
*
* @author <a href="mailto:lj@jguru.se">Lennart J&ouml;relid</a>
* @since 1.4
Expand Down
4 changes: 3 additions & 1 deletion src/main/java/org/codehaus/mojo/jaxb2/shared/FileSystemUtilities.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -158,7 +158,8 @@ public static URL getUrlFor(final File aFile) throws IllegalArgumentException {
/**
* Acquires the file for a supplied URL, provided that its protocol is is either a file or a jar.
*
* @param anURL a non-null URL.
* @param anURL a non-null URL.
* @param encoding The encoding to be used by the URLDecoder to decode the path found.
* @return The File pointing to the supplied URL, for file or jar protocol URLs and null otherwise.
*/
public static File getFileFor(final URL anURL, final String encoding) {
Expand Down Expand Up @@ -384,6 +385,7 @@ public static List<File> filterFiles(final File baseDir,
* exclusionFilters supplied.
* @param exclusionFilters A List of Filters which identify files to remove from the result - implying that any
* File matched by any of these exclusionFilters will not be included in the result.
* @param log The active Maven Log.
* @return All files in (or files in subdirectories of directories provided in) the files List, provided that each
* file is accepted by an ExclusionRegExpFileFilter.
*/
Expand Down
Loading

0 comments on commit 0d3643b

Please sign in to comment.