-
Enhancement
-
Resolution: Fixed
-
P3
-
13
-
b19
Currently, the HTML used to present the inheritance tree for a type misuses lists. For example, look at
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/HashMap.html
<ul class="inheritance">
<li><a href="../lang/Object.html" title="class in java.lang">java.lang.Object</a></li>
<li>
<ul class="inheritance">
<li><a href="AbstractMap.html" title="class in java.util">java.util.AbstractMap</a><K,​V></li>
<li>
<ul class="inheritance">
<li>java.util.HashMap<K,​V></li>
</ul>
</li>
</ul>
</li>
</ul>
There are no natural "lists" here, other than the "list" of parents in the supertype chain, and that "list" is not what is being represented by <ul>/<li>.
Generally, "lists" are for collections of "related" objects of a similar kind. There is no "similar kind" between "the name of a type" and "the subtypes of that type". I believe the primary reason <ul>/<li> is being used here is to get the indentation which comes "for free", (or almost so: we're having to use CSS to get rid of the bullets!) Using HTML like that may have been important in the early days of javadoc, before there was CSS, when you only had HTML elements available to get different visual effects.
Assuming appropriate CSS updates, this can be equivalently be represented by using <div> to achieve the indentation instead of <ul>/<li>:
<div class="inheritance">
<a href="../lang/Object.html" title="class in java.lang">java.lang.Object</a></li>
<div class="inheritance">
<a href="AbstractMap.html" title="class in java.util">java.util.AbstractMap</a><K,​V></li>
<div class="inheritance">
java.util.HashMap<K,​V>
</div>
</div>
</div>
That was a simple replacement of <ul>/<li> with <div>. One other minor issue that could be addressed is that it's a block of text with no indication of its meaning. Visually, we can look at the pixels on the page and guess that it is an inheritance hierarchy, and that is reinforced by those geeky enough to look at the HTML source and see the class name ("inheritance") on the <ul> or <div> nodes. But neither provide (easy) assistance to anyone using a screen reader. One proposal would be to use the "title" attribute, which is now a global attribute in HTML 5 and so can be put on any element, which could be used to put a localizable string on the inheritance tree ... perhaps on the outermost node (<div>) of the inheritance tree. For example,
<div class="inheritance" title="inheritance tree">
<a href="../lang/Object.html" title="class in java.lang">java.lang.Object</a></li>
<div class="inheritance">
<a href="AbstractMap.html" title="class in java.util">java.util.AbstractMap</a><K,​V></li>
<div class="inheritance">
java.util.HashMap<K,​V>
</div>
</div>
</div>
where the content of the title comes from a resource file.
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/HashMap.html
<ul class="inheritance">
<li><a href="../lang/Object.html" title="class in java.lang">java.lang.Object</a></li>
<li>
<ul class="inheritance">
<li><a href="AbstractMap.html" title="class in java.util">java.util.AbstractMap</a><K,​V></li>
<li>
<ul class="inheritance">
<li>java.util.HashMap<K,​V></li>
</ul>
</li>
</ul>
</li>
</ul>
There are no natural "lists" here, other than the "list" of parents in the supertype chain, and that "list" is not what is being represented by <ul>/<li>.
Generally, "lists" are for collections of "related" objects of a similar kind. There is no "similar kind" between "the name of a type" and "the subtypes of that type". I believe the primary reason <ul>/<li> is being used here is to get the indentation which comes "for free", (or almost so: we're having to use CSS to get rid of the bullets!) Using HTML like that may have been important in the early days of javadoc, before there was CSS, when you only had HTML elements available to get different visual effects.
Assuming appropriate CSS updates, this can be equivalently be represented by using <div> to achieve the indentation instead of <ul>/<li>:
<div class="inheritance">
<a href="../lang/Object.html" title="class in java.lang">java.lang.Object</a></li>
<div class="inheritance">
<a href="AbstractMap.html" title="class in java.util">java.util.AbstractMap</a><K,​V></li>
<div class="inheritance">
java.util.HashMap<K,​V>
</div>
</div>
</div>
That was a simple replacement of <ul>/<li> with <div>. One other minor issue that could be addressed is that it's a block of text with no indication of its meaning. Visually, we can look at the pixels on the page and guess that it is an inheritance hierarchy, and that is reinforced by those geeky enough to look at the HTML source and see the class name ("inheritance") on the <ul> or <div> nodes. But neither provide (easy) assistance to anyone using a screen reader. One proposal would be to use the "title" attribute, which is now a global attribute in HTML 5 and so can be put on any element, which could be used to put a localizable string on the inheritance tree ... perhaps on the outermost node (<div>) of the inheritance tree. For example,
<div class="inheritance" title="inheritance tree">
<a href="../lang/Object.html" title="class in java.lang">java.lang.Object</a></li>
<div class="inheritance">
<a href="AbstractMap.html" title="class in java.util">java.util.AbstractMap</a><K,​V></li>
<div class="inheritance">
java.util.HashMap<K,​V>
</div>
</div>
</div>
where the content of the title comes from a resource file.