RFR: 8184021: Fix tables in jaxp doc comments to be accessible

huizhe wang huizhe.wang at oracle.com
Tue Jul 11 00:40:49 UTC 2017 

That looks great!  Almost all "green"!

The only exception is the table in javax/xml/validation/Validator.java 
where the empty cell resulted in a reported "ERROR". I tried changing 
<th></th> to <td></td> and saw that the tool happily accepted it:

- 138      *   <th></th>
+ 138      *   <td></td>

If you decide to adopt the above, no need to re-generate the webrevs.

Thanks,
Joe


On 7/10/2017 3:52 PM, Jonathan Gibbons wrote:
> Here is the amended webrev for the work on fixing the tables (and 
> other nits) in the jaxp docs.
>
> As we discussed, I changed the two manually edited tables, in 
> CatalogFeatures and XMLStreamWriter, to use scope=row/col.  There are 
> now no tables in the jaxp repo using headers to identify row and 
> column headers.
>
> I found two more tables that needed fixing in
> /src/java.xml/share/classes/org/xml/sax/package-info.java.
>
> I've also fixed a minor doc bug JDK-8183984 in which ! in the first 
> sentence was causing javadoc to generate invalid HTML output.
> https://bugs.openjdk.java.net/browse/JDK-8183984
>
> Finally, I fixed one more excess <p>, in XMLReaderFactory.
>
> As a result of all this, the java.xml module gets a clean bill of 
> documentary health, for all the checks we are currently tracking.
>
> -- Jon
>
> On 07/08/2017 09:58 AM, Jonathan Gibbons wrote:
>> Joe,
>>
>> Thanks for the feedback.  I've done some experiments and it looks 
>> like we can indeed simplify the more complex tables to always use 
>> scope=row|col.
>>
>> I'll post an amended webrev next week.
>>
>> Thanks for the feedback and suggestion to revisit this issue.
>>
>> -- Jon
>>
>>
>> On 7/7/17 5:50 PM, huizhe wang wrote:
>>> Hi Jon,
>>>
>>> For the table in CatalogFeatures, the id attribute for Type and 
>>> Value are not used, may be unnecessary. Instead, scope="col" can be 
>>> added, is that right?
>>> 50 * <th id="VType">Type</th>
>>> 51 * <th id="VValue">Value</th>
>>>
>>> I'm new to accessibility, but it seems to me the following can use 
>>> scope="colgroup" instead?
>>>
>>> 46 * <th scope="col" colspan="2" style="text-align:center">Value 
>>> [2]</th>
>>>
>>>
>>> Since the 1st and 7th columns already have scope="row",  if 
>>> scope="col" can be added to the 8th (Action) column, the cells in 
>>> the 8th (Action) column then won't need the "headers" attribute, 
>>> would that be right?
>>> 1st column: 74 * <th rowspan="2" scope="row" 
>>> style="font-weight:normal" id="PREFER">PREFER</th> ...
>>> 7th column: 81 * <th scope="row" id="system" 
>>> style="font-weight:normal">{@code system}</th>
>>> 8th column: 82 * <td headers="PREFER system Action">
>>>
>>> For the table in XMLStreamWriter, it looks like to me we can avoid 
>>> the headers for each cell by instead making the following changes:
>>> add rowspan="2" to
>>>    45  *             <th>Method</th> <!-- method -->
>>> add scope="colgroup" to
>>> 46 * <th colspan="2">{@code isRepairingNamespaces} == true</th>
>>> 47 * <th colspan="2">{@code isRepairingNamespaces} == false</th>
>>> remove:
>>>    50  *             <th></th> <!-- method -->
>>>
>>> add scope="col" to
>>> 51 * <th>namespaceURI bound</th>
>>> 52 * <th>namespaceURI unbound</th>
>>> 53 * <th>namespaceURI bound</th>
>>> 54 * <th>namespaceURI unbound</th>
>>>
>>> add scope="row" to the first column of the rows in the body.
>>>
>>> Would that make sense?
>>>
>>> Thanks,
>>> Joe
>>>
>>> On 7/7/2017 2:53 PM, Jonathan Gibbons wrote:
>>>> Sorry, I meant to include that; will post shortly, beside the webrev.
>>>>
>>>> -- Jon
>>>>
>>>> On 07/07/2017 01:33 PM, Lance Andersen wrote:
>>>>> Hi Jon,
>>>>>
>>>>> The changes looked good to me.   Is the html available by chance 
>>>>> to do an extra sanity check?
>>>>>
>>>>> Best
>>>>> Lance
>>>>>> On Jul 7, 2017, at 2:14 PM, Jonathan Gibbons 
>>>>>> <jonathan.gibbons at oracle.com 
>>>>>> <mailto:jonathan.gibbons at oracle.com>> wrote:
>>>>>>
>>>>>> Please review the following fixes to the doc comments in the jaxp 
>>>>>> repo.
>>>>>>
>>>>>> The primary goal is to fix user-written tables in doc comments 
>>>>>> for accessibility, either by updating tables to use scope=row|col 
>>>>>> in header cells for simple tables, or by using the headings 
>>>>>> attribute in more complex tables. The majority of the changes, to 
>>>>>> tables using class="striped", were done mechanically, using a 
>>>>>> custom Java utility. Three tables were fixed up manually.
>>>>>>
>>>>>> In addition, I removed the use of <p> tags which introduced empty 
>>>>>> paragraph. These tags caused warnings when checking the code with 
>>>>>> the "tidy" program.
>>>>>>
>>>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8184021
>>>>>> Webrev: http://cr.openjdk.java.net/~jjg/8184021/webrev.00/ 
>>>>>> <http://cr.openjdk.java.net/%7Ejjg/8184021/webrev.00/>
>>>>>>
>>>>>> -----
>>>>>>
>>>>>> The following list of comments about the changes is ordered 
>>>>>> according to the list in the webrev.
>>>>>>
>>>>>> Catalog:
>>>>>>    removed empty <p>
>>>>>>
>>>>>> CatalogFeatures:
>>>>>>    first table updated manually (class="plain")
>>>>>>    removed empty <p>
>>>>>>    second table updated with utility
>>>>>>
>>>>>> CatalogResolver:
>>>>>>    removed empty <p>
>>>>>>
>>>>>> DatatypeFactory, Duration:
>>>>>>   table updated with utility
>>>>>>
>>>>>> XMLGregorianCalendar:
>>>>>>   all tables updated with utility
>>>>>>
>>>>>> datatype/package-info:
>>>>>>   table updated with utility
>>>>>>
>>>>>> NamespaceContext:
>>>>>>   all tables updated with utility
>>>>>>
>>>>>> XMLEventWriter, XMLInputFactory, XMLOutputFactory, XMLStreamReader:
>>>>>>   table updated with utility
>>>>>>
>>>>>> XMLStreamWriter:
>>>>>>    this is the one table with class="striped" that had to be updated
>>>>>>    manually, because of the complex headers
>>>>>>
>>>>>> SchemaFactory:
>>>>>>    table updated with utility, but table organization could be 
>>>>>> improved (by spec owner)
>>>>>>    for example, to split first column into a name and a URI, 
>>>>>> and/or use the second
>>>>>>    column as a row header.
>>>>>>
>>>>>> Validator, XPath, XPathExpression, xpath/package-info:
>>>>>>   table updated manually (class="plain")
>>>>>>
>>>>>> Attr
>>>>>>   table updated with utility
>>>>>>   table could be improved by removing redundant atributes, like 
>>>>>> rowspan='1' colspan='1'
>>>>>>
>>>>>> Document, Node:
>>>>>>   all tables updated with utility
>>>>>>
>>>>>> -- Jon
>>>>>
>>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
>>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif><http://oracle.com/us/design/oracle-email-sig-198324.gif> 
>>>>>
>>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance 
>>>>> Andersen| Principal Member of Technical Staff | +1.781.442.2037
>>>>> Oracle Java Engineering
>>>>> 1 Network Drive
>>>>> Burlington, MA 01803
>>>>> Lance.Andersen at oracle.com <mailto:Lance.Andersen at oracle.com>
>>>>>
>>>>>
>>>>>
>>>>
>>>
>>
>

More information about the core-libs-dev mailing list