RFR: JDK-8172312 Update docs target and image for new combined docs

[Magnus Ihse Bursie]

On 2017-03-30 15:42, Erik Joelsson wrote:
> Hello,
>
> Javadoc.gmk:159 looks like too much indentation
>
> The variable JAVADOC_SOURCE_DIRS is starting to seem a bit redundant. 
> It does contain two directories that would not be included if you 
> replaced $(call PathList, $(JAVADOC_SOURCE_DIRS)) with $(call 
> GetModuleSrcPath), but that could be rectified by adding 
> $(SUPPORT_OUTPUTDIR)/rmic to GENERATED_SRC_DIRS and share/doc/stub to 
> SRC_SUBDIRS in Javadoc.gmk. Doing so would make the dependency 
> calculation and the actual source dir input be based on the same 
> definitions.

This is a really nice idea! Unfortunately, it was not so easy. :-(

Adding rmic to GENERATED_SRC_DIRS causes java.base compilation to fail with:
Compiling 2898 files for java.base
warning: [path] bad path element 
"/localhome/hg/jdk9-sandbox/build/linux-x64/support/rmic": no such directory
error: warnings found and -Werror specified
1 error

I could of course add an mkdir somewhere before java.base-java is 
executed, but it doesn't really feel good. I think it's better to 
explicitly add the rmic gensrc dir to the javadoc generation.

The same goes for the share/doc/stub. Adding it caused a whole bunch of 
errors when compiling java.management.rmi:
/localhome/hg/jdk9-sandbox/jdk/src/java.rmi/share/doc/stub/java/rmi/activation/ActivationGroup_Stub.java:72: 
warning: [rawtypes] found raw type: MarshalledObject
     public java.rmi.MarshalledObject newInstance(
                    ^
   missing type arguments for generic class MarshalledObject<T>
   where T is a type-variable:
...

I assume that the sole reason for putting ActivationGroup_Stub.java into 
the "share/doc/stub" directory was to prohibit it from being part of 
normal compilation.

So, once more, I'll rather add that directory to just the javadoc 
generation.

Nevertheless, using $(call GetModuleSrcPath) instead is very nice, even 
if I have to add a couple of paths.

New webrev coming up soon...

/Magnus

>
> /Erik
>
> On 2017-03-30 15:05, Magnus Ihse Bursie wrote:
>> As a part of JEP 299, we should build the Javadoc as a single 
>> combined output, instead of a dozen or so individual javadoc bundles. 
>> This bug fixes this. The selection on what to include is now based on 
>> modules instead of packages.
>>
>> The fix in MakeBase.gmk is to keep CacheFind quiet if the src dir(s) 
>> does not exist, otherwise find can emit an error message. (This was 
>> provoked by the new call to SetupZipArchive).
>>
>> The module selection has been contributed by Mandy Chang.
>>
>> I intend to push this to JDK9. Since this is a noreg-doc bug, no 
>> special RDP2 process is required.
>>
>> Bug: https://bugs.openjdk.java.net/browse/JDK-8172312
>> WebRev: 
>> http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.01
>>
>> /Magnus
>>
>