You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by mi...@apache.org on 2018/12/27 22:32:25 UTC
[maven-javadoc-plugin] branch additionalOptions-doc-improvement
created (now ee98956)
This is an automated email from the ASF dual-hosted git repository.
michaelo pushed a change to branch additionalOptions-doc-improvement
in repository https://gitbox.apache.org/repos/asf/maven-javadoc-plugin.git.
at ee98956 Clarify handling of additionalOptions
This branch includes the following new commits:
new ee98956 Clarify handling of additionalOptions
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[maven-javadoc-plugin] 01/01: Clarify handling of additionalOptions
Posted by mi...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
michaelo pushed a commit to branch additionalOptions-doc-improvement
in repository https://gitbox.apache.org/repos/asf/maven-javadoc-plugin.git
commit ee98956c3e45b253fb5282d56dcaa0ae13857d96
Author: Michael Osipov <mi...@apache.org>
AuthorDate: Thu Dec 27 23:31:53 2018 +0100
Clarify handling of additionalOptions
---
.../maven/plugins/javadoc/AbstractJavadocMojo.java | 128 ++++++++++-----------
1 file changed, 64 insertions(+), 64 deletions(-)
diff --git a/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java b/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java
index e7c8bbc..ef427cb 100644
--- a/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java
+++ b/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java
@@ -249,7 +249,7 @@ public abstract class AbstractJavadocMojo
* Default location for css
*/
private static final String RESOURCE_CSS_DIR = RESOURCE_DIR + "/css";
-
+
private static final String PACKAGE_LIST = "package-list";
private static final String ELEMENT_LIST = "element-list";
@@ -302,7 +302,7 @@ public abstract class AbstractJavadocMojo
private static final JavaVersion SINCE_JAVADOC_1_8 = JavaVersion.parse( "1.8" );
/**
- *
+ *
*/
private static final JavaVersion JAVA_VERSION = JavaVersion.JAVA_SPECIFICATION_VERSION;
@@ -390,9 +390,9 @@ public abstract class AbstractJavadocMojo
private File javadocDirectory;
/**
- * Set an additional option(s) on the command line. This value should include quotes as necessary for
- * parameters that include spaces. Useful for a custom doclet.
- *
+ * Set an additional option(s) on the command line. All input will be passed as-is to the
+ * {@code @options} file. You must take care of quoting and escaping. Useful for a custom doclet.
+ *
* @since 3.0.0
*/
@Parameter
@@ -1357,7 +1357,7 @@ public abstract class AbstractJavadocMojo
/**
* Generates compile-time warnings for missing serial tags.
* <br/>
- * @see <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#serialwarn">serialwarn</a> option
+ * @see <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#serialwarn">serialwarn</a> option
*/
@Parameter( property = "serialwarn", defaultValue = "false" )
private boolean serialwarn;
@@ -1738,14 +1738,14 @@ public abstract class AbstractJavadocMojo
*/
@Parameter( defaultValue = "true", property = "maven.javadoc.applyJavadocSecurityFix" )
private boolean applyJavadocSecurityFix = true;
-
+
/**
* <p>
* Specify the requirements for this jdk toolchain.
* This overrules the toolchain selected by the maven-toolchain-plugin.
* </p>
* <strong>note:</strong> requires at least Maven 3.3.1
- *
+ *
* @since 3.0.0
*/
@Parameter
@@ -1989,9 +1989,9 @@ public abstract class AbstractJavadocMojo
}
Map<String, Collection<String>> sourcePaths = getSourcePaths();
-
+
Collection<String> collectedSourcePaths = collect( sourcePaths.values() );
-
+
List<String> files = getFiles( collectedSourcePaths );
if ( !canGenerateReport( files ) )
{
@@ -2223,7 +2223,7 @@ public abstract class AbstractJavadocMojo
if ( StringUtils.isEmpty( subpackages ) )
{
Collection<String> excludedPackages = getExcludedPackages();
-
+
for ( String sourcePath : sourcePaths )
{
File sourceDirectory = new File( sourcePath );
@@ -2250,7 +2250,7 @@ public abstract class AbstractJavadocMojo
if ( StringUtils.isEmpty( sourcepath ) )
{
-
+
Set<String> sourcePaths =
new LinkedHashSet<>( JavadocUtil.pruneDirs( project, getProjectSourceRoots( project ) ) );
@@ -2276,7 +2276,7 @@ public abstract class AbstractJavadocMojo
}
mappedSourcePaths.put( ArtifactUtils.versionlessKey( project.getGroupId(), project.getArtifactId() ),
sourcePaths );
-
+
if ( includeDependencySources )
{
mappedSourcePaths.putAll( getDependencySourcePaths() );
@@ -2347,15 +2347,15 @@ public abstract class AbstractJavadocMojo
{
reactorProjectsMap.put( reactorProject.getBasedir().toPath(), reactorProject );
}
-
+
return modulesForAggregatedProject( project, reactorProjectsMap );
}
/**
* Recursively add the modules of the aggregatedProject to the set of aggregatedModules.
- *
+ *
* @param aggregatedProject the project being aggregated
- * @param reactorProjectsMap map of (still) available reactor projects
+ * @param reactorProjectsMap map of (still) available reactor projects
* @throws MavenReportException if any
*/
private Set<MavenProject> modulesForAggregatedProject( MavenProject aggregatedProject,
@@ -2378,7 +2378,7 @@ public abstract class AbstractJavadocMojo
}
Set<MavenProject> aggregatedModules = new LinkedHashSet<>();
-
+
for ( Path modulePath : modulePaths )
{
MavenProject module = reactorProjectsMap.remove( modulePath );
@@ -2387,7 +2387,7 @@ public abstract class AbstractJavadocMojo
aggregatedModules.addAll( modulesForAggregatedProject( module, reactorProjectsMap ) );
}
}
-
+
return aggregatedModules;
}
@@ -2531,7 +2531,7 @@ public abstract class AbstractJavadocMojo
throws MavenReportException
{
List<String> excludedNames = null;
-
+
Collection<Path> sourcePaths = new ArrayList<>( sourceFolders.size() );
for ( String folder : sourceFolders )
{
@@ -2541,7 +2541,7 @@ public abstract class AbstractJavadocMojo
if ( StringUtils.isNotEmpty( sourcepath ) && StringUtils.isNotEmpty( subpackages ) )
{
Collection<String> excludedPackages = getExcludedPackages();
-
+
excludedNames = JavadocUtil.getExcludedPackages( sourcePaths, excludedPackages );
}
@@ -2639,7 +2639,7 @@ public abstract class AbstractJavadocMojo
/**
* Method that gets the classpath and modulepath elements that will be specified in the javadoc
- * <code>-classpath</code> and <code>--module-path</code> parameter.
+ * <code>-classpath</code> and <code>--module-path</code> parameter.
* Since we have all the sources of the current reactor, it is sufficient to consider the
* dependencies of the reactor modules, excluding the module artifacts which may not yet be available
* when the reactor project is built for the first time.
@@ -2657,10 +2657,10 @@ public abstract class AbstractJavadocMojo
{
classpathElements.addAll( getProjectBuildOutputDirs( project ) );
}
-
+
populateCompileArtifactMap( compileArtifactMap, project.getArtifacts() );
-
+
if ( isAggregator() )
{
Collection<MavenProject> aggregatorProjects = getAggregatedProjects();
@@ -2670,8 +2670,8 @@ public abstract class AbstractJavadocMojo
{
reactorArtifacts.add( p.getGroupId() + ':' + p.getArtifactId() );
}
-
- TransformableFilter dependencyFilter = new AndFilter( Arrays.asList(
+
+ TransformableFilter dependencyFilter = new AndFilter( Arrays.asList(
new PatternExclusionsFilter( reactorArtifacts ),
getDependencyScopeFilter() ) );
@@ -2693,13 +2693,13 @@ public abstract class AbstractJavadocMojo
ProjectBuildingRequest buildingRequest = session.getProjectBuildingRequest();
buildingRequest =
buildingRequest.setRemoteRepositories( subProject.getRemoteArtifactRepositories() );
-
+
List<Dependency> managedDependencies = null;
if ( subProject.getDependencyManagement() != null )
{
managedDependencies = subProject.getDependencyManagement().getDependencies();
}
-
+
for ( ArtifactResult artifactResult
: dependencyResolver.resolveDependencies( buildingRequest,
subProject.getDependencies(),
@@ -2708,10 +2708,10 @@ public abstract class AbstractJavadocMojo
{
populateCompileArtifactMap( compileArtifactMap,
Collections.singletonList( artifactResult.getArtifact() ) );
-
+
sb.append( artifactResult.getArtifact().getFile() ).append( '\n' );
}
-
+
if ( getLog().isDebugEnabled() )
{
getLog().debug( sb.toString() );
@@ -2780,7 +2780,7 @@ public abstract class AbstractJavadocMojo
protected final Toolchain getToolchain()
{
Toolchain tc = null;
-
+
if ( jdkToolchain != null )
{
// Maven 3.3.1 has plugin execution scoped Toolchain Support
@@ -2805,12 +2805,12 @@ public abstract class AbstractJavadocMojo
// ignore
}
}
-
+
if ( tc == null )
{
tc = toolchainManager.getToolchainFromBuildContext( "jdk", session );
}
-
+
return tc;
}
@@ -3555,7 +3555,7 @@ public abstract class AbstractJavadocMojo
coordinate.setGroupId( javadocArtifact.getGroupId() );
coordinate.setArtifactId( javadocArtifact.getArtifactId() );
coordinate.setVersion( javadocArtifact.getVersion() );
-
+
Iterable<ArtifactResult> deps =
dependencyResolver.resolveDependencies( session.getProjectBuildingRequest(), coordinate,
ScopeFilter.including( "compile", "provided" ) );
@@ -3594,7 +3594,7 @@ public abstract class AbstractJavadocMojo
DefaultProjectBuildingRequest buildingRequest =
new DefaultProjectBuildingRequest( session.getProjectBuildingRequest() );
buildingRequest.setRemoteRepositories( project.getRemoteArtifactRepositories() );
-
+
return artifactResolver.resolveArtifact( buildingRequest, coordinate ).getArtifact();
}
@@ -4115,7 +4115,7 @@ public abstract class AbstractJavadocMojo
{
continue;
}
-
+
if ( isOffline && !link.startsWith( "file:" ) )
{
continue;
@@ -4379,7 +4379,7 @@ public abstract class AbstractJavadocMojo
ResolvePathsRequest<File> request =
ResolvePathsRequest.withFiles( Collections.<File>emptyList() ).
setMainModuleDescriptor( mainDescriptor );
-
+
try
{
Set<JavaModuleDescriptor.JavaExports> exports = locationManager.resolvePaths( request ).
@@ -4403,7 +4403,7 @@ public abstract class AbstractJavadocMojo
{
exportAllPackages = true;
}
-
+
for ( String currentFile : getFiles( artifactSourcePaths ) )
{
currentFile = currentFile.replace( '\\', '/' );
@@ -4795,7 +4795,7 @@ public abstract class AbstractJavadocMojo
throws MavenReportException
{
Collection<String> sourcePaths = collect( allSourcePaths.values() );
-
+
validateJavadocOptions();
// see com.sun.tools.javadoc.Start#parseAndExecute(String argv[])
@@ -4821,18 +4821,18 @@ public abstract class AbstractJavadocMojo
{
addArgIf( arguments, breakiterator, "-breakiterator", SINCE_JAVADOC_1_5 );
}
-
+
Collection<String> reactorKeys = new HashSet<>( session.getProjects().size() );
for ( MavenProject reactorProject : session.getProjects() )
{
reactorKeys.add( ArtifactUtils.versionlessKey( reactorProject.getGroupId(),
reactorProject.getArtifactId() ) );
}
-
+
final LocationManager locationManager = new LocationManager();
-
+
Collection<String> additionalModules = new ArrayList<>();
-
+
Path moduleSourceDir = null;
if ( allSourcePaths.size() > 1 )
{
@@ -4850,15 +4850,15 @@ public abstract class AbstractJavadocMojo
ResolvePathsRequest<File> request =
ResolvePathsRequest.withFiles( Collections.<File>emptyList() )
.setMainModuleDescriptor( moduleDescriptor );
-
+
String moduleName =
locationManager.resolvePaths( request ).getMainModuleDescriptor().name();
-
+
additionalModules.add( moduleName );
-
+
addArgIfNotEmpty( arguments, "--patch-module", moduleName + '='
+ JavadocUtil.quotedPathArgument( getSourcePath( projectSourcepaths.getValue() ) ) );
-
+
Path modulePath = moduleSourceDir.resolve( moduleName );
if ( !Files.isDirectory( modulePath ) )
{
@@ -4886,27 +4886,27 @@ public abstract class AbstractJavadocMojo
}
List<String> roots = getProjectSourceRoots( getProject() );
-
+
File mainDescriptor = findMainDescriptor( roots );
if ( javadocRuntimeVersion.isAtLeast( "9" ) && ( isAggregator() || mainDescriptor != null ) && !isTest() )
{
ResolvePathsRequest<File> request =
ResolvePathsRequest.withFiles( getPathElements() ).setAdditionalModules( additionalModules );
-
+
if ( mainDescriptor != null )
{
request.setMainModuleDescriptor( mainDescriptor );
}
-
+
try
{
ResolvePathsResult<File> result = locationManager.resolvePaths( request );
-
+
Set<File> modulePathElements = new HashSet<>( result.getModulepathElements().keySet() ) ;
if ( allSourcePaths.size() > 1 )
{
- // Probably required due to bug in javadoc (Java 9+)
+ // Probably required due to bug in javadoc (Java 9+)
modulePathElements.addAll( getProjectBuildOutputDirs( getProject() ) );
}
@@ -4922,10 +4922,10 @@ public abstract class AbstractJavadocMojo
classPathElements.add( file );
}
}
-
+
String classpath = StringUtils.join( classPathElements.iterator(), File.pathSeparator );
addArgIfNotEmpty( arguments, "--class-path", JavadocUtil.quotedPathArgument( classpath ) );
-
+
String modulepath =
StringUtils.join( modulePathElements.iterator(), File.pathSeparator );
addArgIfNotEmpty( arguments, "--module-path", JavadocUtil.quotedPathArgument( modulepath ) );
@@ -4940,7 +4940,7 @@ public abstract class AbstractJavadocMojo
String classpath = StringUtils.join( getPathElements().iterator(), File.pathSeparator );
addArgIfNotEmpty( arguments, "-classpath", JavadocUtil.quotedPathArgument( classpath ) );
}
-
+
if ( StringUtils.isNotEmpty( doclet ) )
{
addArgIfNotEmpty( arguments, "-doclet", JavadocUtil.quotedArgument( doclet ) );
@@ -4977,7 +4977,7 @@ public abstract class AbstractJavadocMojo
{
sourcepath = StringUtils.join( sourcePaths.iterator(), File.pathSeparator );
}
-
+
if ( moduleSourceDir != null )
{
addArgIfNotEmpty( arguments, "--module-source-path",
@@ -4994,7 +4994,7 @@ public abstract class AbstractJavadocMojo
{
addArgIfNotEmpty( arguments, "-subpackages", subpackages, SINCE_JAVADOC_1_5 );
}
-
+
// [MJAVADOC-497] must be after sourcepath is recalculated, since getExcludedPackages() depends on it
addArgIfNotEmpty( arguments, "-exclude", getExcludedPackages( sourcePaths ), SINCE_JAVADOC_1_4 );
@@ -5932,7 +5932,7 @@ public abstract class AbstractJavadocMojo
}
String apiVersion;
-
+
Matcher apiMatcher = Pattern.compile( "(1\\.\\d|\\d\\d*)" ).matcher( sourceVersion.toString() );
if ( apiMatcher.find() )
{
@@ -6033,7 +6033,7 @@ public abstract class AbstractJavadocMojo
{
final URI packageListUri;
final URI elementListUri;
-
+
if ( link.trim().toLowerCase( Locale.ENGLISH ).startsWith( "http:" ) || link.trim().toLowerCase(
Locale.ENGLISH ).startsWith( "https:" ) || link.trim().toLowerCase( Locale.ENGLISH ).startsWith(
"ftp:" ) || link.trim().toLowerCase( Locale.ENGLISH ).startsWith( "file:" ) )
@@ -6064,20 +6064,20 @@ public abstract class AbstractJavadocMojo
elementListUri = new File( dir, ELEMENT_LIST ).toURI();
}
-
+
IOException elementListIOException = null;
- try
+ try
{
if ( JavadocUtil.isValidElementList( elementListUri.toURL(), settings, validateLinks ) )
{
return true;
}
}
- catch ( IOException e )
+ catch ( IOException e )
{
elementListIOException = e;
}
-
+
if ( JavadocUtil.isValidPackageList( packageListUri.toURL(), settings, validateLinks ) )
{
return true;
@@ -6092,7 +6092,7 @@ public abstract class AbstractJavadocMojo
}
else
{
- getLog().error( "Invalid links: "
+ getLog().error( "Invalid links: "
+ link + " with /" + PACKAGE_LIST + " or / " + ELEMENT_LIST + ". Ignored it." );
}
}
@@ -6329,7 +6329,7 @@ public abstract class AbstractJavadocMojo
}
File optionsFile = getJavadocOptionsFile();
-
+
try ( Writer writer = WriterFactory.newXmlWriter( optionsFile ) )
{
new JavadocOptionsXpp3Writer().write( writer, options );