groovy-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pa...@apache.org
Subject [2/3] groovy git commit: improve doco for @ToString
Date Sat, 03 Feb 2018 11:55:51 GMT
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 <paulk@asert.com.au>
Authored: Sat Feb 3 19:56:19 2018 +1000
Committer: paulk <paulk@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[]


Mime
View raw message