Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactor the Appendix section in the reference documentation [SPR-16045] #20594

Closed
spring-issuemaster opened this issue Oct 4, 2017 · 1 comment

Comments

Projects
None yet
2 participants
@spring-issuemaster
Copy link
Collaborator

commented Oct 4, 2017

Rossen Stoyanchev opened SPR-16045 and commented

The Appendix used to have links to What's New and the Migration guides on the Wiki. Lots of people couldn't find it there -- it's not a very logical to check. Those are now removed from the Appendix and are instead mentioned on the index page. They're important enough and What's new used to be the start of the reference.

From the remaining content, some needs to be trimmed like the classic ORM and AOP usage.

The XML schema configuration could move to the "Core Container" section, at the bottom. Arguably, in this new section-based structure, it would be more useful there, as a local Appendix of sorts. It does not alone justify having a top-level Appendix section.

The form tags reference is of marginal value. The API docs already lists all Tag classes and methods. We could make sure the API docs have the same amount of information (even including HTML tables in class level Javadoc) and then simply refer to the Javadoc form the reference without bloating the size of the content.


Affects: 5.0 GA

Issue Links:

  • #20593 Top-level "Language Support" reference section

Referenced from: commits e5a5677, eea8ee2

@spring-issuemaster

This comment has been minimized.

Copy link
Collaborator Author

commented Oct 5, 2017

Rossen Stoyanchev commented

XML schema information from the top-level Appendix is now broken up and distributed into a local appendix in each of the Core Container, Data Access, and Integration sections respectively. This follows the more recent pattern to bring such information closer to the source. For example the MVC namespace was never in the top-level appendix but rather side by side with the MVC Java config in the Web section.

Spring JSP tag library and Spring Form tag library reference information has been migrated to Javadoc. At the package level there is a listing of all tags. At the class level, each tag includes the same information including an HTML table with all attributes. In other words no loss of information but rather a consolidation so there is a single source. In many cases as it turns out the Javadoc had a better and more class-level information about each tag while the reference had a better summary by attribute.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.