Merge pull request #4188 from jamezp/docs-update

[RESTEASY-3066] Follow-up fixes for the documentation conversion to a…

docbook/src/main/asciidoc/Cache_NoCache_CacheControl.adoc

@@ -5,7 +5,7 @@ RESTEasy provides numerous annotations and facilities to support HTTP caching se
 Annotations to make setting Cache-Control headers easier and both server-side and client-side in-memory caches are available. 
 
 [[_cache_annotation]]
-== @Cache and @NoCache Annotations
+=== @Cache and @NoCache Annotations
 
 RESTEasy provides an extension to {spec-name} that allows you to automatically set Cache-Control headers on a successful GET request.
 It can only be used on @GET annotated methods.

docbook/src/main/asciidoc/Content_Marshalling_Providers.adoc

@@ -1,6 +1,6 @@
 == Content Marshalling/Providers
 
-=== Default Providers and default {jakarta-rest-spec} Content Marshalling
+=== Default Providers and default {spec-name} Content Marshalling
 
 RESTEasy can automatically marshal and unmarshal a few different message bodies. 
 

docbook/src/main/asciidoc/I18N.adoc

@@ -105,7 +105,7 @@ These IDs belong to the following ranges:
 |===
 
 For example, the {xml-binding} provider contains the interface
-`[class]org.jboss.resteasy.plugins.providers.jaxb.i18.Messages`
+`org.jboss.resteasy.plugins.providers.jaxb.i18.Messages`
 which looks like 
 
 [source,java]

docbook/src/main/asciidoc/Installation_Configuration.adoc

@@ -27,7 +27,10 @@ Here's an example:
 </jboss-deployment-structure>
 ----
 
-The 'services` attribute must be set to "import" for modules that have default providers in a META-INF/services/jakarta.ws.rs.ext.Providers file. 
+The 'services` attribute must be set to "import" for modules that have default providers in a
+`META-INF/services/jakarta.ws.rs.ext.Providers` file.
+
+IMPORTANT: Using the `META-INF/services/jakarta.ws.rs.ext.Providers` is RESTEasy specific and not considered portable.
 
 To get an idea of which RESTEasy modules are loaded by default when  services are deployed, please see the table below, which refers to a recent WildFly ditribution patched with the current RESTEasy distribution.
 Clearly, future and unpatched WildFly distributions might differ a bit in terms of modules enabled by default, as the container actually controls this too.
@@ -166,6 +169,8 @@ RESTEasy is bundled with WildFly and completely integrated as per the requiremen
 application can contain {enterprise-beans} and CDI. WildFly scans the WAR file for the {spec-name} services and
 provider classes packaged in the WAR either as POJOs, CDI beans, or {enterprise-beans}.
 
+The web.xml can supply to RESTEasy init-params and context-params (see <<_configuration_switches>>) if you want to tweak or turn on/off any specific RESTEasy feature.
+
 [source,xml]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
@@ -176,8 +181,6 @@ provider classes packaged in the WAR either as POJOs, CDI beans, or {enterprise-
 </web-app>
 ----
 
-The web.xml can supply to RESTEasy init-params and context-params (see <<_configuration_switches>>) if you want to tweak or turn on/off any specific RESTEasy feature.
-
 When a servlet-mapping element is not declared in the web.xml, then a class must be provided that implements `jakarta.ws.rs.core.Application` class (see <<_jakarta.ws.rs.core.application>>). This class must be annotated with the `jakarta.ws.rs.ApplicationPath` annotation.
 If this implementation class returns an empty set for classes and singletons, the WAR will be scanned for resource and provider classes as indicated by the presence of {spec-name} annotations.
 
@@ -234,9 +237,10 @@ Unzip the file. The resulting directory will contain a lib/ directory that conta
 Copy these, as needed, into your /WEB-INF/lib directory.
 Place your {spec-name} annotated class resources and providers within one or more jars within /WEB-INF/lib or your raw class files within /WEB-INF/classes.
 
-==== Servlet 3.0 containers
+==== Servlet Containers
 
-RESTEasy provides an implementation of the Servlet 3.0 'servletContainerInitializer` integration interface for containers to use in initializing an application.
+RESTEasy provides an implementation of the Servlet `ServletContainerInitializer` integration interface for
+containers to use in initializing an application.
 The container calls this interface during the application's startup phase.
 The RESTEasy implementation performs automatic scanning for resources and providers, and programmatic registration of a servlet.
 RESTEasy's implementation is provided in maven artifact, `resteasy-servlet-initializer`.
@@ -253,7 +257,8 @@ Add this artifact dependency to your project's pom.xml file so the JAR file will
 
 ==== Defining the Servlet in a web.xml
 
-You can manually declare the RESTEasy servlet in the WEB-INF/web.xml file of your WAR project, and provide an `Application` class (see <<_jakarta.ws.rs.core.application>>).
+You can manually declare the RESTEasy servlet in the `WEB-INF/web.xml` file of your WAR project, and provide an
+`Application` class (see <<_jakarta.ws.rs.core.application>>).
 For example: 
 
 [source,xml]
@@ -288,7 +293,7 @@ The RESTEasy servlet is responsible for initializing some basic components of RE
 Initialization of RESTEasy can be performed within a 'servletContextListener` instead of within the Servlet.
 You may need this if you are writing custom Listeners that need to interact with RESTEasy at boot time.
 An example of this is the RESTEasy Spring integration that requires a Spring ServletContextListener.
-The `org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap` class is a 'servletContextListener` that configures an
+The `org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap` class is a `ServletContextListener` that configures an
 instance of an `ResteasyProviderFactory` and Registry. You can obtain instances of a `ResteasyProviderFactory` and
 Registry from the 'servletContext` attributes `org.jboss.resteasy.spi.ResteasyProviderFactory` and
 `org.jboss.resteasy.spi.Registry`. From these instances you can programmatically interact with RESTEasy registration

docbook/src/main/asciidoc/Jakarta_REST_Content_Negotiation.adoc

@@ -88,7 +88,7 @@ Request is injected via `@Context`.
 Read the javadoc for more info on these. 
 
 [[_media_mappings]]
-== URL-based negotiation
+=== URL-based negotiation
 
 Some clients, like browsers, cannot use the Accept and Accept-Language headers to negotiation the representation's media type or language.
 RESTEasy allows the mapping of file name suffixes like (.xml, .txt, .en, .fr) to media types and languages.
@@ -127,7 +127,7 @@ Accept-Language: en-US
 The mapped file suffixes are stripped from the target URL path before the request is dispatched to a corresponding {spec-name} resource.
 
 [[_param_media_mappings]]
-== Query String Parameter-based negotiation
+=== Query String Parameter-based negotiation
 
 RESTEasy can do content negotiation based in a parameter in the query string.
 To enable this, the parameter `resteasy.media.type.param.mapping` should be configured in the web.xml file.

docbook/src/main/asciidoc/MicroProfile_Rest_Client.adoc

@@ -138,7 +138,7 @@ Naturally, the registered providers should be relevant to the client environment
 [NOTE]
 ====
 So far, the MicroProfile Rest Client should look familiar to anyone who has used the RESTEasy client proxy facility
-(<<_client_proxies,Section ""RESTEasy Proxy Framework">>). The construction in  the previous listing would look like
+(<<_client_proxies,Section "RESTEasy Proxy Framework">>). The construction in  the previous listing would look like
 
 [source,java]
 ----
@@ -176,11 +176,11 @@ These are
 * JSON-P `MessageBodyReader` and `MessageBodyWriter` must be provided.
 * JSON-B `MessageBodyReader` and `MessageBodyWriter` must be provided if the implementation supports JSON-B.
 * `MessageBodyReader` and `MessageBodyWriter`  must be provided for the following types:
-** byte[]
-** String
-** InputStream
-** Reader
-** File
+** `byte[]`
+** `String`
+** `InputStream`
+** `Reader`
+** `File`
 
 
 === Beyond {spec-name} and RESTEasy

docbook/src/main/asciidoc/Overview.adoc

@@ -1,27 +1,42 @@
 == Overview
 
+NOTE: This version, {resteasy-version}, of RESTEasy supports {jakarta-rest-spec}[{spec-name} {jakarta-rest-version},window=_blank].
+
 Originally released in 2009, RESTEasy has tracked and implemented a series of official specifications that provide a Java API for RESTful Web Services over the HTTP protocol: 
 
-[cols="1,1", frame="topbot", options="header"]
+[cols="1,1,1", frame="topbot", options="header"]
 |===
 | RESTEasy version
 | Specification
-
+| JavaDoc/Changes
 
 |6.1+
-|https://jakarta.ee/specifications/restful-ws/3.1/jakarta-restful-ws-spec-3.1.html[Jakarta RESTful Web Services 3.1]
+|https://jakarta.ee/specifications/restful-ws/3.1/jakarta-restful-ws-spec-3.1.html[Jakarta RESTful Web Services 3.1,window=_blank]
+a|
+
+* https://jakarta.ee/specifications/restful-ws/3.1/apidocs/[JavaDoc,window=_blank]
+* https://jakarta.ee/specifications/restful-ws/3.1/jakarta-restful-ws-spec-3.1.html#changes-since-3.0-release[Changes,window=_blank]
 
 |6.0
-|https://jakarta.ee/specifications/restful-ws/3.0/jakarta-restful-ws-spec-3.0.html[Jakarta RESTful Web Services 3.0]
+|https://jakarta.ee/specifications/restful-ws/3.0/jakarta-restful-ws-spec-3.0.html[Jakarta RESTful Web Services 3.0,window=_blank]
+a|
+
+* https://jakarta.ee/specifications/restful-ws/3.0/apidocs/[JavaDoc,window=_blank]
+* https://jakarta.ee/specifications/restful-ws/3.0/jakarta-restful-ws-spec-3.0.html#changes-since-2.1-release[Changes,window=_blank]
 
 |3.5+
-|https://jakarta.ee/specifications/restful-ws/2.1/restful-ws-spec-2.1.html[Jakarta RESTful Web Services 2.1]
+|https://jakarta.ee/specifications/restful-ws/2.1/restful-ws-spec-2.1.html[Jakarta RESTful Web Services 2.1,window=_blank]
+a|
+
+* https://jakarta.ee/specifications/restful-ws/2.1/apidocs/[JavaDoc,window=_blank]
 
 |3+
-|https://jcp.org/en/jsr/detail?id=339[JAX-RS 2.0]
+|https://jcp.org/en/jsr/detail?id=339[JAX-RS 2.0,window=_blank]
+|
 
 |2+
-|https://download.oracle.com/otndocs/jcp/jaxrs-1.0-fr-eval-oth-JSpec/[JAX-RS 1.0]
+|https://download.oracle.com/otndocs/jcp/jaxrs-1.0-fr-eval-oth-JSpec/[JAX-RS 1.0,window=_blank]
+|
 |===
 
 JAX-RS 1.0 (https://download.oracle.com/otndocs/jcp/jaxrs-1.0-fr-eval-oth-JSpec/[JSR-311]), JAX-RS 2.0 (https://jcp.org/en/jsr/detail?id=339[JSR-339]), and JAX-RS 2.1 (https://jcp.org/en/jsr/detail?id=370[JSR-370]) are https://jcp.org/en/procedures/overview[Java Community Process (JCP)] specifications.

docbook/src/main/asciidoc/RESTEasy_Client_Framework.adoc

@@ -427,9 +427,8 @@ In this scenario, just have the {spec-name} services implement an annotated inte
 
 [WARNING]
 ====
-WARNING: The Apache HTTP Client support is deprecated in RESTEasy.
-The exposed API's will eventually be removed.
-However, it's still the default client implementation as we prepare for a replacement backing HTTP client. 
+The Apache HTTP Client support is deprecated in RESTEasy. The exposed API's will eventually be removed. However, it's
+still the default client implementation as we prepare for a replacement backing HTTP client.
 ====
 
 Network communication between the client and server is handled by default in RESTEasy.

docbook/src/main/asciidoc/_Context.adoc

@@ -1,6 +1,11 @@
 [[_context]]
 == @Context
 
+WARNING: Support for `@Context` inject has been
+https://jakarta.ee/specifications/restful-ws/3.1/jakarta-restful-ws-spec-3.1.html#context-injection[deprecated,window=_blank].
+RESTEasy supports using the `@Inject` annotation on instance variables. Support for method and constructor injection
+will be available in a future release.
+
 The `@Context` annotation allows the injection of instances of the following types:
 
 * `jakarta.ws.rs.core.HttpHeaders`

docbook/src/main/asciidoc/_HeaderParam.adoc

@@ -33,7 +33,7 @@ public void put(@HeaderParam("Content-Type") MediaType contentType);
 
 
 
-== [class]``HeaderDelegate``s
+=== Header Delegates
 
 In addition to the usual methods for translating parameters to and from strings, parameters annotated with
 `@HeaderParam` have another option: implementations of {jakarta-rest-javadoc}/jakarta/ws/rs/ext/runtimedelegate.headerdelegate[`RuntimeDelegate$HeaderDelegate`].

docbook/src/main/asciidoc/xml-binding.adoc

@@ -1,8 +1,9 @@
 [[_built_in_xml_bind_providers]]
 == {xml-binding} providers
 
-NOTE: In {spec-name} 3.1 the {xml-binding} support was deprecated.
-RESTEasy still plans on supporting {xml-binding}.
+CAUTION: In {spec-name} 4.0 the {xml-binding} support was removed from specification. RESTEasy still plans on supporting
+{xml-binding} for the time being. This may not be supported in a future release. Please plan on migrating to
+<<_json_p,JSON>> or some other supported data type.
 
 As required by the specification, RESTEasy includes support for (un)marshalling {xml-binding} annotated classes.
 RESTEasy provides multiple providers to address some subtle differences between classes generated by XJC and classes which are simply annotated with @XmlRootElement, or working with JAXBElement classes directly.