Small fixes and improvements to the reference documentation #29694
Conversation
The link would be named "Compared to WebFlux", which is easy to mix up with the various links to equivalent sections in the WebFlux chapter. Here the links point to a small section comparing the Servlet Async API to the WebFlux stack from a high perspective. In this commit we eliminate most of these links, except at the beginning of the Asynchronous section. We also add a small mention of the Servlet configuration in the comparison paragraphs, as Configuring section is the one furthest from the comparison paragraphs that used to have a link to it.
The block title style previously used was not rendered in HTML and the title wouldn't be differentiated from the text. It was in the PDF, as italics. Introducing delimited blocks in the open (`--`) style did introduce styling, but the vertical alignment isn't great. This commit turns these block titles to actual (deep) section titles. In the final HTML, at this depth there is no numbering but bold styling is there. The PDF rendering has also be verified to have relevant style.
|
|
||
| This library is freely available on the web -- for example, in Maven Central as | ||
| `com.sun.mail:jakarta.mail`. Please make sure to use the latest 1.6.x version | ||
| rather than Jakarta Mail 2.0 (which comes with a different package namespace). | ||
| See the `v1.x` code in the https://github.com/jakartaee/mail-api/tree/v1.x[Jakarta Mail-Api repository]. |
There was a problem hiding this comment.
Unless I'm missing something, this whole section is wrong regarding the versions.
We currently compile against jakarta.mail:jakarta.mail-api:2.0.1 for our e-mail support (pulling in dependencies on things like jakarta.mail.Message). So users of Spring Framework 6.0 must use Jakarta Mail 2.0+.
There was a problem hiding this comment.
eh, I made this change on the basis that the 1.6.x mention was correct, primarily because the link was 404. perhaps this needs to be evaluated / reworked separately then ? (with a specific backport to 5.3.x that looks like the edits I made)
There was a problem hiding this comment.
I've pushed a commit that removes that github link. So the content referring 1.6 is still probably wrong, but at least the Jakarta Mail link is fixed.
There was a problem hiding this comment.
I made this change on the basis that the 1.6.x mention was correct,
Yes, I assumed that was the case. This is all coming from the 5.3.x version of the docs and was just an oversight (that it hasn't yet been updated in the 6.0.x docs).
I didn't mean to imply that you made an error with the versions. Rather, I just happened to notice it, because you modified that section. 😉
perhaps this needs to be evaluated / reworked separately then ? (with a specific backport to 5.3.x that looks like the edits I made)
Yes. 👍
Would you like to handle that? If not, I can take care of it.
There was a problem hiding this comment.
Actually, I'll just go ahead and address that.
The link was previously named "Compared to WebFlux", which is easy to mix up with the various links to equivalent sections in the WebFlux chapter. Here the links point to a small section comparing the Servlet Async API to the WebFlux stack from a high perspective. In this commit we eliminate most of these links, except at the beginning of the Asynchronous section. We also add a small mention of the Servlet configuration in the comparison paragraphs, since the Configuring section is the one furthest from the comparison paragraphs that used to have a link to it. Closes spring-projectsgh-29694
The block title style previously used was not rendered in HTML and the title couldn't be differentiated from the text. Though, it was in the PDF, as italics. Introducing delimited blocks in the open (`--`) style did introduce styling, but the vertical alignment isn't great. This commit turns these block titles to actual (deep) section titles. In the final HTML, at this depth there is no numbering but bold styling is there. The PDF rendering has also been verified to have relevant style. Closes spring-projectsgh-29694
|
This work has been merged into Thanks |
This PR fixes a few obvious typos and small issues in the reference documentation:
It makes 2 larger changes to improve cross-linking consistency between the MVC and WebFlux chapters:
The PR has been split into meaningful commits for ease of review, but these can be squashed upon merging.