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

[Roger Riggs]

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/20200306/3ff4b60f/attachment-0001.htm>