[Comment Edited] (MJAVADOC-560) Clarify outputDirectory, reportOutputDirectory in javadoc:javadoc documentation

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

[Comment Edited] (MJAVADOC-560) Clarify outputDirectory, reportOutputDirectory in javadoc:javadoc documentation

JIRA jira@apache.org

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

Gili edited comment on MJAVADOC-560 at 2/10/19 7:52 PM:
--------------------------------------------------------

{quote}The directories have different purposes and both and required by the plugin (reportOutputDirectory by all goals, outputDirectory only by packaging goals).
{quote}
I'm a little confused by this given that {{javadoc:javadoc}} does not generate a JAR file yet [https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html] mentions "outputDirectory".
{quote}The outputDirectory is used for the jar, the reportOutputDirectory is used for the generated javadocs.
{quote}
So, anywhere we have "outputDirectory" I would change the description to "Specifies the destination directory where the javadoc JAR file is written".

UPDATE: I just reviewed point 2 (the fact that reportOutputDirectory is used instead of outputDirectory) and I think that was a misunderstanding on my part so you can ignore this for now.


was (Author: cowwoc):
{quote}The directories have different purposes and both and required by the plugin (reportOutputDirectory by all goals, outputDirectory only by packaging goals).
{quote}
I'm a little confused by this given that {{javadoc:javadoc}} does not generate a JAR file yet [https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html] mentions "outputDirectory".
{quote}The outputDirectory is used for the jar, the reportOutputDirectory is used for the generated javadocs.
{quote}
So, anywhere we have "outputDirectory" I would change the description to "Specifies the destination directory where the javadoc JAR file is written".

> Clarify outputDirectory, reportOutputDirectory in javadoc:javadoc documentation
> -------------------------------------------------------------------------------
>
>                 Key: MJAVADOC-560
>                 URL: https://issues.apache.org/jira/browse/MJAVADOC-560
>             Project: Maven Javadoc Plugin
>          Issue Type: Bug
>          Components: javadoc
>    Affects Versions: 3.1.0
>            Reporter: Gili
>            Priority: Major
>
> Looking at the documentation for javadoc:javadoc at [https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html] I see three problems:
>  # The documentation lists both *outputDirectory* and *reportOutputDirectory* parameters, having the same description. It's not clear what each one is used for or what happens if one property is changed without the other.
>  # The default value of *outputDirectory* is listed as *${project.build.directory}/apidocs* but the value that is actually used is *${project.reporting.outputDirectory}/apidocs* (the value of *reportOutputDirectory*).
>  # It was extremely difficult to find any documentation on *${project.reporting.outputDirectory}***, such as what its default value is. I eventually found [https://maven.apache.org/pom.html#Reporting] but Google does not link directly to this page/section because it doesn't contain an explicit reference to *${project.reporting}*.
> Suggested fix(es):
>  # Drop one of the two parameters, ideally *reportOutputDirectory*, to avoid confusion.
>  # Update the documentation so it lists the correct default value for *outputDirectory*.
>  # Link directly from mention of *${project.reporting.outputDirectory}* to [https://maven.apache.org/pom.html#Reporting]



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)