Class annotation used to assist in the creation of toString() methods in classes. The @ToString annotation instructs the compiler to execute an AST transformation which adds the necessary toString() method.

It allows you to write classes in this shortened form:

@ToString
class Customer {
    String first, last
    int age
    Date since = new Date()
    Collection favItems
    private answer = 42
}
println new Customer(first:'Tom', last:'Jones', age:21, favItems:['Books', 'Games'])

Which will have this output:

Customer(Tom, Jones, 21, Wed Jul 14 23:57:14 EST 2010, [Books, Games])

There are numerous options to customize the format of the generated output. E.g. if you change the first annotation to:

@ToString(includeNames=true)

Then the output will be:

Customer(first:Tom, last:Jones, age:21, since:Wed Jul 14 23:57:50 EST 2010, favItems:[Books, Games])

Or if you change the first annotation to:

@ToString(includeNames=true,includeFields=true,excludes="since,favItems")

Then the output will be:

Customer(first:Tom, last:Jones, age:21, answer:42)

If you have this example:

import groovy.transform.ToString
@ToString class NamedThing {
    String name
}
@ToString(includeNames=true,includeSuper=true)
class AgedThing extends NamedThing {
    int age
}
String agedThingAsString = new AgedThing(name:'Lassie', age:5).toString()
assert agedThingAsString == 'AgedThing(age:5, super:NamedThing(Lassie))'

@ToString can also be used in conjunction with @Canonical and @Immutable.

If you want to omit fields or properties referring to null, you can use the ignoreNulls flag:

import groovy.transform.ToString
@ToString(ignoreNulls = true) class NamedThing {
    String name
}
assert new NamedThing(name: null).toString() == 'NamedThing()'

By default the fully-qualified class name is used as part of the generated toString. If you want to exclude the package, you can set the includePackage flag to false, e.g.:

package my.company
import groovy.transform.ToString
@ToString(includePackage = false) class NamedThing {
    String name
}
println new NamedThing(name: "Lassie")

Which results in:

NamedThing(name: Lassie)

If the includePackage flag is true (the default), then the output will be:

my.company.NamedThing(name: Lassie)

More examples:

//--------------------------------------------------------------------------    
// Most simple implementation of toString.
import groovy.transform.ToString

@ToString
class Person {
    String name
    List likes
    private boolean active = false
}

def person = new Person(name: 'mrhaki', likes: ['Groovy', 'Java'])

assert person.toString() == 'Person(mrhaki, [Groovy, Java])'

//--------------------------------------------------------------------------    
// includeNames to output the names of the properties.
import groovy.transform.ToString

@ToString(includeNames=true)
class Person {
    String name
    List likes
    private boolean active = false
}

def person = new Person(name: 'mrhaki', likes: ['Groovy', 'Java'])

assert person.toString() == 'Person(name:mrhaki, likes:[Groovy, Java])'

//--------------------------------------------------------------------------
// includeFields to not only output properties, but also field values.
import groovy.transform.ToString

@ToString(includeNames=true, includeFields=true)
class Person {
    String name
    List likes
    private boolean active = false
}

def person = new Person(name: 'mrhaki', likes: ['Groovy', 'Java'])

assert person.toString() == 'Person(name:mrhaki, likes:[Groovy, Java], active:false)'

//--------------------------------------------------------------------------    
// Use includeSuper to include properties from super class in output.
import groovy.transform.ToString

@ToString(includeNames=true)
class Person {
    String name
    List likes
    private boolean active = false
}

@ToString(includeSuper=true, includeNames=true)
class Student extends Person {
    List courses
}

def student = new Student(name: 'mrhaki', likes: ['Groovy', 'Java'], courses: ['IT', 'Business'])

assert student.toString() == 'Student(courses:[IT, Business], super:Person(name:mrhaki, likes:[Groovy, Java]))'

//--------------------------------------------------------------------------    
// excludes active field and likes property from output
import groovy.transform.ToString

@ToString(includeNames=true, includeFields=true, excludes='active,likes')
class Person {
    String name
    List likes
    private boolean active = false
}

def person = new Person(name: 'mrhaki', likes: ['Groovy', 'Java'])

assert person.toString() == 'Person(name:mrhaki)'

//--------------------------------------------------------------------------
// Don't include the package name in the output
package com.mrhaki.blog.groovy

import groovy.transform.*

@ToString(includePackage=false)
class Course {
    String title
    Integer maxAttendees
}

final Course course = new Course(title: 'Groovy 101', maxAttendees: 200)

assert course.toString() == 'Course(Groovy 101, 200)'

//--------------------------------------------------------------------------
// Don't use properties with null value.
package com.mrhaki.blog.groovy

import groovy.transform.*

@ToString(ignoreNulls=true)
class Course {
    String title
    Integer maxAttendees
}

final Course course = new Course(title: 'Groovy 101')

assert course.toString() == 'com.mrhaki.blog.groovy.Course(Groovy 101)'

//--------------------------------------------------------------------------
// Cache toString() result.
package com.mrhaki.blog.groovy

import groovy.transform.*

@ToString(cache=true)
class Course {
    String title
    Integer maxAttendees
}

Course course = new Course(title: 'Groovy 101', maxAttendees: 200)

assert course.toString() == 'com.mrhaki.blog.groovy.Course(Groovy 101, 200)'

// Value change will not be reflected in toString().
course.title = 'Grails with REST'

assert course.toString() == 'com.mrhaki.blog.groovy.Course(Groovy 101, 200)'
assert course.title == 'Grails with REST'