On Tue, 2 May 2023 19:26:38 GMT, Joe Wang <jo...@openjdk.org> wrote: >> One other thing to say on this is that jaxp.properties has "XML Library >> (java.xml) Configuration File" at the top of the file, maybe that could be >> used in the module description instead of "JAXP Configuration File". > > 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. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/12985#discussion_r1185814343
