javadoc ignores -XD-Xmaxerrs

[Jonathan Gibbons]

On 06/09/2010 05:02 PM, Martin Buchholz wrote:
> 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.
>
>    

The way to do this would be to isolate the processing of the potentially 
bad source code from the global docs generation.

For example, you could provide and use an "XML Doclet" that you could 
run on source code in small chunks, to render the doc comments for each 
class in a simple XML file closely mirroring the javadoc comments of 
each class. Then separately, you can process these XML files to generate 
the doc pages for each class, and for all the various global tables and 
indices.

-- Jon