Feature/doc (#7)

* feat: Changes documentation on data types and variables.

* feat: Changes documentation on loops, expressions and functions.

doc/readmes/roadmap/EXPRESSIONS.md

@@ -11,7 +11,6 @@ Em Kotlin, `if` é uma expressão, e ela retorna um valor. Portanto, não há op
 ordinário funciona bem nessa função:
 
 ```kotlin
-
 var value = 1
 val other = 5
 
@@ -21,7 +20,6 @@ if (2 < other) value = other
 Com else:
 
 ```kotlin
-
 val value = 1
 val other = 2
 
@@ -32,10 +30,11 @@ if (value >= other) {
 }
 ```
 
+_Você pode testar esse código [online](https://pl.kotl.in/oxoYfp-bN)._
+
 Uma expressão `if` podem ser usada em blocos. Neste caso, a última expressão é o valor de um bloco:
 
 ```kotlin
-
 val value = 1
 val other = 2
 
@@ -48,6 +47,8 @@ val max = if (value > other) {
 }
 ```
 
+_Você pode testar esse código [online](https://pl.kotl.in/AEc7dCRRh)._
+
 **Nota**
 > Se estiver usando `if` como expressão, por exemplo, para retornar seu valor ou atribuí-lo a uma variável, o `else` é
 > obrigatório.
@@ -62,7 +63,6 @@ em linguagens como o PHP. O `when` corresponde seu argumento a todas as ramifica
 condição de ramificação seja satisfeita:
 
 ```kotlin
-
 val value = 3
 
 when (value) {
@@ -72,6 +72,8 @@ when (value) {
 }
 ```
 
+_Você pode testar esse código [online](https://pl.kotl.in/EZYAVJQKf)._
+
 O `when` pode ser usado como uma expressão ou como uma instrução. Se for usado como uma expressão, o valor da primeira
 ramificação correspondente se tornará o valor da expressão geral. Se for usado como uma instrução, os valores de
 ramificações individuais serão ignorados. Assim como com if, cada ramificação pode ser um bloco e seu valor é o valor da

doc/readmes/roadmap/FUNCTIONS.md

@@ -35,7 +35,10 @@ ou usando argumentos nomeados:
 add(augend = 1, addend = 1)
 ```
 
-Usar argumentos nomeados pode ser útil quando uma função tem muitos argumentos e é difícil associar um valor a um
-argumento.
+_Você pode testar esse código [online](https://pl.kotl.in/fuB8CNime)._
+
+**Nota**
+> Usar argumentos nomeados pode ser útil quando uma função tem muitos argumentos e é difícil associar um valor a um
+> argumento.
 
 Ir para [variáveis](VARIABLES.md).

doc/readmes/roadmap/LOOPS.md

@@ -19,6 +19,8 @@ for (value in values) {
 }
 ```
 
+_Você pode testar esse código [online](https://pl.kotl.in/hEp_xK2X8)._
+
 <div id='while'></div> 
 
 ## While
@@ -31,22 +33,30 @@ eles é o tempo de verificação de condição.
 Verifica a condição e, se for satisfeita, executa o corpo e retorna à verificação de condição:
 
 ```kotlin
-val value = 0
+var value = 2
 
 while (value > 0) {
+    println(value)
     value--
 }
 ```
 
+_Você pode testar esse código [online](https://pl.kotl.in/8F5YNLU0W)._
+
 ### Do-while
 
 Executa o corpo, e, em seguida, verifica a condição. Se estiver satisfeito, o loop se repete. Assim, o corpo
 de `do-while` executa pelo menos uma vez, independentemente da condição:
 
 ```kotlin
+var value = 2
+
 do {
-    val value = null
-} while (value != null)
+    println(value)
+    value--
+} while (value > 0)
 ```
 
+_Você pode testar esse código [online](https://pl.kotl.in/jmbkQSwMF)._
+
 Ir para [classes e objetos](CLASS.md).

doc/readmes/roadmap/TYPES.md

@@ -1,16 +1,18 @@
 # Tipos de dados
 
-Em Kotlin, tudo é um objeto no sentido de que você pode chamar funções de membro e propriedades em qualquer variável.
+Em Kotlin, tudo é um objeto no sentido de que você pode chamar funções de membro, e propriedades em qualquer variável.
 
 * [Numbers](#numbers)
     - [Integers](#integers)
         - [Byte](#byte)
         - [Short](#short)
         - [Int](#int)
         - [Long](#long)
+        - [Funções auxiliares](#integers-functions)
     - [Floating](#floating)
         - [Float](#float)
         - [Double](#double)
+        - [Funções auxiliares](#floating-functions)
 * [Booleans](#booleans)
 * [Strings](#strings)
 * [Arrays](#arrays)
@@ -71,6 +73,24 @@ val two = 2L
 val threeBillion = 3000000000
 ```
 
+<div id='integers-functions'></div> 
+
+#### Funções auxiliares
+
+Cada tipo de número tem funções auxiliares que convertem de um tipo de número para outro:
+
+```kotlin
+val value: Int = 1234567
+
+fun main() {
+    println(value.toByte())  // Imprime "-121".
+    println(value.toLong())  // Imprime "1234567".
+    println(value.toShort()) // Imprime "-10617".
+}
+```
+
+_Você pode testar esse código [online](https://pl.kotl.in/ZNnMuVnMf)._
+
 **Nota**
 > Quando você inicializa uma variável sem especificação de tipo explícita, o compilador infere automaticamente o tipo
 > com o menor intervalo suficiente para representar o valor.
@@ -105,6 +125,22 @@ val one: Double = 1.0
 val withDecimal = 2.123456789
 ```
 
+<div id='floating-functions'></div> 
+
+#### Funções auxiliares
+
+Cada tipo de número tem funções auxiliares que convertem de um tipo de número para outro:
+
+```kotlin
+val value: Double = 9999.999
+
+fun main() {
+    println(value.toFloat()) // Imprime "9999.999".
+}
+```
+
+_Você pode testar esse código [online](https://pl.kotl.in/XcmN3AU3P)._
+
 ## Booleans
 
 <div id='booleans'></div> 
@@ -116,12 +152,34 @@ val isFull: Boolean = true
 val isEmpty: Boolean = false
 ```
 
+O tipo `Boolean` em Kotlin é o mesmo que em Java. As operações de disjunção `||`,
+conjunção `&&` e negação `!`, podem ser executadas em tipos booleanos, como em Java.
+
+```kotlin
+val one: Int = 1
+val two: Int = 2
+val three: Int = 3
+
+fun main() {
+    println(one < two)                // Imprime "true".
+    println(one > two)                // Imprime "false".
+    println(one <= two)               // Imprime "true".
+    println(one >= two)               // Imprime "false".
+    println(one == two)               // Imprime "false".
+    println(one != three)             // Imprime "true".
+    println(one < two && one < three) // Imprime "true".
+    println(one < two || one < three) // Imprime "true".
+}
+```
+
+_Você pode testar esse código [online](https://pl.kotl.in/Y-qzMlJwj)._
+
 <div id='strings'></div>
 
 ## Strings
 
 Em Kotlin as strings são representadas pelo tipo `String`. Geralmente, um valor de string é uma sequência de
-caracteres entre aspas duplas:
+caracteres entre aspas duplas ou aspas triplas:
 
 ```kotlin
 val name: String = "Kotlin"
@@ -135,20 +193,79 @@ original inalterada:
 ```kotlin
 val name = "Kotlin"
 
-println(name.uppercase()) // Cria e imprime um novo objeto String. O resultado ao imprimir é "KOTLIN".
-println(name)             // A string original permanece a mesma. O resultado ao imprimir é "Kotlin".
+fun main() {
+    println(name.uppercase()) // Cria e imprime um novo objeto String. Imprime "KOTLIN".
+    println(name)             // A string original permanece a mesma. Imprime "Kotlin".
+}
+```
+
+_Você pode testar esse código [online](https://pl.kotl.in/HzzvtZb2F)._
+
+Para criar uma sequêcia de caracteres que abrange várias linhas no arquivo de origem, nós usamos aspas triplas:
+
+```kotlin
+val json = """        
+    {
+        "id": "b87a002a-d2a9-4f31-8e95-271ea510b85f",
+        "amount": {
+            "value": "1.00",
+            "currency": "BRL"
+        }
+    }
+    """
+
+fun main() {
+    println(json)  // Imprime o json.
+}
+```
+
+_Você pode testar esse código [online](https://pl.kotl.in/x8dJfuIjs)._
+
+Kotlin também oferece suporte a interpolação de strings ou de string templates. Esta é uma maneira mais fácil de
+construir strings dinâmicas do que a concatenação, que é o que usamos em Java. Usando string templates, podemos
+inserir variáveis e expressões em uma string:
+
+```kotlin
+val kotlin = "Kotlin"
+val template = "$kotlin is a programming language."
+
+fun main() {
+    println(template)  // Imprime "Kotlin is a programming language.".
+}
+```
+
+Também é possível obter o mesmo resultado usando a função `format`:
+
+```kotlin
+val kotlin = "Kotlin"
+val template = "%s is a programming language."
+
+fun main() {
+    println(template.format(kotlin))  // Imprime "Kotlin is a programming language.".
+}
 ```
 
+_Você pode testar esse código [online](https://pl.kotl.in/GCWMkEuHf)._
+
 <div id='arrays'></div> 
 
 ## Arrays
 
 Em Kotlin os arrays são representadas pelo tipo `Array`. Para criar um array, use a função `arrayOf()`
-e passe os valores dos itens para ela.
+e passe os valores dos itens para ela:
 
 ```kotlin
 val names = arrayOf("Kotlin", "Java", "PHP")
 val values = arrayOf(1, 2, 3)
+val mixedValues = arrayOf(1, "Kotlin", true, 2.51)
+
+fun main() {
+    println(names.contentToString())       // Imprime "[Kotlin, Java, PHP]".
+    println(values.contentToString())      // Imprime "[1, 2, 3]".
+    println(mixedValues.contentToString()) // Imprime "[1, Kotlin, true, 2.51]".
+}
 ```
 
+_Você pode testar esse código [online](https://pl.kotl.in/RDK1wzTW4)._
+
 Ir para [loops](LOOPS.md).

doc/readmes/roadmap/VARIABLES.md

@@ -1,24 +1,66 @@
 # Variáveis
 
+* [Val](#val)
+* [Var](#var)
+* [Escopos](#scopes)
+
 Em Kotlin, as variáveis podem ser declaradas usando dois tipos de palavras-chave, `val` ou `var`.
 
+<div id='val'></div> 
+
 ## Val
 
-Quando você precisar de variáveis em um escopo local, e que a atribuição de valor seja feita uma única vez,
-então você utiliza a palavra-chave `val`:
+Quando você precisar de variáveis em que a atribuição de valor seja feita uma única vez, então você utiliza a
+palavra-chave `val`:
 
 ```kotlin
 val name: String = "kotlin"
 ```
 
-## Val
+<div id='var'></div> 
 
-Quando você precisar de variáveis em um escopo global, ou, que possam receber uma atribuição de valor mais de uma vez,
-então você utiliza a palavra-chave `var`:
+## Var
+
+Quando você precisar de variáveis que possam receber uma atribuição de valor mais de uma vez, então você utiliza a
+palavra-chave `var`:
 
 ```kotlin
 var name: String = "kotlin"
 name = "kotlin 123"
 ```
 
+<div id='scopes'></div> 
+
+## Escopos
+
+As variáveis em Kotlin podem ser declaradas em escopos diferentes, isto é, podem ser variáveis locais ou com um escopo
+global.
+
+Vejamos um exemplo em uma [classe](CLASS.md):
+
+```kotlin
+class Language {
+    val name = "Kotlin"
+
+    fun register() {
+        val template = "Language: %s."
+        println(template.format(name))
+    }
+}
+```
+
+Nesse exemplo, a variável `name` está no nível mais elevado/global, e a variável `template` é local porque está na
+função `register`. A variável de nível elevado `name` pode ser utilizada em qualquer lugar, inclusive em outros
+arquivos, enquanto a variável local `template` pode ser utilizada somente na função onde foi declarada:
+
+```kotlin
+fun main() {
+    val language = Language()
+    language.register()    // Imprime "Language: Kotlin.".
+    println(language.name) // Eu posso acessar a variável name, pois ela é global. Imprime "Kotlin".
+}
+```
+
+_Você pode testar esse código [online](https://pl.kotl.in/2EZqH2QuF)._
+
 Ir para [tipos de dados](TYPES.md).