maven-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Peter lynch (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (MJAVADOC-431) allow javadoc jar to contain Maven descriptor
Date Mon, 05 Oct 2015 17:14:27 GMT

    [ https://issues.apache.org/jira/browse/MJAVADOC-431?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14943681#comment-14943681
] 

Peter lynch commented on MJAVADOC-431:
--------------------------------------

[~michael-o] The javadoc plugin accepts a generic archiver configuration for the javadoc-jar
goal, yet silently prevents users from adding the descriptor as part of that configuration.
This is an abuse of the generic archiver configuration.

The maven descriptor files are located at a well known path and contains well known contents,
a properties file and pom. The existence of the GA specific paths in the javadoc-jar archive
can help identify the GA of the artifact without needing the original pom or original jar.
There are cases I need to know the GA, but I do not have the 'main' jar or the pom separately.


There is no easy way to automatically generate a maven descriptor like path or file and put
this into the javadoc jar, without polluting the source tree with dummy class files which
exist only generate packages at certain GA paths. Adding complexity to a build process to
generate such files is overkill and needless. Even then we still can't put these under META-INF
to indicate this is meta information only. Certain organizations have strict policies around
adding dummy class files with no operational purpose. All that is needed is to fix the bug
where the archiver configuration is not respected when configured by plugin configuration
- a single line to the javadoc plugin configuration - done.

The javadoc and source plugin are the only two core plugins known to do this, yet there is
no good reason documented. I suggest it was one plugin copied the other. If there was a good
reason, I suggest the archiver configuration library should go to greater lengths to not have
a generic option to add the descriptor.

The existing forced, non-overridable blocking of the descriptor is confusing and not-consistent
with standard archiver configuration use in the very least. The patch preserves backwards
compatibility of the default behaviour just in case we cannot foresee a good reason why it
was done this way.

I can accept a plugin chooses defaults for the archiver configuration, but unless we can cite
a solid reason not to respect user configured archiver configuration, like it breaks well
established Maven tooling which would rely on it only existing except in the main jar ( even
then one could argue it is at user discretion ), I urge this patch to be accepted.

The source plugin has already moved ahead with a patch to fix this. See MSOURCES-81.

> allow javadoc jar to contain Maven descriptor
> ---------------------------------------------
>
>                 Key: MJAVADOC-431
>                 URL: https://issues.apache.org/jira/browse/MJAVADOC-431
>             Project: Maven Javadoc Plugin
>          Issue Type: Bug
>    Affects Versions: 2.10.3
>            Reporter: Peter lynch
>             Fix For: 2.10.4
>
>
> The javadoc:jar mojo explicitly prevents the Maven descriptor from being added to the
produced javadoc.jar file.
> https://github.com/apache/maven-plugins/blob/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugin/javadoc/JavadocJar.java#L299-299
> I could not find an explanation or technical reason why this is done.
> Adding the maven descriptor to the javadoc jar can help expose valuable information about
the build that produced it and should be at the discretion of the build process.
> Expected:
> - allow the archiver used to create the javadoc jar to respect the plexus archiver configuration
if it is configured to include the Maven descriptor.
> - preserve the default behaviour of not including the Maven descriptor, for (unknown)
backwards compatibility reasons only



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

Mime
View raw message