update: improve Classes page #4786

AlejandraPedroza · 2025-04-02T14:13:02Z

This PR revamps the content and code examples in the Classes page following external feedback.
Some of the key changes are:

Improve the whole page and revamp the code snippets.
Explain the use case for multiple init blocks.
Explain constructor chaining.
Add examples for primary constructors.
Clarify the open keyword.
Explain how to access a class property from a class member function.
Use the term "object" consistently.
Clarify what abstract classes are.
Provide example companion objects.

ice-phoenix

My main question is: what are the things we want the reader to know, after they've finished reading the updated "Classes" page? Is it basic syntax for classes, details about constructors, details about initialization, smth else? Right now the section is a bit all over the place, I feel.

In other words, when we set to improve the page, what did we want to achieve?

ice-phoenix · 2025-04-07T16:15:24Z

docs/topics/classes.md

-and some other things), and the class body surrounded by curly braces. Both the header and the body are optional; if the
-class has no body, the curly braces can be omitted.
+The class declaration consists of: 
+* **Class header**, including:


Is it "including" or "including but not limited to"? Because class header also includes, for example, supertype list.

ice-phoenix · 2025-04-07T16:16:16Z

docs/topics/classes.md


 ```kotlin
-class Person constructor(firstName: String) { /*...*/ }
+// Class with only a name and no body
+class Person


I think a better example would be a class with a primary constructor and some properties, but no body

ice-phoenix · 2025-04-07T16:17:35Z

docs/topics/classes.md

-If the primary constructor does not have any annotations or visibility modifiers, the `constructor` keyword can be omitted:
+## Constructors and initializer blocks
+
+A class in Kotlin has a [_primary constructor_](#primary-constructor) and, optionally, one or more [_secondary constructors_](#secondary-constructors). 


Before we correctly said primary ctor is optional. Here I'm reading as if it is mandatory. I would suggest trying to find a better phrasing for the idea "primary ctor is optional, but we believe in most cases your classes should have one".

ice-phoenix · 2025-04-07T16:26:39Z

docs/topics/classes.md

+}
+```
+
+See classes in action. Considering the same code example, if you [create an object](#creating-objects-of-classes) of the `Person` class by passing values for


"See classes in action"?

ice-phoenix · 2025-04-07T16:29:26Z

docs/topics/classes.md

+) { /*...*/ }
+```
+
+Using the trailing comma example, if you [create an object](#creating-objects-of-classes) of the `Person`


I do not fully get what we say via "using the trailing comma example" here

ice-phoenix · 2025-04-07T17:02:32Z

docs/topics/classes.md

-> Kotlin does not have a `new` keyword.
->
-{style="note"}
+Typically, you create objects within the `main()` function because it serves as the entry point of your Kotlin program. 


This statement is not true, you create objects whenever you need to do that, and not only within the main function

ice-phoenix · 2025-04-07T17:27:32Z

docs/topics/classes.md

+You don't need to annotate abstract classes or functions with the `open` keyword because they are implicitly 
+open and designed to be inherited. 
+
+Similarly, you can override a non-abstract `open` member with an abstract one:


Tbh, I do not think this example adds anything useful for one reading the documentation. Such pattern of overriding open with abstract is very strange and should not be used unless there are very specific circumstances.

ice-phoenix · 2025-04-07T17:28:59Z

docs/topics/classes.md


-You can override a non-abstract `open` member with an abstract one.
+## Open keyword


I would say this section makes more sense in the Inheritance part of the documentation

ice-phoenix · 2025-04-07T17:32:14Z

docs/topics/classes.md


-Even more specifically, if you declare a [companion object](object-declarations.md#companion-objects) inside your class,
+If you need to write a function that can be called without having a class object but still needs access 
+to the internals of the class, you can define it inside `companion object` within that class:


How do you define "internals of the class" here? A companion object can access its own internals, but class itself does not have any internals until you have created an instance of it.

Also, here the terminology begins being a bit confusing, as "class object" and "companion object" look very similar, but mean significantly different things

How do you define "internals of the class" here?

This comes in the current version of the docs and I didn't modify it, but I rephrased it. What do you think?

ice-phoenix · 2025-04-07T17:43:55Z

docs/topics/classes.md

@@ -1,245 +1,747 @@
 [//]: # (title: Classes)

-Classes in Kotlin are declared using the keyword `class`:
+Like other object-oriented languages, Kotlin uses _classes_ to encapsulate data and behavior 
+for reusable, structured code.


I'm missing a short intro talking about different "parts" of a class, similar to what you have in one of the later sections. Smth like "Classes encapsulate data (properties) and behavior (functions). They are templates for objects, which you create via constructors."

I would also prefer to see a very simple example in the beginning of "class -> ctor -> created object instance" which we then iteratively expand on, by adding more properties, functions, ctors, init blocks or other things.

AlejandraPedroza requested a review from a team as a code owner April 2, 2025 14:13

AlejandraPedroza requested a review from ice-phoenix April 2, 2025 14:13

AlejandraPedroza force-pushed the update-classes-page branch from b4d1916 to 85c4e7f Compare April 7, 2025 08:54

ice-phoenix requested changes Apr 7, 2025

View reviewed changes

AlejandraPedroza force-pushed the update-classes-page branch from 82db250 to 9fb5f07 Compare April 14, 2025 13:09

AlejandraPedroza added 3 commits April 23, 2025 14:37

update: improve Classes page

60f2760

chore: fix anchors

c85a7ff

Marat review

3871cf7

AlejandraPedroza force-pushed the update-classes-page branch from 3ce95e1 to 3871cf7 Compare April 23, 2025 12:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

update: improve Classes page #4786

update: improve Classes page #4786

AlejandraPedroza commented Apr 2, 2025 •

edited

Loading

ice-phoenix left a comment

ice-phoenix Apr 7, 2025

ice-phoenix Apr 7, 2025

ice-phoenix Apr 7, 2025

ice-phoenix Apr 7, 2025

ice-phoenix Apr 7, 2025

ice-phoenix Apr 7, 2025

ice-phoenix Apr 7, 2025

ice-phoenix Apr 7, 2025

ice-phoenix Apr 7, 2025

ice-phoenix Apr 7, 2025

AlejandraPedroza Apr 16, 2025 •

edited

Loading

ice-phoenix Apr 7, 2025

ice-phoenix Apr 7, 2025


		You can override a non-abstract `open` member with an abstract one.
		## Open keyword

update: improve Classes page #4786

Are you sure you want to change the base?

update: improve Classes page #4786

Conversation

AlejandraPedroza commented Apr 2, 2025 • edited Loading

ice-phoenix left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AlejandraPedroza Apr 16, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AlejandraPedroza commented Apr 2, 2025 •

edited

Loading

AlejandraPedroza Apr 16, 2025 •

edited

Loading