On Mon, Jun 4, 2018 at 2:11 PM, Jonathan Gibbons < jonathan.gibb...@oracle.com> wrote:
> 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. > I completely agree with your analysis. The reason I (and presumably many others) hard-coded overview-summary.html into my URLs is that I was trained by the javadoc tool. E.g. if I visit https://docs.oracle.com/javase/10/docs/api/ today it gets "corrected" in the address bar of my browser to https://docs.oracle.com/javase/10/docs/api/overview-summary.html and it's natural to copy-paste or bookmark that URL. So overview-summary.html is a public interface, not an implementation detail (even if that was the original intent). The jjava se javadocs are important enough that I would probably do #5 for 5 years or so, during which time you can train people by "correcting" overview-summary.html back to index.html or naked .../api/ whatever you think should be the "canonical" URL. I don't know much about search engines (!) but maybe there's metadata to tell search engines what the canonical URL is (or maybe simply redirects are interpreted that way).
