You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@groovy.apache.org by pa...@apache.org on 2018/02/03 09:56:29 UTC
groovy git commit: improve doco for @ToString
Repository: groovy
Updated Branches:
refs/heads/master 7f7acff71 -> f0d663f3d
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/f0d663f3
Tree: http://git-wip-us.apache.org/repos/asf/groovy/tree/f0d663f3
Diff: http://git-wip-us.apache.org/repos/asf/groovy/diff/f0d663f3
Branch: refs/heads/master
Commit: f0d663f3db9b390cccf8c13b11ab5a0edc20ff4c
Parents: 7f7acff
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 19:56:19 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/f0d663f3/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 979d333..9a9335f 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/f0d663f3/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/f0d663f3/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/f0d663f3/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[]