You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
While analyzing the claim in #29998, I became aware of our current settings for chomp and fold for spring-asciidoctor-backends in the reference documentation.
Historically, we have maintained handcrafted code examples (in contrast to included snippets which we have recently introduced for AOT examples), sometimes with explicit package and import statements in order to assist the user in understanding the examples. For example, the CommonPointcuts class explicitly declares its package com.xyz.myapp to make it clear in subsequent examples where shared pointcuts are derived from (e.g., com.xyz.myapp.CommonPointcuts.businessService()).
As far as I understand the feature set of spring-asciidoctor-backends, it is not possible to "un-chomp" (i.e., show) chompedpackage statements; whereas, it is possible to un-fold foldedimport statements (even if not readily apparent to the user).
However, for handcrafted examples that intentionally include package and import statements I think we should show those by default, especially since the user has no way to show the package statements that have been chomped.
On the other hand, if the package statement is irrelevant -- for example, when including code snippets from a real source file in the framework-docs project -- it then makes sense to chomppackage statements.
I am therefore creating this issue for the team to decide how to deal with chomping and folding defaults across the reference documentation, specifically with regard to handcrafted vs. included code snippets.
The text was updated successfully, but these errors were encountered:
sbrannen
changed the title
Reassess chomp and fold settings in reference documentation
Revise chomp and fold settings in reference documentation
Feb 22, 2023
While analyzing the claim in #29998, I became aware of our current settings for
chomp
andfold
for spring-asciidoctor-backends in the reference documentation.spring-framework/framework-docs/src/docs/asciidoc/attributes.adoc
Lines 1 to 2 in 8a44b64
Historically, we have maintained handcrafted code examples (in contrast to included snippets which we have recently introduced for AOT examples), sometimes with explicit
package
andimport
statements in order to assist the user in understanding the examples. For example, theCommonPointcuts
class explicitly declares its packagecom.xyz.myapp
to make it clear in subsequent examples where shared pointcuts are derived from (e.g.,com.xyz.myapp.CommonPointcuts.businessService()
).As far as I understand the feature set of
spring-asciidoctor-backends
, it is not possible to "un-chomp" (i.e., show) chompedpackage
statements; whereas, it is possible to un-fold foldedimport
statements (even if not readily apparent to the user).However, for handcrafted examples that intentionally include
package
andimport
statements I think we should show those by default, especially since the user has no way to show thepackage
statements that have been chomped.On the other hand, if the
package
statement is irrelevant -- for example, when including code snippets from a real source file in theframework-docs
project -- it then makes sense to chomppackage
statements.I am therefore creating this issue for the team to decide how to deal with chomping and folding defaults across the reference documentation, specifically with regard to handcrafted vs. included code snippets.
The text was updated successfully, but these errors were encountered: