On Fri, 5 May 2023 08:12:01 GMT, Alan Bateman <al...@openjdk.org> wrote:
>> Changed the opening statement and also the naming of config file as above. > > I've looked through the updated proposal but I think the intro is going to > take a few iterations to get to something that is easy to read. I had hoped > the intro would provide an overview of the APIs in the module and establish > the terminology that is needed to read further. The existing text isn't great > but it does name the APIs in the module so the reader knows there are several > APIs for processing XML. With the update, the names of the APIs in the module > is lost, and in its place, the text switches to "XML library" and talks about > factories and processors. I understand the focus of this PR is to introduce a > system property to allow for configuration file but it's changing important > API docs that introduce the APIs. > > My view is that we have to create a new introduction that provides a summary > of the APIs in the module and a short summary of some concepts. We can't have > API docs talk about "factories" and "processors" without defining them. This > intro/setup is needed before diving into the configuration, which we might > title "Configuring factories and processors" with a summary of the various > ways that they can be configured. I think the text from the "Property > Precedence" section will need to move into the section on Configuration as it > is hard to list the various ways to configure without also talking about > precedence. > > Once you have a good introduction and seciton on Configuration then I think > the other sections will follow without too much work. New introduction added, along with sections leading up to the Configuration File. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/12985#discussion_r1206026416
