add section for getters and setters (#6830)

Added a section for getters and setters.

Fixes #5477

Preview:

https://dart-dev--pr6830-getters-setters-bcxd3yuk.web.app/language/functions#getters-and-setters

---

- [x] I’ve reviewed the contributor guide and applied the relevant
portions to this PR.
- [x] This PR doesn't contain automatically generated corrections or
text (Grammarly, LLMs, and similar).
- [x] This PR follows the [Google Developer Documentation Style
Guidelines](https://developers.google.com/style) — for example, it
doesn't use _i.e._ or _e.g._, and it avoids _I_ and _we_ (first person).
- [x] This PR uses [semantic line
breaks](https://github.com/dart-lang/site-shared/blob/main/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks)
of 80 characters or fewer.

<details>
  <summary>Contribution guidelines:</summary><br>

- See our [contributor
guide](https://github.com/dart-lang/site-www/blob/main/CONTRIBUTING.md)
for general expectations for PRs.
- Larger or significant changes should be discussed in an issue before
creating a PR.
- Code changes should generally follow the [Dart style
guide](https://dart.dev/effective-dart) and use `dart format`.
- Updates to [code
excerpts](https://github.com/dart-lang/site-shared/blob/main/packages/excerpter)
indicated by `<?code-excerpt` need to be updated in their source `.dart`
file as well.
</details>

---------

Co-authored-by: Parker Lougheed <[email protected]>

Author: conooi

examples/language/lib/functions/getters_setters.dart

@@ -0,0 +1,44 @@
+// Defines a variable `_secret` that is private to the library since
+// its identifier starts with an underscore (`_`).
+String _secret = 'Hello';
+
+// A public top-level getter that
+// provides read access to [_secret].
+String get secret {
+  print('Getter was used!');
+  return _secret.toUpperCase();
+}
+
+// A public top-level setter that
+// provides write access to [_secret].
+set secret(String newMessage) {
+  print('Setter was used!');
+  if (newMessage.isNotEmpty) {
+    _secret = newMessage;
+    print('New secret: "$newMessage"');
+  }
+}
+
+void main() {
+  // Reading the value calls the getter.
+  print('Current message: $secret');
+
+  /*
+  Output:
+  Getter was used!
+  Current message: HELLO
+  */
+
+  // Assigning a value calls the setter.
+  secret = 'Dart is fun';
+
+  // Reading it again calls the getter to show the new computed value
+  print('New message: $secret');
+
+  /*
+  Output:
+  Setter was used! New secret: "Dart is fun"
+  Getter was used!
+  New message: DART IS FUN
+  */
+}

pubspec.yaml

@@ -9,3 +9,4 @@ workspace:
   - examples
   - site
   - tool/dash_site
+

src/content/language/functions.md

@@ -1,7 +1,7 @@
 ---
 title: Functions
 description: Everything about functions in Dart.
-js: [{url: '/assets/js/inject_dartpad.js', defer: true}]
+js: [{ url: "/assets/js/inject_dartpad.js", defer: true }]
 prevpage:
   url: /language/error-handling
   title: Error handling
@@ -62,8 +62,8 @@ that indicates whether the `atomicNumber` falls into the noble gas range.
 
 ## Parameters
 
-A function can have any number of *required positional* parameters. These can be
-followed either by *named* parameters or by *optional positional* parameters
+A function can have any number of _required positional_ parameters. These can be
+followed either by _named_ parameters or by _optional positional_ parameters
 (but not both).
 
 :::note
@@ -75,7 +75,6 @@ details.
 You can use [trailing commas][] when you pass arguments to a function
 or when you define function parameters.
 
-
 ### Named parameters
 
 Named parameters are optional
@@ -97,9 +96,9 @@ void enableFlags({bool? bold, bool? hidden}) {
 }
 ```
 
-When calling a function, 
+When calling a function,
 you can specify named arguments using
-<code><em>paramName</em>: <em>value</em></code>. 
+<code><em>paramName</em>: <em>value</em></code>.
 For example:
 
 <?code-excerpt "misc/lib/language_tour/functions.dart (use-named-parameters)"?>
@@ -144,6 +143,7 @@ A parameter marked as `required` can still be nullable:
 ```dart
 const Scrollbar({super.key, required [!Widget?!] child});
 ```
+
 :::
 
 You might want to place positional arguments first,
@@ -274,7 +274,7 @@ More about those in the next section.
 
 ## Function types
 
-You can specify the type of a function, which is known as a *function type*.
+You can specify the type of a function, which is known as a _function type_.
 A function type is obtained from a function declaration header by
 replacing the function name by the keyword `Function`.
 Moreover, you are allowed to omit the names of positional parameters, but
@@ -309,8 +309,8 @@ These functions are called _anonymous functions_, _lambdas_, or _closures_.
 
 An anonymous function resembles a named function as it has:
 
-* Zero or more parameters, comma-separated
-* Optional type annotations between parentheses.
+- Zero or more parameters, comma-separated
+- Optional type annotations between parentheses.
 
 The following code block contains the function's body:
 
@@ -511,7 +511,6 @@ void main() {
 }
 ```
 
-
 ## Return values
 
 All functions return a value. If no return value is specified, the
@@ -534,14 +533,92 @@ To return multiple values in a function, aggregate the values in a [record][].
 
 [record]: /language/records#multiple-returns
 
+## Getters and setters
+
+Every property access (top-level, static, or instance) is an invocation
+of a getter or a setter. A variable implicitly creates a getter
+and, if it's mutable, a setter. This is why when you access a property,
+you're actually calling a small function in the background. Reading a
+property calls a getter function, and writing one calls a setter function,
+even in cases where the property is declared a variable.
+
+However, you can also declare getters and setters explicitly with
+the `get` and `set` keywords respectively.
+This allows a property's value to be computed when it's read or written.
+
+The purpose of using getters and setters is to create a clear
+separation between the client (the code that uses the property) and
+the provider (the class or library that defines it). The client asks for or
+sets a value without needing to know if that value is stored in a
+simple variable or calculated on the spot. This gives the provider
+the freedom to change how the property works.
+
+For example, because the value of the property might not be stored anywhere,
+it could be computed each time the getter is called. Another example
+is that when a value is stored in a private variable, and public access
+is only allowed by calling a getter or a setter.
+
+The following example showcases this,
+with the `secret` getter and setter providing
+indirect access to the private variable `_secret` with
+its own manipulations on the assigned and retrieved values.
+
+<?code-excerpt "language/lib/functions/getters_setters.dart"?>
+```dart highlightLines=3,7-10,14-20,24,33
+// Defines a variable `_secret` that is private to the library since
+// its identifier starts with an underscore (`_`).
+String _secret = 'Hello';
+
+// A public top-level getter that
+// provides read access to [_secret].
+String get secret {
+  print('Getter was used!');
+  return _secret.toUpperCase();
+}
+
+// A public top-level setter that
+// provides write access to [_secret].
+set secret(String newMessage) {
+  print('Setter was used!');
+  if (newMessage.isNotEmpty) {
+    _secret = newMessage;
+    print('New secret: "$newMessage"');
+  }
+}
+
+void main() {
+  // Reading the value calls the getter.
+  print('Current message: $secret');
+
+  /*
+  Output:
+  Getter was used!
+  Current message: HELLO
+  */
+
+  // Assigning a value calls the setter.
+  secret = 'Dart is fun';
+
+  // Reading it again calls the getter to show the new computed value
+  print('New message: $secret');
+
+  /*
+  Output:
+  Setter was used! New secret: "Dart is fun"
+  Getter was used!
+  New message: DART IS FUN
+  */
+}
+```
+
 ## Generators
 
 When you need to lazily produce a sequence of values,
 consider using a _generator function_.
 Dart has built-in support for two kinds of generator functions:
 
-* **Synchronous** generator: Returns an [`Iterable`] object.
-* **Asynchronous** generator: Returns a [`Stream`] object.
+- **Synchronous** generator: Returns an [`Iterable`] object.
+- **Asynchronous** generator: Returns a [`Stream`] object.
 
 To implement a **synchronous** generator function,
 mark the function body as `sync*`,
@@ -580,7 +657,6 @@ Iterable<int> naturalsDownFrom(int n) sync* {
 }
 ```
 
-
 [`Iterable`]: {{site.dart-api}}/dart-core/Iterable-class.html
 [`Stream`]: {{site.dart-api}}/dart-async/Stream-class.html
 
@@ -601,22 +677,22 @@ heavily platform specific, so check out the interop docs on, for example,
 [C][] or [JavaScript][] to learn more.
 
 External functions can be top-level functions, [instance methods][],
-[getters or setters][], or [non-redirecting constructors][].
+getters or setters, or [non-redirecting constructors][].
 An [instance variable][] can be `external` too,
 which is equivalent to an external getter and (if the variable
 is not `final`) an external setter.
 
 [instance methods]: /language/methods#instance-methods
-[getters or setters]: /language/methods#getters-and-setters
 [non-redirecting constructors]: /language/constructors#redirecting-constructors
 [instance variable]: /language/classes#instance-variables
 [C]: /interop/c-interop
 [JavaScript]: /interop/js-interop
-
 [Function API reference]: {{site.dart-api}}/dart-core/Function-class.html
 [Callable objects]: /language/callable-objects
 [type annotations for public APIs]: /effective-dart/design#do-type-annotate-fields-and-top-level-variables-if-the-type-isnt-obvious
 [if statement]: /language/branches#if
 [conditional expression]: /language/operators#conditional-expressions
 [Flutter]: {{site.flutter}}
 [trailing commas]: /language/collections#lists
+
+