Right; you also can use the same tag several times if you want several distinct snippets from a file to end up in one listing in the docs: https://github.com/hibernate/hibernate-validator/blob/master/documentation/src/test/java/org/hibernate/validator/referenceguide/chapter11/failfast/Car.java .
The usage in the docs is like so: https://github.com/hibernate/hibernate-validator/blame/master/documentation/src/main/asciidoc/ch11.asciidoc#L206..L213 . I am very happy with this in general, the only (minor) downside is that it naturally adds a bit of build time for compiling/testing the source. But I think it's well spent and of course one can skip it for quick docs rendering during authoring. 2016-01-13 15:57 GMT+01:00 Vlad Mihalcea <mihalcea.v...@gmail.com>: > This is how you mark an anchor in the source code: > > > //tag::constraintMapping[]HibernateValidatorConfiguration configuration = > Validation .byProvider( HibernateValidator.class ) > .configure(); > ConstraintMapping constraintMapping = > configuration.createConstraintMapping(); > constraintMapping .type( Car.class ) .property( "manufacturer", > FIELD ) .constraint( new NotNullDef() ) .property( > "licensePlate", FIELD ) .ignoreAnnotations() > .constraint( new NotNullDef() ) .constraint( new > SizeDef().min( 2 ).max( 14 ) ) .type( RentalCar.class ) > .property( "rentalStation", METHOD ) .constraint( new > NotNullDef() ); > Validator validator = configuration.addMapping( constraintMapping ) > .buildValidatorFactory() .getValidator(); > > //end::constraintMapping[] > > The start/end comments allow to describe what goes in a snippet. > Now that's another reason for having the tests in the documentation folder. > > Vlad > > > On Wed, Jan 13, 2016 at 4:52 PM, Steve Ebersole <st...@hibernate.org> > wrote: > >> Gunnar, that's very awesome. You mention being able to include snippets >> of an actual source file. Do you have pointers to an explanation of the >> snippets/portion part of that? >> >> On Wed, Jan 13, 2016 at 8:47 AM Gunnar Morling <gun...@hibernate.org> >> wrote: >> >>> Hey Vlad, >>> >>> slightly related and just in case you are not aware of this feature >>> yet: You can include (parts of) actual source code files straight into >>> AsciiDoc documents. We do that in the HV reference guide, e.g. at [1]. >>> That way you are 100% sure your examples actually compile (and pass >>> tests) and you don't need to copy & paste them. >>> >>> Cheers, >>> >>> --Gunnar >>> >>> [1] >>> https://raw.githubusercontent.com/hibernate/hibernate-validator/master/documentation/src/main/asciidoc/ch11.asciidoc >>> >>> >>> 2016-01-13 15:30 GMT+01:00 Vlad Mihalcea <mihalcea.v...@gmail.com>: >>> > Hi Steve, >>> > >>> > The User Guide illustrations are snippets of code that go into the >>> extras >>> > folder, which stays right next to every chapter. >>> > That's in the main folder. >>> > >>> > The tests are now located in the test folder of the documentation >>> folder, so >>> > that we can update/evolve them in future. >>> > They are also a proof that the code snippets work. >>> > There was a time when I realized that an example was not really ok, >>> and I >>> > had to change that. >>> > I change the test first to see how it worked, and only then I updated >>> the >>> > Guide. >>> > They are also a form of regression testing, so that we are alerted if >>> some >>> > future change will break the expectations we made while writing the >>> > documentation code snippets. >>> > >>> > The reader can fork the repo and try them, if he wishes. >>> > >>> > Vlad >>> > >>> > On Wed, Jan 13, 2016 at 4:12 PM, Steve Ebersole <st...@hibernate.org> >>> wrote: >>> >> >>> >> Vlad, I see you created a PR for moving your new tests out of >>> >> hibernate-entitymanager into documentation. I guess that depends on >>> the >>> >> intent. Are they meant as illustrations? And if so, how are you >>> >> expecting >>> >> people will see them? And if they are meant as real tests rather >>> than as >>> >> illustrations, I think moving them is not appropriate. >>> >> >>> >> On Tue, Jan 12, 2016 at 4:57 AM andrea boriero <drebor...@gmail.com> >>> >> wrote: >>> >> >>> >> > I'm not against the use of Java 8 letting AnimalSniffer guarding for >>> >> > compatibility, >>> >> > but I understand this can cause some problems so I'm ok with >>> removing >>> >> > Java >>> >> > 8 usage from tests. >>> >> > >>> >> > On 12 January 2016 at 10:07, Gunnar Morling <gun...@hibernate.org> >>> >> > wrote: >>> >> > >>> >> > > @Vlad, what Java 8 syntax specifically are you using in the user >>> guide >>> >> > > tests (examples?)? >>> >> > > >>> >> > > I like the idea of using a current syntax in usage examples, to >>> give >>> >> > > the guide a current look and show that our APIs play well with >>> current >>> >> > > Java versions (while staying compatible with older ones). >>> >> > > >>> >> > > >>> >> > > >>> >> > > 2016-01-12 10:51 GMT+01:00 Sanne Grinovero <sa...@hibernate.org>: >>> >> > > > +1 for Vlad's proposal to use the same JDK for tests and main >>> code >>> >> > > > in >>> >> > > > a given module. >>> >> > > > >>> >> > > > Infinispan requires Java8 at runtime too, so that module should >>> be >>> >> > > > the >>> >> > > > only one to use Java8? >>> >> > > > >>> >> > > > On 12 January 2016 at 07:55, Vlad Mihalcea < >>> mihalcea.v...@gmail.com> >>> >> > > wrote: >>> >> > > >> I used Java 8 syntax in the User Guide tests as I remembered >>> that >>> >> > tests >>> >> > > can >>> >> > > >> use it, but I also agree that this is a rather strange move. >>> >> > > >> Since we need to support Java 1.6, maybe it's a better idea to >>> use >>> >> > > >> the >>> >> > > >> latest JDK just in the modules where we have no other choice. >>> >> > > >> For testing, I think that 1.6 is just fine and I could easily >>> >> > > >> change >>> >> > > those >>> >> > > >> tests to remove the 1.8 dependency. >>> >> > > >> >>> >> > > >> So I vote for using the same JDK for both main and test in a >>> >> > particular >>> >> > > >> module. >>> >> > > >> >>> >> > > >> Vlad >>> >> > > >> >>> >> > > >> On Mon, Jan 11, 2016 at 11:35 PM, Steve Ebersole >>> >> > > >> <st...@hibernate.org >>> >> > > >>> >> > > >> wrote: >>> >> > > >> >>> >> > > >>> The former. People commit things that already assume the >>> move to >>> >> > Java >>> >> > > 8 >>> >> > > >>> locally to build (and test). But at the moment we have not >>> >> > formalized >>> >> > > >>> that, and so that causes problems when we import into an IDE >>> - the >>> >> > > imported >>> >> > > >>> IDE project is built for 1.6 compliance and so everything we >>> try >>> >> > > >>> in >>> >> > > the IDE >>> >> > > >>> fails. >>> >> > > >>> >>> >> > > >>> On Mon, Jan 11, 2016 at 3:33 PM Gunnar Morling >>> >> > > >>> <gun...@hibernate.org >>> >> > > >>> >> > > >>> wrote: >>> >> > > >>> >>> >> > > >>> > Hey, >>> >> > > >>> > >>> >> > > >>> > > or we move to Java 8 and rely on >>> >> > > >>> > > AnimalSniffer to make sure we are still compatible. >>> >> > > >>> > >>> >> > > >>> > WDYM by "move to Java8" exactly? Requiring it at Hibernate's >>> >> > > >>> > build >>> >> > > >>> > time, or also at runtime in user apps? >>> >> > > >>> > >>> >> > > >>> > >>> >> > > >>> > 2016-01-11 19:49 GMT+01:00 Steve Ebersole < >>> st...@hibernate.org>: >>> >> > > >>> > > The use of Java 8 features in Hibernate ORM is starting to >>> >> > expand. >>> >> > > >>> > Luckily >>> >> > > >>> > > it is still constrained to just tests. >>> >> > > >>> > > >>> >> > > >>> > > However these usages make development in an IDE more and >>> more >>> >> > > >>> difficult. >>> >> > > >>> > > Previously this was isolated to hibernate-infinispan. >>> Now[1] >>> >> > this >>> >> > > has >>> >> > > >>> > > crept into hibernate-entitymanager. We need to have a >>> plan >>> >> > > >>> > > here. >>> >> > > >>> Either >>> >> > > >>> > > we stop using Java 8 anywhere, or we move to Java 8 and >>> rely >>> >> > > >>> > > on >>> >> > > >>> > > AnimalSniffer to make sure we are still compatible. >>> >> > > >>> > > >>> >> > > >>> > > Votes? Other options? >>> >> > > >>> > > >>> >> > > >>> > > [1] >>> >> > > >>> > > >>> >> > > >>> > >>> >> > > >>> >>> >> > > >>> >> > >>> >> > >>> https://github.com/hibernate/hibernate-orm/commit/c2ece0108ed52d5e3a227ed0150cfb5cb1a76101 >>> >> > > >>> > > _______________________________________________ >>> >> > > >>> > > hibernate-dev mailing list >>> >> > > >>> > > hibernate-dev@lists.jboss.org >>> >> > > >>> > > https://lists.jboss.org/mailman/listinfo/hibernate-dev >>> >> > > >>> > >>> >> > > >>> _______________________________________________ >>> >> > > >>> hibernate-dev mailing list >>> >> > > >>> hibernate-dev@lists.jboss.org >>> >> > > >>> https://lists.jboss.org/mailman/listinfo/hibernate-dev >>> >> > > >>> >>> >> > > >> _______________________________________________ >>> >> > > >> hibernate-dev mailing list >>> >> > > >> hibernate-dev@lists.jboss.org >>> >> > > >> https://lists.jboss.org/mailman/listinfo/hibernate-dev >>> >> > > > _______________________________________________ >>> >> > > > hibernate-dev mailing list >>> >> > > > hibernate-dev@lists.jboss.org >>> >> > > > https://lists.jboss.org/mailman/listinfo/hibernate-dev >>> >> > > _______________________________________________ >>> >> > > hibernate-dev mailing list >>> >> > > hibernate-dev@lists.jboss.org >>> >> > > https://lists.jboss.org/mailman/listinfo/hibernate-dev >>> >> > > >>> >> > _______________________________________________ >>> >> > hibernate-dev mailing list >>> >> > hibernate-dev@lists.jboss.org >>> >> > https://lists.jboss.org/mailman/listinfo/hibernate-dev >>> >> > >>> >> _______________________________________________ >>> >> hibernate-dev mailing list >>> >> hibernate-dev@lists.jboss.org >>> >> https://lists.jboss.org/mailman/listinfo/hibernate-dev >>> > >>> > >>> >> > _______________________________________________ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
