In the section Introduction under subsection Variables it would be very helpful if you showed an example where read-only variable refers to mutable object such as list with an explanation that variable itself is immutable, but object it refers to is mutable.

Because later in the subsection Generics there is this code:

class MutableStack<E>(vararg items: E) {

  private val elements = items.toMutableList()

  fun push(element: E) = elements.add(element)

  ...
}

This part was very unclear to me, it didn't quite get how can you add items to variable elements if the variable is immutable. Until I read at this source the following:

Also, while the read-only variable may not be reassigned while it is in scope, it can still refer to an object which is in itself mutable (such as a list).

That's why I think it would be very useful if you added explanation about immutable variables referring to mutable objects in the section Variables.

I was reading the examples in the page and I noticed there's now way to change the theme of the page, having it would be pretty sweet and give eyes a break :P Maybe i'm being to dramatic but is there a way to get this implemented ?.

https://play.kotlinlang.org/byExample/01_introduction/06_Generics

fun <E> mutableStackOf(vararg elements: E) = MutableStack(*elements)

fun main() {
  val stack = mutableStackOf(0.62, 3.14, 2.7)
  println(stack)
}

```Note that the compiler can infer the generic type from the parameters of mutableStackOf so that you don't have to write mutableStackOf<**Int**>(...).

-> shouldn't that be mutableStackOf<**Float**>(...) in this scenario?

https://github.com/akrmfathy80/kotlin-by-example/blob/master/.github/workflows/verify-samples.yml

https://github.com/akrmfathy80

https://github.com/Kotlin/kotlin-by-example/blob/master/examples/04_functional/02_Lambdas.md

So many syntaxes are shown together but not really explained in detail...

Running the HTML Builder example code in the https://play.kotlinlang.org/byExample/09_Kotlin_JS/06_HtmlBuilder page produces the expected result while displaying deprecation warnings next to several lines (please refer to the screenshot below).

Attempt to run the code in Kotlin Playground fails with errors (please refer to the screenshot below).

The Type Sage Builders reference doc mentioned at the bottom of the page contains a different implementation that [after minor adaptations] runs successfully in Kotlin Playground.

It seems beneficial to align HTML Builder example with with Type Safe Builders reference doc and make it executable in Kotlin Playground.

The example for "let" has "customPrint" which is never defined nor mentioned; only used. This is confusing for readers.

On page: https://play.kotlinlang.org/byExample/08_productivity_boosters/04_Smart%20Casts
This is what I see:

Notice how the items (1 and 2) are no in a separate line like they are in the markdown page:

I am on Windows 10 pro using Firefox 74.0.1

Originally posted by @Markisha1997 in #220 (comment)

Kotlin native is not the most beginner friendly tool out there at the moment. Maybe a suggestion for chapter 10 can be focused on some examples with full projects (Including buildscripts, def files, etc)? Multiple files? Maybe that might be undoable, but I think we should try.

Examples can be for all three platforms (Mingw, MacOs, and Linux)?

We can also add some examples for WebAssembly, and Swift porting?
This can be a great way for people to learn how to use libraries and such with Kotlin Native, and such a project allows us to cover many different kinds of projects.

Of course, we don't have to focus on the building part of things, we can also focus on creating examples for memory management, etc.

Am I doing something wrong?
Examples in docs and default code in sandbox at https://play.kotlinlang.org/ throw an exception

Exception in thread "main" java.io.FileNotFoundException: /var/task/tmp/5123f1e03e204326b652cc46776a48ba/executor.policy (No such file or directory)
at java.io.FileOutputStream.open0 (FileOutputStream.java:-2)
at java.io.FileOutputStream.open (FileOutputStream.java:270)
at java.io.FileOutputStream. (FileOutputStream.java:213)

Target platform: JVM
Running on kotlin v.1.5.31

Found this accidentally when trying to execute basic code in playground

This code

CanvasState(canvas).apply {
    addShape(Kotlin)
    addShape(Creature(size * 0.25, this))
    addShape(Creature(size * 0.75, this))
}

returns the following errors when run on the page:

Using 'jq(Element): JQuery' is an error. Use declarations from 'https://bintray.com/kotlin/js-externals/kotlin-js-jquery' package instead.
Using 'jq(Element): JQuery' is an error. Use declarations from 'https://bintray.com/kotlin/js-externals/kotlin-js-jquery' package instead.
Using 'jq(Element): JQuery' is an error. Use declarations from 'https://bintray.com/kotlin/js-externals/kotlin-js-jquery' package instead.
Using 'jq(Element): JQuery' is an error. Use declarations from 'https://bintray.com/kotlin/js-externals/kotlin-js-jquery' package instead.
Using 'MouseEvent' is an error. Use declarations from 'https://bintray.com/kotlin/js-externals/kotlin-js-jquery' package instead.

Tested on

• Chrome Version 85.0.4183.121 (Official Build) (64-bit), on Windows 7 x64 pro
• Microsoft Edge Version 85.0.564.63 (Official build) (64-bit), same platform

Background

I'm brand new to Kotlin and working through Kotlin by Example. I've noticed that each topic is organised into a structure similar to the following:

package org.kotlinlang.play         // 1

fun main() {                        // 2
    println("Hello, World!")        // 3
}

1. Kotlin code is usually defined in packages. Package specification is optional: If you don't specify a package in a source file, its content goes to the default package.
2. An entry point to a Kotlin application is the main function. In Kotlin 1.3, you can declare main without any parameters. The return type is not specified, which means that the function returns nothing.
3. println writes a line to the standard output. It is imported implicitly. Also note that semicolons are optional.

Problem

Personally, I find this difficult to follow. For each line of code, I need to:

1. Read the line of code
2. Memorise the reference number at the end of the line
3. Skip down the page to the reference notes
4. Find the reference note with the memorised reference number
5. Read the reference note
6. Skip back up the page to the code
7. Find the line of code I was last at

By the time I finish the topic, I have skipped up and down the page several times.

Solution

Inline the reference notes into the code:

// Kotlin code is usually defined in packages.
// Package specification is optional: If you don't specify a package in a source file,
// its content goes to the default package.
package org.kotlinlang.play

// An entry point to a Kotlin application is the main function.
// In Kotlin 1.3, you can declare main without any parameters.
// The return type is not specified, which means that the function returns nothing.
fun main() {
    // println() writes a line to the standard output.
    // It is imported implicitly. Also note that semicolons are optional.
    println("Hello, World!")
}

Benefits

Now, instead of having to keep skipping down and up the page, I can just follow it from top to bottom. So for each line of code, I need to:

1. Read the comment
2. Read the line of code

I find this significantly easier to follow than the way it's currently done.

Alternative solution

If you don't like the look of detailed notes inside code comments, then you could interleave the notes with the code:

Kotlin code is usually defined in packages. Package specification is optional: If you don't specify a package in a source file, its content goes to the default package.

package org.kotlinlang.play

An entry point to a Kotlin application is the main function. In Kotlin 1.3, you can declare main without any parameters. The return type is not specified, which means that the function returns nothing.

fun main() {

println writes a line to the standard output. It is imported implicitly. Also note that semicolons are optional.

    println("Hello, World!")
}

This way is a bit nicer to read, but now it's hard to copy and run the full code block since it's split up, so I'm not sure if it's worth it.

Pull request

I'm happy to make the changes myself and submit a pull request.

In my opinion, projects like this should be detected and recognized with the programming language they are based on, and not with the file extension used (.md). So, in my opinion, should be added a .gitattributes to force GitHub to consider it a Kotlin project.

A generic .gitattributes could be:
*.* linguist-language=Kotlin

My two cents

Null Safety
In an effort to rid the world of NullPointerException, variable types in Kotlin don't allow the assignment of null. If you need a variable that can be null, declare it nullable by adding ? at the end of its type.

fun main() {
//sampleStart
var neverNull: String = "This can't be null" // 1

neverNull = null                                        // 2

var nullable: String? = "You can keep a null here"      // 3

nullable = null                                         // 4

var inferredNonNull = "The compiler assumes non-null"   // 5

inferredNonNull = null                                  // 6

fun strLength(notNull: String): Int {                   // 7
    return notNull.length
}

It should be this in documentation :
println(strLength(neverNull)); // 8
println(strLength(nullable)); // 9

instead of this:
strLength(neverNull) // 8
strLength(nullable) // 9
//sampleEnd
}

i have already created the pull request for this.