Hi,
While updating the build system to better support Java 9 (e.g., javac's
"-release" parameter), I noticed that Javadoc invocation fails with an unknown
error during building the docs:
This is the verbose output of ANT (with -verbose):
[javadoc] Generating Javadoc
[javadoc] No href was given for the link - skipping
[javadoc] No href was given for the link - skipping
[javadoc] Executing 'C:\Program Files\Java\jdk-9\bin\javadoc.exe' with
arguments:
[javadoc] '-locale'
[javadoc] 'en_US'
[javadoc] '-charset'
[javadoc] 'utf-8'
[javadoc] '-d'
[javadoc] 'C:\Users\Uwe
Schindler\Projects\lucene\trunk-lusolr1\lucene\build\docs\core'
[javadoc] '-noindex'
[javadoc] '-protected'
[javadoc] '-J-Xmx512m'
[javadoc] '-overview'
[javadoc] 'C:\Users\Uwe
Schindler\Projects\lucene\trunk-lusolr1\lucene\core\src\java\overview.html'
[javadoc] '-windowtitle'
[javadoc] 'Lucene 7.0.0-SNAPSHOT API'
[javadoc] '-encoding'
[javadoc] 'utf-8'
[javadoc] '-use'
[javadoc] '-docencoding'
[javadoc] 'utf-8'
[javadoc] '-release'
[javadoc] '8'
[javadoc] '-Xdoclint:all'
[javadoc] '-Xdoclint:-missing'
[javadoc] '-doctitle'
[javadoc] 'Lucene 7.0.0-SNAPSHOT core API'
[javadoc] '-bottom'
[javadoc] '
[javadoc] <i>Copyright © 2000-2016 Apache Software Foundation.
All Rights Reserved.</i>
[javadoc] <script src='{@docRoot}/prettify.js'
type='text/javascript'></script>
[javadoc] <script type='text/javascript'>
[javadoc] (function(){
[javadoc] var oldonload = window.onload;
[javadoc] if (typeof oldonload != 'function') {
[javadoc] window.onload = prettyPrint;
[javadoc] } else {
[javadoc] window.onload = function() {
[javadoc] oldonload();
[javadoc] prettyPrint();
[javadoc] }
[javadoc] }
[javadoc] })();
[javadoc] </script>
[javadoc] '
[javadoc] '-classpath'
[javadoc] 'C:\Program Files\Java\apache-ant-1.8.3\lib\ant.jar'
[javadoc] '-version'
[javadoc] '-author'
[javadoc] '-sourcepath'
[javadoc] 'C:\Users\Uwe
Schindler\Projects\lucene\trunk-lusolr1\lucene\core\src\java'
[javadoc] '-linkoffline'
[javadoc] 'https://docs.oracle.com/javase/8/docs/api/'
[javadoc]
'file:/C:/Users/Uwe%20Schindler/Projects/lucene/trunk-lusolr1/lucene/tools/javadoc/java8/'
[javadoc] '-tag'
[javadoc] 'lucene.experimental:a:WARNING: This API is experimental and might
change in incompatible ways in the next release.'
[javadoc] '-tag'
[javadoc] 'lucene.internal:a:NOTE: This API is for internal purposes only and
might change in incompatible ways in the next release.'
[javadoc] 'org.apache.lucene'
[javadoc] 'org.apache.lucene.analysis'
[javadoc] 'org.apache.lucene.analysis.tokenattributes'
[javadoc] 'org.apache.lucene.codecs'
[javadoc] 'org.apache.lucene.codecs.blocktree'
[javadoc] 'org.apache.lucene.codecs.compressing'
[javadoc] 'org.apache.lucene.codecs.lucene50'
[javadoc] 'org.apache.lucene.codecs.lucene53'
[javadoc] 'org.apache.lucene.codecs.lucene54'
[javadoc] 'org.apache.lucene.codecs.lucene60'
[javadoc] 'org.apache.lucene.codecs.lucene62'
[javadoc] 'org.apache.lucene.codecs.perfield'
[javadoc] 'org.apache.lucene.document'
[javadoc] 'org.apache.lucene.geo'
[javadoc] 'org.apache.lucene.index'
[javadoc] 'org.apache.lucene.search'
[javadoc] 'org.apache.lucene.search.similarities'
[javadoc] 'org.apache.lucene.search.spans'
[javadoc] 'org.apache.lucene.store'
[javadoc] 'org.apache.lucene.util'
[javadoc] 'org.apache.lucene.util.automaton'
[javadoc] 'org.apache.lucene.util.bkd'
[javadoc] 'org.apache.lucene.util.fst'
[javadoc] 'org.apache.lucene.util.mutable'
[javadoc] 'org.apache.lucene.util.packed'
[javadoc]
[javadoc] The ' characters around the executable and arguments are
[javadoc] not part of the command.
[javadoc] Javadoc execution
[javadoc] Loading source files for package org.apache.lucene...
[...]
[javadoc] Loading source files for package org.apache.lucene.util.mutable...
[javadoc] Loading source files for package org.apache.lucene.util.packed...
[javadoc] Constructing Javadoc information...
[javadoc] Standard Doclet version 9-ea
[javadoc] Building tree for all the packages and classes...
[javadoc] Generating C:\Users\Uwe
Schindler\Projects\lucene\trunk-lusolr1\lucene\build\docs\core\org\apache\lucene\LucenePackage.html...
[javadoc] Generating C:\Users\Uwe
Schindler\Projects\lucene\trunk-lusolr1\lucene\build\docs\core\org\apache\lucene\analysis\Analyzer.html...
[...]
[javadoc] Generating C:\Users\Uwe
Schindler\Projects\lucene\trunk-lusolr1\lucene\build\docs\core\org\apache\lucene\util\bkd\package-use.html...
[javadoc] Generating C:\Users\Uwe
Schindler\Projects\lucene\trunk-lusolr1\lucene\build\docs\core\org\apache\lucene\util\fst\package-use.html...
[javadoc] Generating C:\Users\Uwe
Schindler\Projects\lucene\trunk-lusolr1\lucene\build\docs\core\org\apache\lucene\util\mutable\package-use.html...
[javadoc] Generating C:\Users\Uwe
Schindler\Projects\lucene\trunk-lusolr1\lucene\build\docs\core\org\apache\lucene\util\packed\package-use.html...
[javadoc] Building index for all the packages and classes...
[javadoc] Generating C:\Users\Uwe
Schindler\Projects\lucene\trunk-lusolr1\lucene\build\docs\core\overview-tree.html...
[javadoc] Generating C:\Users\Uwe
Schindler\Projects\lucene\trunk-lusolr1\lucene\build\docs\core\deprecated-list.html...
[javadoc] Building index for all classes...
[javadoc] Generating C:\Users\Uwe
Schindler\Projects\lucene\trunk-lusolr1\lucene\build\docs\core\allclasses-frame.html...
[javadoc] javadoc: error - an unknown error has occurred
[javadoc] Generating C:\Users\Uwe
Schindler\Projects\lucene\trunk-lusolr1\lucene\build\docs\core\allclasses-noframe.html...
[javadoc] Generating C:\Users\Uwe
Schindler\Projects\lucene\trunk-lusolr1\lucene\build\docs\core\index.html...
[javadoc] Generating C:\Users\Uwe
Schindler\Projects\lucene\trunk-lusolr1\lucene\build\docs\core\overview-summary.html...
[javadoc] 1 error
You see:
[javadoc] javadoc: error - an unknown error has occurred
Shortly before failing the build.
I tried to disable many of the default options we pass to javadoc (like custom
stylesheet sources).
I also tried to inject "-Xold", but this does not work with ant, because
Javadocs seems to only accept this parameter at the beginning of the command
line. With Ant you cannot insert anything at the beginning of command line, so
it complains with "unknown option: -Xold"!!!
I also tried to pass -html5 or -html4, but neither brought a change. It fails
in the same way.
The resulting Javadocs are not viewable, because the stylesheet and scripts are
completely missing, you only see 3 small boxes.
Is there any way to figure out what the "unknown error" is about? I would need
more information to open a bug report.
If you want to reproduce, just checkout Apache Lucene/Solr from Github
(https://github.com/apache/lucene-solr) and run "ant documentation".
Uwe
-----
Uwe Schindler
[email protected]
ASF Member, Apache Lucene PMC / Committer
Bremen, Germany
http://lucene.apache.org/
