javadoc ignores -XD-Xmaxerrs

[Martin Buchholz]

On Wed, Jun 9, 2010 at 16:40, Jonathan Gibbons
<jonathan.gibbons at oracle.com> wrote:
> On 06/04/2010 06:07 PM, Martin Buchholz wrote:
>>
>> Hi javadoc team,
>>
>> This is a bug report with proposed fix.
>>
>> We have reason to believe that javadoc was designed
>> to accept javac flags like -Xmaxerrs via
>>
>> javadoc -XD-Xmaxerrs=NNNN ....
>>
>> However,
>>
>> this is not documented, except via 'javac -X'
>> javadoc should also really have a -X flag
>> that documents its "nonstandard" -Xxxx flags.
>>
>> The -XD-Xmaxerrs=NNNN flag is not recognized
>> because the Messager in
>> src/share/classes/com/sun/tools/javadoc/Start.java
>> is created before the options are parsed.
>>
>> Here's a fix that works for us, but it seems likely that
>> there is an architecturally cleaner fix:
>>
>> http://cr.openjdk.java.net/~martin/webrevs/openjdk7/javadoc-Xmaxerrs/
>>
>> Martin
>>
>
> Martin,
>
> What are you trying to achieve with your proposed fix (beyond the
> initialization order problem), and does it actually have the effect you
> expected?

We're trying to do generate javadoc for a very large body of java
source code, and we want to keep going even if parts of the code base
don't even compile.

>From a higher-level view, there's the problem of incrementally
generating complete javadocs for a very large partially broken code
base without running into resource exhaustion, that seems like a big
job to fix.

> I believe your proposed fix as-is is subject to NPE for those cases where
> the messager is required before you initialize it.

We recently discovered that independently ourselves.

You need a messager before option parsing, so that you can report
option parsing failures, and you need the option parsing to affect the
messager.

> That's not a big deal;
> I've got a somewhat cleaner fix, as regards the initialization issues.   But
> setting -XD-Xmaxerrs only affects the javac part of javadoc; it seems that
> javadoc can generate an unbounded number of errors and warnings while
> generating the docs themselves, since the javadoc messages are reported via
> different methods that are not subject to the limits.

Thanks for clearing this up.  I have only a hazy understanding of the
architecture of javadoc.

> I'm looking at providing -Xmaxerrs and -Xmaxwarns for javadoc. I think these
> values should encompass all the messages that may be generated (i.e. from
> both javac and javadoc, because anything else is silly) but that leaves a
> question of what the default limit should be -- 100, as is the standard for
> javac, or unbounded, as is (sort-of) the case for javadoc.

"Keep-going" makes a lot more sense as a javadoc default,
but you'd probably still want to get a non-zero return code at the end.
Hmmmm....I'm not sure what the best defaults would be.

Martin