RFR [15] 8239487: Better links generation for system properties found in HTML files

[Roger Riggs]

Yes, the output looks fine.

I didn't review the code so I don't consider that I should be a "Reviewer".

Roger


On 3/9/20 2:18 PM, Pavel Rappo wrote:
> Thanks Roger! I reckon this is the green light from you, right?
> If so, do you want me to add you as "Reviewer"?
>
> Hopefully, we'll figure out how to convey the fact that
> there are missing <title>s to the user real soon.
>
> -Pavel
>
>> On 6 Mar 2020, at 19:10, Roger Riggs <Roger.Riggs at Oracle.com> wrote:
>>
>> Hi Pavel,
>>
>> The System Properties page looks better with the links qualified by class or package, or
>> the html document title. Developers will want to have a <title> on their document
>> so the properties listing is most informative.
>>
>> Thanks, Roger
>>
>> On 3/6/20 7:51 AM, Pavel Rappo wrote:
>>> Hello,
>>>
>>> Please review the change for
>>> https://bugs.openjdk.java.net/browse/JDK-8239487
>>> :
>>>
>>>    
>>> http://cr.openjdk.java.net/~prappo/8239487/webrev.00/
>>>
>>>
>>> This change addresses 2 closely related issues on the "System Properties Page":
>>>
>>>      8239485: Define behavior of the System Properties page when no system properties are available
>>>      8239487: Better links generation for system properties found in HTML files
>>>
>>> This change does NOT affect the (somewhat related) representation of search
>>> results in the Interactive Search or the looks of the Index pages in any way.
>>>
>>> The net effect of JDK-8239487 can be seen when comparing the outputs.
>>> (For practical reasons the below two links contain only bare-bones versions
>>> of the system properties page out of all the documentation.)
>>>
>>> Before:
>>>
>>>    
>>> http://cr.openjdk.java.net/~prappo/8239487/before/system-properties.html
>>>
>>>
>>> After:
>>>
>>>    
>>> http://cr.openjdk.java.net/~prappo/8239487/webrev.00/after/system-properties.html
>>>
>>>
>>>    ***
>>>
>>> For convenience I split this change into 4 changesets, called phase-{1, 4},
>>> which are applied in this particular order.
>>>
>>> phase-{1, 2} are intermediate, but somewhat necessary, refactorings.
>>> phase-{3, 4} are the core of the change.
>>>
>>> * phase-1 splits Category.SEARCH_TAGS into two separate categories, Category.INDEX
>>> and Category.SYSTEM_PROPERTY. The reason is that more often than not, items of
>>> those categories are consumed separately. This also allows to remove the hacky
>>> systemProperty flag from SearchIndexItem.
>>>
>>> There are still a few cases left where items of those categories are consumed
>>> as if they were of a single category. In these cases careful attention is
>>> required. For example, since INDEX and SYSTEM_PROPERTY items are no longer
>>> sorted as a whole, a use-site sorting is applied where necessary.
>>>
>>> There are changes to make the SearchIndexItems container work with the Stream
>>> API rather than with Collections. I'm not 100% sure if the Stream API is the
>>> right abstraction here, but for now, it seems to fit better than the alternatives.
>>> That said, in some places Streams API had to be shoehorned (for now) by using
>>> stream.iterator() "escape hatch".
>>>
>>> Signatures of the query methods in SearchIndexItems have also been fixed to
>>> accommodate for the change, described above, in Category. There's a top-level
>>> @apiNote in SearchIndexItems describing the details.
>>>
>>> On a related note. If that (required, optional...) signature pattern proves
>>> useful, we could move SearchIndexItems.concat to Utils for reuse.
>>>
>>> * phase-2 is a small cleanup that leverages Stream API from SearchIndexItems
>>> where practical.
>>>
>>> * phase-3 is the meat of the change. The DocFilesHandlerImpl.getWindowTitle
>>> method is extracted and moved to Utils. A String field "referrer" is introduced
>>> in SearchIndexItem to hold a description (title) of a non-program elements, such
>>> as HTML files. The System Properties Page is no longer generated if there are no
>>> system properties. Links to program elements are displayed in a monospace font,
>>> whereas non-program elements are displayed in a proportional font. "Overview"
>>> file is treated specially (it's not of kind DOCFILE, neither is it a program
>>> element) as it should be displayed in a proportional font.
>>>
>>> Some tests are adapted to reflect that the System Properties Page is now
>>> generated conditionally. "system-properties.html" has been excluded from the
>>> "standardExpectFiles" set in APITest. A single {@systemProperty} tag is injected
>>> into TestMetadata.java. TestSystemPropertyPage is updated. Fixed some typos
>>> along the way.
>>>
>>> * By phase-4 it became apparent that search item needs to store richer context
>>> than that of provided by a bunch of string fields. So the anemic String referrer
>>> field is swapped for the DocletElement element field. A cache of HTML titles is
>>> moved to the use site. Once again updated the TestSystemPropertyPage test.
>>>
>>> Changed presentation in the SystemPropertiesWriter.createLink. Non-program
>>> elements are rendered with an extra bit of context: the enclosing package. If a
>>> non-program element has no <title>, the code falls back to the file name. This
>>> is done in a more reliable way than it used to be (the code that relied on
>>> "doc-files" substring was pretty brittle).
>>>
>>> Notes
>>> =====
>>>
>>> 1. I must say that it is unsettling to see how much of the presentation detail
>>> spills over into the Java code :( This is something to think about while working
>>> on HTML and CSS.
>>>
>>> 2. I do believe that this change addresses most of the concerns raised when the
>>> System Properties page was introduced:
>>>
>>>    
>>> https://mail.openjdk.java.net/pipermail/javadoc-dev/2019-December/001234.html
>>>
>>>
>>> That said, there is a lot more that can be done here. For example, even the
>>> current, improved, page might look untidy and cluttered should there appear system
>>> properties linked from both doc files and program elements. Have a look at the
>>> following, contrived, example (this is the actual output of the TestSystemPropertyPage test):
>>>
>>>    
>>> http://cr.openjdk.java.net/~prappo/8239487/webrev.00/test-output/system-properties.html
>>>
>>>
>>> This suggests some visual improvements are required. One way it could be done is
>>> by using description lists (<dd>) instead of plain comma-separated lists.
>>> (A note to self. Should the way <dl>s are rendered depend on the used locale?
>>> Are those subject to the same localization concerns as comma-separated lists?)
>>>
>>> -Pavel
>>>
>>>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20200309/25d6fbbf/attachment-0001.htm>