RFR: JDK-8195796: Reduce the size of relative URLs in generated docs

[Jonathan Gibbons]

Thanks.

With respect to the difficulty of before/after comparison, I ran a 
"broken links" checker, before/after, and verified that the set of 
broken links is the same. While this doesn't guarantee the "after" links 
point to exactly the right place, together with the verification in the 
tests, it does strongly indicate that links do not point to non-existent 
places.

-- Jon

On 01/22/2018 09:46 AM, Kumar Srinivasan wrote:
> Hi Jon,
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java.udiff.html 
>
>
> redundant code commented out, probably best to nuke it.
>
> test/langtools/jdk/javadoc/doclet/testDocPaths/TestDocPaths.java
>
> Objects.equals likely not needed as per our hallway discusssion.
>
>   72         if (!Objects.equals(expect, found)) {
>   73             error("Mismatch:\n"
>   74                 + "  expect: " + expect);
>   75         }
>
> Besides that, nothing else stands out.
>
> With the changes in the output, inspecting the before/after outputs is 
> near impossible.
> I think the sooner we get this in, and have folks test it out, the 
> better.
> So I give a thumbs up.
>
> Kumar
>
>
> On 1/19/2018 2:26 PM, Jonathan Gibbons wrote:
>> Please review some work to reduce the size of relative URLs within a 
>> documentation bundle.
>> The work is fully described in the JBS issue.
>>
>> The work was done in 3 steps, which is reflected in the webrev. You 
>> can either view the
>> top-level cumulative webrev, or individual webrevs for each of the 3 
>> steps. The work
>> will be pushed as a single changeset.
>>
>> Step 1.
>> Add new methods normalize and relativize to DocPaths. There's a new 
>> unit test for the
>> new functionaility.   I cleaned up the doc comments as well.
>>
>> Step 2.
>> Change DocLink to use a DocPath internally, instead of a String.
>> Add a new method to leverage the new DocPath functionality, to 
>> generate simplified
>> DocLinks.   I cleaned up the doc comments as well.
>>
>> Step 3.
>> Update Links to use the new DocLink functionality. This is 
>> conceptually the simplest
>> of the 3 steps, but it causes simple, derivative changes in both 
>> source and tests.
>> Start by reviewing Links.java ... Links is changed from being a 
>> singleton object
>> to a per-file object, and a number of methods are changed from being 
>> static methods
>> to instance methods, to avail themselves of the information about 
>> what file the link
>> will be generated in.
>>
>> A number of tests are affected. Almost without exception, all the 
>> changes are to remove
>> unnecessary content from href values, depending on the file in which 
>> the link is
>> generated.
>>
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8195796
>> Webrev: http://cr.openjdk.java.net/~jjg/8195796/webrev.00/
>>     See the 3 links, labelled "Steps", on the index page, for the 
>> webrevs for each
>>     of the steps described above.
>>
>> -- Jon
>