Jakarta XML Web Services 2.3 apidocs

[lukasj]

Signed-off-by: Lukas Jungmann lukas.jungmann@oracle.com

Include the following in PR#2:

• Specification JavaDoc in the wombat/x.y/apidocs directory.

[netlify]

Deploy preview for jakartaee-specifications ready!

Built with commit eba9fab

https://deploy-preview-124--jakartaee-specifications.netlify.com

[kwsutter]

@lukasj, I just downloaded all of these apidocs to review them and they don't look quite the same as the other specifications' apidocs. For example, if I open the "index.html" on other apidocs, I get a multi-paneled view of the apidocs with a list of classes on the left with the overview on the right. With this web services 2.3 index.html, I am getting a Module view. I can't even find the Overview view.

Also, when I look at the Module view, the top line of description says "java.xml.ws". Shouldn't that be "javax.xml.ws"?

[lukasj]

in JDK9/10 the module name for this component was 'java.xml.ws', see: https://docs.oracle.com/javase/9/docs/api/java.xml.ws-summary.html I'd be fine with changing this to 'jakarta.xml.ws' but forcing users to go through 'java.xml.ws' -> 'javax.xml.ws' -> 'jakarta.xml.ws' transitions does not look like good idea to me. My thinking is let's keep what we have for the initial (Jakarta EE 8 related ) release and switch to 'jakarta.xml.ws' (or whatever becomes prefered) for the next release. As for the javadoc format - the output is the default from javadoc from/on jdk11 which no more creates overview page. I do think this makes sense since this API (together with JAF/JAXB/JAXWS) is supposed to be replacement/minor update to the module removed from JDK 11.

Questions:

• Do you require changing current module name from 'java.xml.ws' to 'javax.xml.ws' now, thus forcing people to adopt the change and do similar change once new 'jakarta'-like module name gets decided?
• Do you require javadoc to be in JDK 8 format? (not sure how much work that would mean yet, the main build requires JDK 11)

thanks.

[kwsutter]

Thanks for the explanations, @lukasj. And, apologies for my missing this comment earlier...

Re: Module name. I didn't make the connection with the module name as part of the Java SE 9 modularity. I guess I'm still not a convert... :-) If that was the intent of this module name, then let's just leave it consistent with what was done previously for Java 9/10. No need to introduce this type of change at this point, just wait until we do something in a future version of Jakarta EE when we address Java 9 Modularity.

Re: Javadoc format. Although I would prefer to see the javadoc in a consistent format with the rest of Jakarta EE 8, I really don't want to introduce extra work for these components. As you said, since they are a replacement for the modules removed from Java 11, retrofitting the javadoc back to Java SE 8 format sounds like busy work. I'm okay with leaving them as is.

[kwsutter]

@lukasj has provided sufficient justification for the Module name and the Javadoc format questions. I will leave it to him if he wants to spend the cycles to clean up the Javadoc.

[bshannon]

This "module" will work on JDK 8, right? That's one of the requirements for Jakarta EE 9
that the API (at least) work on JDK 8. And likely we will need an implementation that will
work on JDK 8 as part of Eclipse GlassFish 6.0. And since we're not defining any JPMS
module names as part of the Jakarta EE 9 specifications, the javadocs should really be in
JDK 8 format, with no reference to modules. (Module names, if present, are an implementation
detail.)

So, I think these javadocs should be produced in JDK 8 style.

[kwsutter]

So, I think these javadocs should be produced in JDK 8 style.

I'll jump on this JDK 8 style for Javadoc band wagon. I was flexible previously, but if we have more than just me asking for it, then let's do it. As @bshannon also pointed out, the APIs need to be consistent with Java SE 8 anyway, so let's ensure that's the case by generating the Javadoc using Java SE 8. Thanks.

[lukasj]

well, wrt javadoc format I'm limited with what javadoc from JDK 11 allows me todo. I tried passing '--frames' option to it and got both variants - with as well as without frames, where the former requires explicit query parameter.; so if I update URL to javadoc within spec PR from "./apidocs" to "./apidocs/index.html?overview-summary.html", first impression visitor gets should be consistent with other specs (ie it has frames); going to "./apidocs" or "./apidocs/index.html" opens non-framed version. In any case, module name won't be in any of them.

Would this be acceptable or should I look for other solution? Thanks!

[lukasj]

javadoc was refreshed to match latest binary