Pavel,
Thanks for researching the background.
-- Jon
On 2/21/20 7:04 AM, Pavel Rappo wrote:
On 20 Feb 2020, at 17:49, Jonathan Gibbons <[email protected]> wrote:
On 2/20/20 7:14 AM, Pavel Rappo wrote:
Hi Hannes,
What is the background of this "?is-external=true" feature? How was it used in
the first place? Is there anything I can read on that?
My recollection/impression is that this may have been related to the frames
feature
and to support for updating the window title. If you want to follow up, I
recommend
getting an older copy of the source and look for occurrences of the string,
particularly
in .js files.
Thanks, Jon. It turns out that "?is-external=true" is exclusively used for
displaying external documentation in the framed version of generated HTML pages.
We did away with frames in Standard Doclet in JDK-8215599, so there should be no
repercussions for removing this leftover bit.
A bit of background
===================
Javadoc can be instructed to use external referenced classes [1]:
*Note*: External referenced classes are classes that are not passed into
the javadoc command on the command line. Links in the generated
documentation to external referenced classes are called external references
or external links. For example, if you run the javadoc command on only the
java.awt package, then any class in java.lang, such as Object, is an
external referenced class. Use the -link and -linkoffline options to link
to external referenced classes. The source comments of external referenced
classes are not available to the javadoc command run.
That "?is-external=true" portion of the URL was used for deciding if a page
should set its title to the parent window (the container of all the frames).
The code that used to handle this was a tiny JavaScript function generated by
(currently extinct) HtmlWriter.java
098 /**
099 * Print the script code to be embeded before the </HEAD>
tag.
100 */
101 protected void printWinTitleScript(String winTitle){
102 if(winTitle != null && winTitle.length() > 0) {
103 script();
104 println("function windowTitle()");
105 println("{");
106 println(" if (location.href.indexOf('is-external=true') ==
-1) {");
107 println(" parent.document.title=\"" + winTitle +
"\";");
108 println(" }");
109 println("}");
110 scriptEnd();
111 noScript();
112 noScriptEnd();
113 }
114 }
This function was then inserted into HTML pages that were describing types.
For example, here is an excerpt from String.html [2]:
...
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="String (Java Platform SE 8 )";
}
}
catch(err) {
}
//-->
...
-------------------------------------------------------------------------------
[1] https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html
[2] https://docs.oracle.com/javase/8/docs/api/java/lang/String.html
I'm surprised to see the tests' @bug tags are updated to include this bug
number.
I thought that an @bug tag needs to be updated when the test has been
meaningfully
changed. In other words, when the relation between the test and the bug is
stronger than mere "updated because otherwise fails".
Agreed,
I appreciate that the semantics of @bug might depend on the area, still:
https://openjdk.java.net/jtreg/faq.html#when-should-i-update-the-bug-entry-in-a-test-description
I think opinions have differed over time, and there is room for a range of
opinion.
I think the best way to look at this is to ask, if I want to select and run the
tests related
to a specific bug fix, should I include this test. That is what the `@bug` tag
and the
corresponding `-bug` option are for.
-Pavel
On 20 Feb 2020, at 13:09, Hannes Wallnöfer <[email protected]> wrote:
Please review:
JBS: https://bugs.openjdk.java.net/browse/JDK-8232438
Webrev: http://cr.openjdk.java.net/~hannesw/8232438/webrev.00/
The is-external=true query was the only use of query functionality in DocLink,
so I removed support for query strings in DocLink. The rest of the patch
consists of removing the query string from test fixtures.
Thanks,
Hannes
