From 298a815a49402d1eb790e7dc339e94bce96259a1 Mon Sep 17 00:00:00 2001
From: Sarah Haggarty <sarahhaggarty@users.noreply.github.com>
Date: Wed, 26 Jul 2023 11:30:18 +0100
Subject: [PATCH] update: revised introduction to data classes

---
 docs/topics/data-classes.md | 29 +++++++++++++++--------------
 1 file changed, 15 insertions(+), 14 deletions(-)

diff --git a/docs/topics/data-classes.md b/docs/topics/data-classes.md
index b4f45dd87c0..e4333efd152 100644
--- a/docs/topics/data-classes.md
+++ b/docs/topics/data-classes.md
@@ -1,8 +1,8 @@
 [//]: # (title: Data classes)
 
-It is not unusual to create classes whose main purpose is to hold data.
-In such classes, some standard functionality and some utility functions are often mechanically
-derivable from the data. In Kotlin, these are called _data classes_ and are marked with `data`:
+Data classes in Kotlin are classes whose main purpose is to hold data. Data classes come automatically with additional
+member functions that allow you to print an instance to readable output, compare instances, copy instances, and more.
+Data classes are marked with `data`:
 
 ```kotlin
 data class User(val name: String, val age: Int)
@@ -10,10 +10,10 @@ data class User(val name: String, val age: Int)
 
 The compiler automatically derives the following members from all properties declared in the primary constructor:
 
-* `equals()`/`hashCode()` pair
-* `toString()` of the form `"User(name=John, age=42)"`
-* [`componentN()` functions](destructuring-declarations.md) corresponding to the properties in their order of declaration.
-* `copy()` function (see below).
+* `.equals()`/`.hashCode()` pair
+* `.toString()` of the form `"User(name=John, age=42)"`
+* [`.componentN()` functions](destructuring-declarations.md) corresponding to the properties in their order of declaration.
+* `.copy()` function (see below).
 
 To ensure consistency and meaningful behavior of the generated code, data classes have to fulfill the following requirements:
 
@@ -53,10 +53,10 @@ data class Person(val name: String) {
 }
 ```
 
-In this example, only the `name` property can be used inside the `toString()`, `equals()`, `hashCode()`, and `copy()` implementations,
-and there is only be one component function `component1()`. The `age` property can't be used inside the `toString()`, 
-`equals()`, `hashCode()`, and `copy()` implementations because it's declared inside the class body. If two `Person` 
-objects have different ages but the same `name`, then they are treated as equal. This is because the `equals()` function
+In this example, only the `name` property can be used inside the `.toString()`, `.equals()`, `.hashCode()`, and `.copy()` implementations,
+and there is only one component function `.component1()`. The `age` property can't be used inside the `.toString()`, 
+`.equals()`, `.hashCode()`, and `.copy()` implementations because it's declared inside the class body. If two `Person` 
+objects have different ages but the same `name`, then they are treated as equal. This is because the `.equals()` function
 can only check for equality of the `name` property. For example:
 
 ```kotlin
@@ -85,7 +85,7 @@ fun main() {
 
 ## Copying
 
-Use the `copy()` function to copy an object, allowing you to alter _some_ of its properties while keeping the rest unchanged. The implementation of this function for the `User` class above would be as follows:
+Use the `.copy()` function to copy an object, allowing you to alter _some_ of its properties while keeping the rest unchanged. The implementation of this function for the `User` class above would be as follows:
 
 ```kotlin
 fun copy(name: String = this.name, age: Int = this.age) = User(name, age)
@@ -105,11 +105,12 @@ _Component functions_ generated for data classes make it possible to use them in
 ```kotlin
 val jane = User("Jane", 35)
 val (name, age) = jane
-println("$name, $age years of age") // prints "Jane, 35 years of age"
+println("$name, $age years of age") 
+// Jane, 35 years of age
 ```
 
 ## Standard data classes
 
 The standard library provides the `Pair` and `Triple` classes. In most cases, though, named data classes are a better design choice
-because they make the code more readable by providing meaningful names for the properties.
+because they make the code easier to read by providing meaningful names for the properties.