📚 Update concrete expressions documentation

Author: alexaubry

Sources/Expressions/JSFunction.swift

@@ -6,28 +6,30 @@
 import Foundation
 
 ///
-/// A concrete JavaScript expression that executes a function in the current JavaScript `this`. The
-/// function variable is represented by a key path relative to the current `this`.
+/// A JavaScript expression that executes a function in the current JavaScript `this`. The
+/// function variable is referenced by a key path relative to the current `this`.
 ///
 /// For instance, to present an alert:
 ///
 /// ~~~swift
-/// let alert = JSFreeFunction<Void>("window.alert", arguments: "Hello from Swift!")
-/// // equivalent to the JS script `this.window.alert("Hello from Swift!");`
+/// let alert = JSFunction<JSVoid>("window.alert", arguments: "Hello from Swift!")
+/// // equivalent to the JS script: `this.window.alert("Hello from Swift!");`
 /// ~~~
 ///
 /// Instances of this class are specialized with the `T` generic parameter. It must be set to the
 /// return type of the JavaScript function to execute. Check the documentation of the JavaScript
 /// function to know what to set the parameter to.
 ///
-/// `T` must be a compatible type. Compatible types include:
-/// - `Void`
-/// - Primitive values (`JSPrimitiveType`)
-/// - Enum cases with a primitive `RawValue`
-/// - Objects (`JSObject`)
+/// `T` must be a `Decodable` type. This includes:
+///
+/// - `JSVoid` for functions that do not return a value
+/// - Primitive values (Strings, Numbers, Booleans, ...)
+/// - Decodable enumerations
+/// - Objects decodable from JSON
 /// - Arrays of primitive values
-/// - Arrays of enum cases with a primitive `RawValue`
-/// - Arrays of objects.
+/// - Arrays of enumeration cases
+/// - Arrays of objects
+/// - Native dictionaries
 ///
 
 public final class JSFunction<T>: JSExpression where T: Decodable {
@@ -51,8 +53,8 @@ public final class JSFunction<T>: JSExpression where T: Decodable {
     /// For instance, to present an alert:
     ///
     /// ~~~swift
-    /// let alert = JSFreeFunction<Void>("window.alert", arguments: "Hello from Swift!")
-    /// // equivalent to the JS script `this.window.alert("Hello from Swift!");`
+    /// let alert = JSFunction<JSVoid>("window.alert", arguments: "Hello from Swift!")
+    /// // equivalent to the JS script: `this.window.alert("Hello from Swift!");`
     /// ~~~
     ///
 

Sources/Expressions/JSScript.swift

@@ -6,8 +6,8 @@
 import Foundation
 
 ///
-/// A concrete JavaScript expression that executes a user-defined script. This class allows you to
-/// evaluate your own scripts.
+/// A JavaScript expression that executes a user-defined script. This class allows you to
+/// evaluate your own custom scripts.
 ///
 /// For instance, to return the text of the longest <p> node in the current document:
 ///
@@ -35,26 +35,30 @@ import Foundation
 /// type of the last statement in your script. In the above example, `findLongestText` has a return
 /// type of `String` because its last statement is a String (`longestInnerHTML`).
 ///
-/// `T` must be a compatible type. Compatible types include:
-/// - `Void`
-/// - Primitive values (`JSPrimitiveType`)
-/// - Enum cases with a primitive `RawValue`
-/// - Objects (`JSObject`)
+/// `T` must be a `Decodable` type. This includes:
+///
+/// - `JSVoid` for scripts that do not return a value
+/// - Primitive values (Strings, Numbers, Booleans, ...)
+/// - Decodable enumerations
+/// - Objects decodable from JSON
 /// - Arrays of primitive values
-/// - Arrays of enum cases with a primitive `RawValue`
-/// - Arrays of objects.
+/// - Arrays of enumeration cases
+/// - Arrays of objects
+/// - Native dictionaries
 ///
 
 public final class JSScript<T>: JSExpression where T: Decodable {
-
     public typealias ReturnType = T
+
+    /// The text of the script to execute.
     public let javaScriptString: String
 
     ///
     /// Creates a new custom script description with the script to execute.
     ///
     /// - parameter javaScriptString: The script to run when evaluating this expression. It will
-    /// be ran as is, make sure to check for syntax errors before creating the expression.
+    /// be ran without modifications, so make sure to check for syntax errors and escape strings if
+    /// necessary before creating the expression.
     ///
 
     public init(_ javaScriptString: String) {

Sources/Expressions/JSVariable.swift

@@ -6,31 +6,32 @@
 import Foundation
 
 ///
-/// A concrete JavaScript expression that returns the value of a variable in the current JavaScript
-/// `this`. The variable is represented by a key path relative to the current `this`.
+/// A JavaScript expression that returns the value of a variable in the current JavaScript
+/// `this`. The variable is referenced by a key path relative to the current `this`.
 ///
 /// For instance, to get the title of the current document:
 ///
 /// ~~~swift
 /// let title = JSVariable<String>("document.title")
-/// // equivalent to the JS script `this.document.title;`
+/// // equivalent to the JS script: `this.document.title;`
 /// ~~~
 ///
 /// Instances of this class are specialized with the `T` generic parameter. It must be set to the
 /// type of the JavaScript variable to query. Check the documentation of the JavaScript variable
 /// to know what to set the parameter to.
 ///
-/// `T` must be a compatible type. Compatible types include:
-/// - Primitive values (`JSPrimitiveType`)
-/// - Enum cases with a primitive `RawValue`
-/// - Objects (`JSObject`)
+/// `T` must be a `Decodable` type. This includes:
+///
+/// - Primitive values (Strings, Numbers, Booleans, ...)
+/// - Decodable enumerations
+/// - Objects decodable from JSON
 /// - Arrays of primitive values
-/// - Arrays of enum cases with a primitive `RawValue`
-/// - Arrays of objects.
+/// - Arrays of enumeration cases
+/// - Arrays of objects
+/// - Native dictionaries
 ///
 
 public final class JSVariable<T>: JSExpression where T: Decodable {
-    
     public typealias ReturnType = T
 
     /// The path to the variable, relative to the current `this` object tree.
@@ -46,7 +47,7 @@ public final class JSVariable<T>: JSExpression where T: Decodable {
     ///
     /// ~~~swift
     /// let title = JSVariable<String>("document.title")
-    /// // equivalent to the JS script `this.document.title;`
+    /// // equivalent to the JS script: `this.document.title;`
     /// ~~~
     ///