[jira] [Commented] (MJAVADOC-560) Clarify outputDirectory, reportOutputDirectory in javadoc:javadoc documentation

["Robert Scholte (Jira)" <ji...@apache.org>]

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

Robert Scholte commented on MJAVADOC-560:
-----------------------------------------

What basically needs to be done is introduce a {{protected abstract File getJavadocOutputDirectory()}} and move the outputDirectory to JavadocJar (and make it private). 
Check if destDir can be used as alias and clean up all kinds of double output directory checks.
Next a lot of unittests need to be fixed by replacing outputDirectory with reportOutputDirectory.
As this will touch parameters, we'd better move this to 4.0.0 to ensure we won't make breaking changes halfway the 3.x releases.


> 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
>             Fix For: 4.0.0
>
>
> 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
(v8.3.4#803005)