improve doco for @ToString
Project: http://git-wip-us.apache.org/repos/asf/groovy/repo Commit: http://git-wip-us.apache.org/repos/asf/groovy/commit/e2429364 Tree: http://git-wip-us.apache.org/repos/asf/groovy/tree/e2429364 Diff: http://git-wip-us.apache.org/repos/asf/groovy/diff/e2429364 Branch: refs/heads/GROOVY_2_5_X Commit: e24293644456451e917a0d63fc33a54ca9d03a9f Parents: afeec6a Author: paulk <pa...@asert.com.au> Authored: Sat Feb 3 19:56:19 2018 +1000 Committer: paulk <pa...@asert.com.au> Committed: Sat Feb 3 21:55:35 2018 +1000 ---------------------------------------------------------------------- src/main/groovy/groovy/transform/ToString.java | 7 ++++++- .../groovy/transform/TupleConstructor.java | 2 +- src/spec/doc/core-metaprogramming.adoc | 21 ++++++++++++-------- .../test/CodeGenerationASTTransformsTest.groovy | 20 +++++++++++++++++++ 4 files changed, 40 insertions(+), 10 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/groovy/blob/e2429364/src/main/groovy/groovy/transform/ToString.java ---------------------------------------------------------------------- diff --git a/src/main/groovy/groovy/transform/ToString.java b/src/main/groovy/groovy/transform/ToString.java index 49930d2..4807924 100644 --- a/src/main/groovy/groovy/transform/ToString.java +++ b/src/main/groovy/groovy/transform/ToString.java @@ -268,7 +268,8 @@ public @interface ToString { String[] excludes() default {}; /** - * List of field and/or property names to include within the generated toString. + * List of field and/or property names to include within the generated toString. The order of inclusion + * is determined by the order in which the names are specified. * Must not be used if 'excludes' is used. For convenience, a String with comma separated names * can be used in addition to an array (using Groovy's literal list notation) of String values. * The default value is a special marker value indicating that no includes are defined; all fields and/or properties @@ -305,6 +306,8 @@ public @interface ToString { * Include super fields in the generated toString. * Groovy properties, JavaBean properties and fields (in that order) from superclasses come after * the members from a subclass (unless 'includes' is used to determine the order). + * + * @since 2.5.0 */ boolean includeSuperFields() default false; @@ -316,6 +319,7 @@ public @interface ToString { /** * Whether to include the fully-qualified class name (i.e. including * the package) or just the simple class name in the generated toString. + * * @since 2.0.6 */ boolean includePackage() default true; @@ -337,6 +341,7 @@ public @interface ToString { /** * Whether to cache toString() calculations. You should only set this to true if * you know the object is immutable (or technically mutable but never changed). + * * @since 2.1.0 */ boolean cache() default false; http://git-wip-us.apache.org/repos/asf/groovy/blob/e2429364/src/main/groovy/groovy/transform/TupleConstructor.java ---------------------------------------------------------------------- diff --git a/src/main/groovy/groovy/transform/TupleConstructor.java b/src/main/groovy/groovy/transform/TupleConstructor.java index d43f18b..f330fdd 100644 --- a/src/main/groovy/groovy/transform/TupleConstructor.java +++ b/src/main/groovy/groovy/transform/TupleConstructor.java @@ -216,7 +216,7 @@ public @interface TupleConstructor { boolean includeSuperProperties() default false; /** - * Include fields from super classes in the constructor. + * Include visible fields from super classes in the constructor. * Groovy properties, JavaBean properties and fields (in that order) from superclasses come before * the members from a subclass (unless 'includes' is used to determine the order). */ http://git-wip-us.apache.org/repos/asf/groovy/blob/e2429364/src/spec/doc/core-metaprogramming.adoc ---------------------------------------------------------------------- diff --git a/src/spec/doc/core-metaprogramming.adoc b/src/spec/doc/core-metaprogramming.adoc index ec27f18..cd1cd00 100644 --- a/src/spec/doc/core-metaprogramming.adoc +++ b/src/spec/doc/core-metaprogramming.adoc @@ -783,11 +783,6 @@ The `@ToString` annotation accepts several parameters which are summarized in th [cols="1,1,2,3a",options="header"] |======================================================================= |Attribute|Default value|Description|Example -|includeNames|false|Whether to include names of properties in generated toString.| -[source,groovy] ----- -include::{projectdir}/src/spec/test/CodeGenerationASTTransformsTest.groovy[tags=tostring_example_includeNames,indent=0] ----- |excludes|Empty list|List of properties to exclude from toString| [source,groovy] ---- @@ -803,16 +798,26 @@ include::{projectdir}/src/spec/test/CodeGenerationASTTransformsTest.groovy[tags= ---- include::{projectdir}/src/spec/test/CodeGenerationASTTransformsTest.groovy[tags=tostring_example_includeSuper,indent=0] ---- -|includeSuperProperties|False|Should super properties be included in toString| +|includeNames|false|Whether to include names of properties in generated toString.| [source,groovy] ---- -include::{projectdir}/src/spec/test/CodeGenerationASTTransformsTest.groovy[tags=tostring_example_includeSuperProperties,indent=0] +include::{projectdir}/src/spec/test/CodeGenerationASTTransformsTest.groovy[tags=tostring_example_includeNames,indent=0] ---- |includeFields|False|Should fields be included in toString, in addition to properties| [source,groovy] ---- include::{projectdir}/src/spec/test/CodeGenerationASTTransformsTest.groovy[tags=tostring_example_includeFields,indent=0] ---- +|includeSuperProperties|False|Should super properties be included in toString| +[source,groovy] +---- +include::{projectdir}/src/spec/test/CodeGenerationASTTransformsTest.groovy[tags=tostring_example_includeSuperProperties,indent=0] +---- +|includeSuperFields|False|Should visible super fields be included in toString| +[source,groovy] +---- +include::{projectdir}/src/spec/test/CodeGenerationASTTransformsTest.groovy[tags=tostring_example_includeSuperFields,indent=0] +---- |ignoreNulls|False|Should properties/fields with null value be displayed| [source,groovy] ---- @@ -823,7 +828,7 @@ include::{projectdir}/src/spec/test/CodeGenerationASTTransformsTest.groovy[tags= ---- include::{projectdir}/src/spec/test/CodeGenerationASTTransformsTest.groovy[tags=tostring_example_includePackage,indent=0] ---- -|allPropeties|True|Include all JavaBean properties in toString| +|allProperties|True|Include all JavaBean properties in toString| [source,groovy] ---- include::{projectdir}/src/spec/test/CodeGenerationASTTransformsTest.groovy[tags=tostring_example_allProperties,indent=0] http://git-wip-us.apache.org/repos/asf/groovy/blob/e2429364/src/spec/test/CodeGenerationASTTransformsTest.groovy ---------------------------------------------------------------------- diff --git a/src/spec/test/CodeGenerationASTTransformsTest.groovy b/src/spec/test/CodeGenerationASTTransformsTest.groovy index 85af1d5..90c941e 100644 --- a/src/spec/test/CodeGenerationASTTransformsTest.groovy +++ b/src/spec/test/CodeGenerationASTTransformsTest.groovy @@ -149,6 +149,26 @@ assert bono.toString() == 'BandMember(bandName:U2, name:Bono)' ''' assertScript ''' +import groovy.transform.* + +// tag::tostring_example_includeSuperFields[] +class Person { + protected String name +} + +@ToString(includeSuperFields = true, includeNames = true) +@MapConstructor(includeSuperFields = true) +class BandMember extends Person { + String bandName +} + +def bono = new BandMember(name:'Bono', bandName: 'U2').toString() + +assert bono.toString() == 'BandMember(bandName:U2, name:Bono)' +// end::tostring_example_includeSuperFields[] +''' + + assertScript ''' import groovy.transform.ToString // tag::tostring_example_ignoreNulls[]
