Clean up structure of JavaScript related docs

The global object and list of javascript functions should be linked to
as subsections from the "JavaScript Host Environment" topic page, and
all of the subsections should be visible from the module index page.

Also move the "restrictions" docs to this topic page as it's more
relevant to this section.

Also includes some minor doc improvements.

Task-number: QTBUG-26380

Change-Id: Iba6e4e510191bf5e4603d6cbb2826ad7bcdbd10c
Reviewed-by: Chris Adams <christopher.adams@nokia.com>

7 files changed, 136 insertions, 116 deletions

diff --git a/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc b/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc
index 95deba52c6..81c340fe70 100644
--- a/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc
+++ b/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc
@@ -64,11 +64,10 @@ Once you have a \l Component, you can call its \l {Component::createObject()}
 can take one or two arguments:
 \list
 \li The first is the parent for the new object.  The parent can be a graphical
-    object (QtQuick item) or non-graphical object
-    (\l{qtqml-typereference-topic.html}{QtQml} \l QtObject or C++
-    QObject).  Only graphical objects with graphical parent objects will be
-    rendered to the QtQuick visual canvas.  If you wish to set the parent later
-    you can safely pass \c null to this function.
+    object (i.e. of the \l Item type) or non-graphical object (i.e. of the
+    \l QtObject or C++ QObject type). Only graphical objects with graphical
+    parent objects will be rendered to the QtQuick visual canvas.  If you wish
+    to set the parent later you can safely pass \c null to this function.
 \li The second is optional and is a map of property-value pairs that define
     initial any property values for the object.  Property values specified by
     this argument are applied to the object before its creation is finalized,
diff --git a/src/qml/doc/src/javascript/expressions.qdoc b/src/qml/doc/src/javascript/expressions.qdoc
index 3c8f83d22b..ea699a9a4f 100644
--- a/src/qml/doc/src/javascript/expressions.qdoc
+++ b/src/qml/doc/src/javascript/expressions.qdoc
@@ -40,9 +40,9 @@ The JavaScript environment provided by QML is stricter than that in a web
 browser.  For example, in QML you cannot add, or modify, members of the
 JavaScript global object.  In regular JavaScript, it is possible to do this
 accidentally by using a variable without declaring it. In QML this will throw
-an exception, so all local variables should be explicitly declared.  A complete
-description of the limitations of JavaScript code in QML is included in an
-\l{JavaScript Expression Restrictions in QML}{upcoming section}.
+an exception, so all local variables should be explicitly declared.  See
+\l{JavaScript Environment Restrictions} for a complete description of the
+restrictions on JavaScript code executed from QML.
 
 There are various ways in which JavaScript expressions may be defined and used
 in QML, including property bindings, signal handlers, custom methods and
@@ -299,8 +299,9 @@ component instance) startup.  While it is tempting to just include the startup
 script as \e {global code} in an external script file, this can have severe
 limitations as the QML environment may not have been fully established.  For
 example, some objects might not have been created or some
-\l {Property Binding}s may not have been run.  \l {JavaScript Expression Restrictions in QML}
-covers the exact limitations of global script code.
+\l {Property Binding}{property bindings} may not have been run.
+\l {JavaScript Environment Restrictions} covers the exact limitations of global
+script code.
 
 Every QML object has an \e attached \l Component property that references the
 component within which the object was instantiated.  Every \l Component
@@ -331,102 +332,6 @@ on component destruction.
 
 
 
-
-
-
-\section1 JavaScript Expression Restrictions in QML
-
-QML executes standard JavaScript code, with the following restrictions:
-
-\list
-\li JavaScript code cannot modify the global object.
-
-In QML, the global object is constant - existing properties cannot be modified
-or deleted, and no new properties may be created.
-
-Most JavaScript programs do not intentionally modify the global object.
-However, JavaScript's automatic creation of undeclared variables is an implicit
-modification of the global object, and is prohibited in QML.
-
-Assuming that the \c a variable does not exist in the scope chain, the
-following code is illegal in QML:
-
-\code
-// Illegal modification of undeclared variable
-a = 1;
-for (var ii = 1; ii < 10; ++ii)
-    a = a * ii;
-console.log("Result: " + a);
-\endcode
-
-It can be trivially modified to this legal code.
-
-\code
-var a = 1;
-for (var ii = 1; ii < 10; ++ii)
-    a = a * ii;
-console.log("Result: " + a);
-\endcode
-
-Any attempt to modify the global object - either implicitly or explicitly - will
-cause an exception.  If uncaught, this will result in an warning being printed,
-that includes the file and line number of the offending code.
-
-\li Global code is run in a reduced scope
-
-During startup, if a QML file includes an external JavaScript file with "global"
-code, it is executed in a scope that contains only the external file itself and
-the global object.  That is, it will not have access to the QML objects and
-properties it \l {Scope and Naming Resolution}{normally would}.
-
-Global code that only accesses script local variable is permitted.  This is an
-example of valid global code.
-
-\code
-var colors = [ "red", "blue", "green", "orange", "purple" ];
-\endcode
-
-Global code that accesses QML objects will not run correctly.
-
-\code
-// Invalid global code - the "rootObject" variable is undefined
-var initialPosition = { rootObject.x, rootObject.y }
-\endcode
-
-This restriction exists as the QML environment is not yet fully established.
-To run code after the environment setup has completed, refer to
-\l {Running JavaScript at Startup}.
-
-\li The value of \c this is currently undefined in QML in the majority of contexts
-
-The \c this keyword is supported when binding properties from JavaScript.
-In all other situations, the value of
-\c this is undefined in QML.
-
-To refer to any element, provide an \c id.  For example:
-
-\qml
-Item {
-    width: 200; height: 100
-    function mouseAreaClicked(area) {
-        console.log("Clicked in area at: " + area.x + ", " + area.y);
-    }
-    // This will not work because this is undefined
-    MouseArea {
-        height: 50; width: 200
-        onClicked: mouseAreaClicked(this)
-    }
-    // This will pass area2 to the function
-    MouseArea {
-        id: area2
-        y: 50; height: 50; width: 200
-        onClicked: mouseAreaClicked(area2)
-    }
-}
-\endqml
-
-\endlist
-
 \section1 Scarce Resources in JavaScript
 
 As described in the documentation for \l{QML Basic Types}, a \c var type
diff --git a/src/qml/doc/src/javascript/functionlist.qdoc b/src/qml/doc/src/javascript/functionlist.qdoc
index 9dca6c51be..97d2bf7d45 100644
--- a/src/qml/doc/src/javascript/functionlist.qdoc
+++ b/src/qml/doc/src/javascript/functionlist.qdoc
@@ -190,6 +190,12 @@
     \li trim()
     \endlist
 
+    Additionally, the QML engine adds the following functions to the \l String prototype:
+    \list
+    \li \l {String::arg}{arg()}
+    \endlist
+
+
     \section1 Boolean Objects
 
     \section2 Boolean Prototype Object
@@ -215,6 +221,13 @@
     \li toPrecision(precision)
     \endlist
 
+    Additionally, the QML engine adds the following functions to the \l Number prototype:
+    \list
+    \li \l {Number::fromLocaleString}{fromLocaleString(locale, number)}
+    \li \l {Number::toLocaleCurrencyString}{toLocaleCurrencyString(locale, symbol)}
+    \li \l {Number::toLocaleString}{toLocaleString(locale, format, precision)}
+    \endlist
+
     \section1 The Math Object
 
     \section2 Value Properties
@@ -305,6 +318,14 @@
     \li toJSON()
     \endlist
 
+    Additionally, the QML engine adds the following functions to the \l Date prototype:
+    \list
+    \li \l {Date::timeZoneUpdated}{timeZoneUpdated()}
+    \li \l {Date::toLocaleDateString}{toLocaleDateString(locale, format)}
+    \li \l {Date::toLocaleString}{toLocaleString(locale, format)}
+    \li \l {Date::toLocaleTimeString}{toLocaleTimeString(locale, format)}
+    \endlist
+
     \section1 RegExp Objects
 
     \section2 RegExp Prototype Object
diff --git a/src/qml/doc/src/javascript/hostenvironment.qdoc b/src/qml/doc/src/javascript/hostenvironment.qdoc
index ad2b905e22..6d1fa6534b 100644
--- a/src/qml/doc/src/javascript/hostenvironment.qdoc
+++ b/src/qml/doc/src/javascript/hostenvironment.qdoc
@@ -52,32 +52,122 @@ specific to the browser environment. In the case of the W3Schools link above, th
 Reference} section generally covers the standard, while the \c{Browser Objects Reference} and \c{HTML DOM
 Objects Reference} sections are browser specific (and thus not applicable to QML).
 
-\section1 Host Objects and Functions
+
+\section1 QML Global Object
 
 The QML JavaScript host environment implements a number of host objects and functions, as
 detailed in the \l{QML Global Object} documentation.
 
+These host objects and functions are always available, regardless of whether any modules
+have been imported.
+
 
-\section1 Native Object Modification
+\section1 JavaScript Objects and Functions
 
-QML makes the following modifications to native objects:
+A list of the JavaScript objects, functions and properties supported by the
+QML engine can be found in the \l{List of JavaScript Objects and Functions}.
+
+Note that QML makes the following modifications to native objects:
 
 \list
 \li An \l {String::arg}{arg()} function is added to the \l String prototype.
 \li Locale-aware coversion functions are added to the \l Date and \l Number prototypes.
 \endlist
 
-\section1 Restrictions
+
+\section1 JavaScript Environment Restrictions
 
 QML implements the following restrictions for JavaScript code:
 
 \list
 \li JavaScript code cannot modify the global object.
+
+In QML, the global object is constant - existing properties cannot be modified
+or deleted, and no new properties may be created.
+
+Most JavaScript programs do not intentionally modify the global object.
+However, JavaScript's automatic creation of undeclared variables is an implicit
+modification of the global object, and is prohibited in QML.
+
+Assuming that the \c a variable does not exist in the scope chain, the
+following code is illegal in QML:
+
+\code
+// Illegal modification of undeclared variable
+a = 1;
+for (var ii = 1; ii < 10; ++ii)
+    a = a * ii;
+console.log("Result: " + a);
+\endcode
+
+It can be trivially modified to this legal code.
+
+\code
+var a = 1;
+for (var ii = 1; ii < 10; ++ii)
+    a = a * ii;
+console.log("Result: " + a);
+\endcode
+
+Any attempt to modify the global object - either implicitly or explicitly - will
+cause an exception.  If uncaught, this will result in an warning being printed,
+that includes the file and line number of the offending code.
+
 \li Global code is run in a reduced scope.
-\li The value of \c this is undefined in QML in the majority of contexts.
+
+During startup, if a QML file includes an external JavaScript file with "global"
+code, it is executed in a scope that contains only the external file itself and
+the global object.  That is, it will not have access to the QML objects and
+properties it \l {Scope and Naming Resolution}{normally would}.
+
+Global code that only accesses script local variable is permitted.  This is an
+example of valid global code.
+
+\code
+var colors = [ "red", "blue", "green", "orange", "purple" ];
+\endcode
+
+Global code that accesses QML objects will not run correctly.
+
+\code
+// Invalid global code - the "rootObject" variable is undefined
+var initialPosition = { rootObject.x, rootObject.y }
+\endcode
+
+This restriction exists as the QML environment is not yet fully established.
+To run code after the environment setup has completed, refer to
+\l {Running JavaScript at Startup}.
+
+\li The value of \c this is currently undefined in QML in the majority of contexts.
+
+The \c this keyword is supported when binding properties from JavaScript.
+In all other situations, the value of
+\c this is undefined in QML.
+
+To refer to any element, provide an \c id.  For example:
+
+\qml
+Item {
+    width: 200; height: 100
+    function mouseAreaClicked(area) {
+        console.log("Clicked in area at: " + area.x + ", " + area.y);
+    }
+    // This will not work because this is undefined
+    MouseArea {
+        height: 50; width: 200
+        onClicked: mouseAreaClicked(this)
+    }
+    // This will pass area2 to the function
+    MouseArea {
+        id: area2
+        y: 50; height: 50; width: 200
+        onClicked: mouseAreaClicked(area2)
+    }
+}
+\endqml
+
 \endlist
 
-See \l {JavaScript Expression Restrictions in QML} for more details on these restrictions.
 
 
 */
diff --git a/src/qml/doc/src/javascript/qmlglobalobject.qdoc b/src/qml/doc/src/javascript/qmlglobalobject.qdoc
index c45b430025..8425eead30 100644
--- a/src/qml/doc/src/javascript/qmlglobalobject.qdoc
+++ b/src/qml/doc/src/javascript/qmlglobalobject.qdoc
@@ -30,7 +30,9 @@
 \brief Description of the Qml Global Object
 
 
-The QML JavaScript host environment implements the following host objects and functions:
+The QML JavaScript host environment implements the following host objects and functions.
+These are built in and can be used from any JavaScript code loaded in QML, without
+additional imports:
 
 \list
 \li The \l{QmlGlobalQtObject}{Qt object}: This object is specific to QML, and provides helper methods
diff --git a/src/qml/doc/src/qtqml.qdoc b/src/qml/doc/src/qtqml.qdoc
index b525b92be9..35667034d0 100644
--- a/src/qml/doc/src/qtqml.qdoc
+++ b/src/qml/doc/src/qtqml.qdoc
@@ -116,12 +116,15 @@ for an introduction to writing QML applications.
     \li \l{qtqml-javascript-topic.html}{Integrating QML and JavaScript}
         \list
         \li \l{qtqml-javascript-expressions.html}{Using JavaScript Expressions with QML}
+        \li \l{qtqml-javascript-dynamicobjectcreation.html}{Dynamic QML Object Creation from JavaScript}
         \li \l{qtqml-javascript-resources.html}{Defining JavaScript Resources In QML}
         \li \l{qtqml-javascript-imports.html}{Importing JavaScript Resources In QML}
         \li \l{qtqml-javascript-hostenvironment.html}{JavaScript Host Environment}
             \list
-            \li \l{qtqml-javascript-qmlglobalobject.html}{QML Global Object}
-            \li \l{qtqml-javascript-functionlist.html}{List of JavaScript Objects and Functions}
+            \li \l{qtqml-javascript-hostenvironment.html#common-base}{Common Base}
+            \li \l{qtqml-javascript-hostenvironment.html#qml-global-object}{QML Global Object}
+            \li \l{qtqml-javascript-hostenvironment.html#javascript-objects-and-functions}{JavaScript Objects and Functions}
+            \li \l{qtqml-javascript-hostenvironment.html#javascript-environment-restrictions}{JavaScript Environment Restrictions}
             \endlist
         \endlist
 
diff --git a/src/qml/doc/src/syntax/propertybinding.qdoc b/src/qml/doc/src/syntax/propertybinding.qdoc
index 48c17ff244..7b71b16407 100644
--- a/src/qml/doc/src/syntax/propertybinding.qdoc
+++ b/src/qml/doc/src/syntax/propertybinding.qdoc
@@ -186,7 +186,7 @@ In this case, the function could also have referred to \c rect.width rather than
 \c this.width.
 
 Note that the value of \c this is not defined outside of its use in property binding.
-See \l {JavaScript Expression Restrictions in QML} for details.
+See \l {JavaScript Environment Restrictions} for details.
 
 
 */