It's quite flexible. I'll have to use it as soon as we agree with the tests that were moved into the doc folder.
Vlad On Wed, Jan 13, 2016 at 5:07 PM, Gunnar Morling <gun...@hibernate.org> wrote: > 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
