Merge pull request Kotlin#51 from p7nov/js-revised

docs: revised Kotlin/JS

Author: AlexanderPrendota

examples/09_Kotlin_JS/01_dynamic.md

@@ -30,9 +30,9 @@ fun main(){
 
 </div>
 
-1. Any value can be assigned to variable to `dynamic` type
-2. Dynamic value can be assigned to anything.
-3. Dynamic value can be passed as argument to any function
-4. Any property or function with any arguments can be called on `dynamic` value 
-5. Dynamic call always returns dynamic value, so it is possible to chain them.
-6. Operators, assignments and indexed access (`[..]`) are translated "as is". Beware!
+1. Any value can be assigned to a `dynamic` variable type.
+2. A dynamic value can be assigned to anything.
+3. A dynamic variable can be passed as an argument to any function.
+4. Any property or function with any arguments can be called on a `dynamic` variable. 
+5. A function call on a `dynamic` variable always returns a dynamic value, so it is possible to chain the calls.
+6. Operators, assignments, and indexed access (`[..]`) are translated "as is". Beware!

examples/09_Kotlin_JS/02_js_function.md

@@ -1,7 +1,21 @@
 # JS function
 
-You can inline some JavaScript code into your Kotlin code using the `js("…")` function.
-Should be used with extreme care. 
+You can inline JavaScript code into your Kotlin code using the js("…") function.
+This should be used with extreme care.
+
+
+<div class="language-kotlin" theme="idea" data-min-compiler-version="1.3" data-target-platform="js">
+
+```kotlin
+fun main() {
+// sampleStart
+    js("alert(\"alert from Kotlin!\")") // 1
+// sampleEnd    
+}
+```
+</div>
+
+1. Sending a JavaScript alert from a Kotlin function. 
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3" data-target-platform="js">
 
@@ -19,6 +33,6 @@ fun main(){
 
 </div>
 
-1. Create a JavaScript object literal. The `js(...)` function return type is `dynamic`.
-2. Add some properties by utilizing the `dynamic` type capabilities.
-3. Pass the JSON to JavaScript API.
+1. Creates a JavaScript object literal. The `js(...)` function return type is `dynamic`.
+2. Adds some properties by utilizing the `dynamic` type capabilities.
+3. Passes the JSON to JavaScript API.

examples/09_Kotlin_JS/03_external.md

@@ -14,11 +14,11 @@ fun main() {
 
 </div>
 
-1. Declare an existing JavaScript function `alert` which takes a single `String` argument
-2. Use it as if it was regular Kotlin.
+1. Declares an existing JavaScript function `alert` which takes a single `String` argument.
+2. Uses `alert` as if it were regular Kotlin.
 
-Note that Kotlin checks during compilation that exactly a single argument of type `String` is passed.
-That prevents a number of bugs even when using pure JavaScript API - same as with regular Kotlin.
+Note that Kotlin checks during compilation, that a single argument of type String is passed. 
+Such a check prevents some bugs even when using pure JavaScript API.
 
 Please [refer to the docs](https://kotlinlang.org/docs/reference/js-interop.html#external-modifier) in order 
 to learn more about describing existing JavaScript API.

examples/09_Kotlin_JS/06_HtmlBuilder.md

@@ -1,10 +1,8 @@
 # Html Builder
 
-This is an example of a Type-Safe Groovy-style Builder
-
-Builders are good for declaratively describing data in your code.
-In this example we show how to describe an HTML page in Kotlin
+Kotlin provides you with an option to describe structured data in a declarative style with _builders_.
 
+Below is an example of a type-safe Groovy-style builder. In this example, we will describe an HTML page in Kotlin.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3" data-target-platform="canvas" data-output-height="400">
 
@@ -127,8 +125,8 @@ fun html(init: HTML.() -> Unit): HTML {
    This means that we need to pass an instance of type `HTML` (a receiver) to the function,
    and we can call members of that instance inside the function.
 
-2. `head` and `body` are member functions of `HTML`.
+2. `head` and `body` are member functions of the`HTML` class.
 
-3. Text us added to tags by calling `unaryPlus()` operation.
+3. Adds the text to tags by calling the `unaryPlus()` operation, like `+"HTML encoding with Kotlin"`.
 
-For details see: [Type Safe Builders](http://kotlinlang.org/docs/reference/type-safe-builders.html)
+For details see: [Type Safe Builders](http://kotlinlang.org/docs/reference/type-safe-builders.html)