[MJAVADOC-722] Log javadoc warnings and errors to file

[alzimmermsft]

Following this checklist to help us incorporate your
contribution quickly and easily:

• Make sure there is a JIRA issue filed
  for the change (usually before you start working on it). Trivial changes like typos do not
  require a JIRA issue. Your pull request should address just this issue, without
  pulling in other changes.
• Each commit in the pull request should have a meaningful subject line and body.
• Format the pull request title like [MJAVADOC-XXX] - Fixes bug in ApproximateQuantiles,
  where you replace MJAVADOC-XXX with the appropriate JIRA issue. Best practice
  is to use the JIRA issue title in the pull request title and in the first line of the
  commit message.
• Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
• Run mvn clean verify -Prun-its to make sure basic checks pass. A more thorough check will
  be performed on your pull request automatically.

If your pull request is about ~20 lines of code you don't need to sign an
Individual Contributor License Agreement if you are unsure
please ask on the developers list.

To make clear that you license your contribution under
the Apache License Version 2.0, January 2004
you have to acknowledge this by using the following check-box.

• I hereby declare this contribution to be licenced under the Apache License Version 2.0, January 2004

• In any other case, please file an Apache Individual Contributor License Agreement.

Adds a new @errors file to the output directory, similar to the @options, @packages, @argfile, and @files, that contains the warnings and errors returned by the Javadoc process and won't be contained in a Javadoc JAR. This allows for external processes to capture warnings and errors produced during Javadoc generation without the need for complex logging processes and ensures that the Javadoc warnings and errors aren't interleaved with other data if the logger is handling requests from multiple threads.

[alzimmermsft]

Hi @michael-o, is there anything else I need to update in this PR? I'm more than happy to make those changes

[alzimmermsft]

@michael-o just checking in again to see if there is anything else that is needed for this change

[michael-o]

I won't review this before October

[alzimmermsft]

I won't review this before October

Got it, thanks for the update. I'll check back in a couple weeks and make sure there are no merge conflicts.

[alzimmermsft]

Hey @michael-o just following up on this 😃

[michael-o]

So, while I partially understand this request, I consider it ill-designed. Treating the stdout/stderr as @argfiles or Javadoc produce feels wrong. This is just yet another convenience output just like in other plugins to write to a file.

Your request is similar to https://maven.apache.org/plugins/maven-dependency-plugin/list-mojo.html#outputFile or what other plugins do.

[alzimmermsft]

So, while I partially understand this request, I consider it ill-designed. Treating the stdout/stderr as @argfiles or Javadoc produce feels wrong. This is just yet another convenience output just like in other plugins to write to a file.

Your request is similar to https://maven.apache.org/plugins/maven-dependency-plugin/list-mojo.html#outputFile or what other plugins do.

Thanks for the feedback, I can get this changed to more closely follow the design used by maven-dependency-plugin if you see that as the best direction forward. Using outputFile to redirect the output instead of @errors, and changing outputing to file from being an additional output target to the only output target as right now @errors is an additional output in comparison to outputFile which is a redirection of output.

[michael-o]

@alzimmermsft Can you rebase, I will take another look at it. I have now a better understanding of this plugin. Ideally, can you also create an IT where such an output is depicted as well?

[alzimmermsft]

@alzimmermsft Can you rebase, I will take another look at it. I have now a better understanding of this plugin. Ideally, can you also create an IT where such an output is depicted as well?

Gladly, I will rebase this change soon and will add an integration test when I do that.

Since it's been a while, do you still want @errors replaced with using outputFile to completely redirect error output? Similar to what is seen with plugins like Maven Dependency where outputFile completely redirects the output.

[michael-o]

I will get back to you as soon as possible.

[michael-o]

So I reviewed it again and still consider is as flawed. @files are pure input files to the Javadoc process, they have nothing in common with the output of the process. I still consider stderrOutputFile/errorOutputFile or similar as the param to go. If someone wants/needs he could add stdoutOutputFile, you get the picture.