JDK-8196202 [1] introduced a change to the javadoc tool (and because of
that, to the Java SE API documentation) such that frames are not
generated by default.
This has had a deliberate but somewhat unexpected consequence on the
Java SE API docs, of getting "404: Not found" on URLs that explicitly
referenced the .../api/overview-summary.html page.
Here is what happened:
The issue is that previously there were two pages:
* index.html (contained the frame definitions)
* overview-summary.html (contained the content for the main top-level
user-visible page)
Now that we are not generating frames by default, we only need one
page. The tool is generating the content for the main top-level
user-visible page in index.html, and there is no need for
overview-summary.html page, which is therefore not generated.
This behavior has been the behavior since the javadoc option --no-frames
was added a year ago. In other words, the recent change [2] was just to
flip the default, not to substantially change the behavior of the
--frames and --no-frames options.
@@ -197,13 +197,13 @@
*/
public boolean createoverview = false;
/**
* Specifies whether or not frames should be generated.
- * Defaults to true; can be set by --frames; can be set to false by
--no-frames; last one wins.
+ * Defaults to false; can be set to true by --frames; can be set to false
by --no-frames; last one wins.
*/
- public boolean frames = true;
+ public boolean frames = false;
/**
* This is the HTML version of the generated pages.
* The default value is determined later.
*/
So, what are our options.
0. Do nothing. People, and search engines, will learn to use a URL
ending in "api/" or "api/index.html"
1. Back out the change. This is undesirable, because the plan is to
eventually eliminate all support for frames, and this change was one
step in that sequence.
2. Without backing out the change to the tool, we could reverse the
effect of the change in the Java SE API documentation, by specifying the
use of the --frames options to generate the Java SE API docs. But like
#1, this is undesirable because of the plan to remove support for frames.
3. Generate overview-summary.html instead of index.html. This will
break folk that think that api/index.html is the top level file.
4. Generate overview-summary.html instead of index.html, and generate
index.html with a redirect to overview-summary.html
5. Leave the current behavior, but add back overview-summary.html as a
redirect to index.html.
Long term, of the two names, index.html is a better default for the top
level page than overview-summary.html. This suggests that the top two
choices are option #0 and option #5, with #5 providing some minor
short-term relief for folk who expect to see overview-summary.html.
-- Jon
[1] https://bugs.openjdk.java.net/browse/JDK-8196202
[2] http://cr.openjdk.java.net/~jjg/8196202/webrev.00/
