Improve the Qt/JavaScript (QJS) documentation

Make sure all public classes and functions are documented.
Fix/remove broken references.
Add code snippets.
Add a minimal "Making Applications Scriptable" page based
on the QtScript docs.

Change-Id: I76a32bff776b478f01ff08b3276a0a020a1fa81f
Reviewed-on: http://codereview.qt.nokia.com/2863
Reviewed-by: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Simon Hausmann <simon.hausmann@nokia.com>

7 files changed, 480 insertions, 0 deletions

diff --git a/doc/src/declarative/qtjavascript.qdoc b/doc/src/declarative/qtjavascript.qdoc
new file mode 100644
index 0000000000..6d5e237c63
--- /dev/null
+++ b/doc/src/declarative/qtjavascript.qdoc
@@ -0,0 +1,92 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \group qtjavascript
+    \title Scripting Classes and Overviews
+
+    \brief Classes for embedding JavaScript in Qt/C++ applications.
+*/
+
+/*!
+  \page qtjavascript.html
+  \title Making Applications Scriptable
+  \ingroup frameworks-technologies
+
+  Qt provides support for application scripting with JavaScript.
+  The following guides and references cover aspects of programming with
+  JavaScript and Qt.
+
+  \tableofcontents
+
+  \section1 Scripting Classes
+
+  The following classes add scripting capabilities to Qt applications.
+
+  \annotatedlist qtjavascript
+
+  \section1 Basic Usage
+
+  To evaluate script code, you create a QJSEngine and call its
+  evaluate() function, passing the script code (text) to evaluate
+  as argument.
+
+  \snippet doc/src/snippets/qtjavascript/evaluation/main.cpp 0
+
+  The return value will be the result of the evaluation (represented
+  as a QJSValue object); this can be converted to standard C++
+  and Qt types.
+
+  Custom properties can be made available to scripts by registering
+  them with the script engine. This is most easily done by setting
+  properties of the script engine's \e{Global Object}:
+
+  \snippet doc/src/snippets/qtjavascript/registeringvalues/main.cpp 0
+
+  This places the properties in the script environment, thus making them
+  available to script code.
+
+  \section1 Making a QObject Available to the Script Engine
+
+  Any QObject-based instance can be made available for use with scripts.
+
+  When a QObject is passed to the QJSEngine::newQObject() function,
+  a Qt Script wrapper object is created that can be used to make the
+  QObject's signals, slots, properties, and child objects available
+  to scripts.
+
+  Here's an example of making an instance of a QObject subclass
+  available to script code under the name \c{"myObject"}:
+
+  \snippet doc/src/snippets/qtjavascript/registeringobjects/main.cpp 0
+
+  This will create a global variable called \c{myObject} in the
+  script environment. The variable serves as a proxy to the
+  underlying C++ object. Note that the name of the script variable
+  can be anything; i.e., it is not dependent upon QObject::objectName().
+
+ */
diff --git a/doc/src/snippets/code/src_script_qjsengine.cpp b/doc/src/snippets/code/src_script_qjsengine.cpp
new file mode 100644
index 0000000000..56c3d6b114
--- /dev/null
+++ b/doc/src/snippets/code/src_script_qjsengine.cpp
@@ -0,0 +1,90 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+QJSEngine myEngine;
+QJSValue three = myEngine.evaluate("1 + 2");
+//! [0]
+
+
+//! [1]
+QJSValue fun = myEngine.evaluate("(function(a, b) { return a + b; })");
+QJSValueList args;
+args << 1 << 2;
+QJSValue threeAgain = fun.call(QJSValue(), args);
+//! [1]
+
+
+//! [2]
+QString fileName = "helloworld.qs";
+QFile scriptFile(fileName);
+if (!scriptFile.open(QIODevice::ReadOnly))
+    // handle error
+QTextStream stream(&scriptFile);
+QString contents = stream.readAll();
+scriptFile.close();
+myEngine.evaluate(contents, fileName);
+//! [2]
+
+
+//! [3]
+myEngine.globalObject().setProperty("myNumber", 123);
+...
+QJSValue myNumberPlusOne = myEngine.evaluate("myNumber + 1");
+//! [3]
+
+
+//! [4]
+QJSValue result = myEngine.evaluate(...);
+if (myEngine.hasUncaughtException())
+    qDebug() << "uncaught exception:" << result.toString();
+//! [4]
+
+
+//! [5]
+QPushButton button;
+QJSValue scriptButton = myEngine.newQObject(&button);
+myEngine.globalObject().setProperty("button", scriptButton);
+
+myEngine.evaluate("button.checkable = true");
+
+qDebug() << scriptButton.property("checkable").toBoolean();
+scriptButton.property("show").call(); // call the show() slot
+//! [5]
diff --git a/doc/src/snippets/code/src_script_qjsvalue.cpp b/doc/src/snippets/code/src_script_qjsvalue.cpp
new file mode 100644
index 0000000000..c64c4c0f2a
--- /dev/null
+++ b/doc/src/snippets/code/src_script_qjsvalue.cpp
@@ -0,0 +1,65 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+QJSEngine myEngine;
+QJSValue myObject = myEngine.newObject();
+QJSValue myOtherObject = myEngine.newObject();
+myObject.setProperty("myChild", myOtherObject);
+myObject.setProperty("name", "John Doe");
+//! [0]
+
+
+//! [1]
+QJSEngine engine;
+engine.evaluate("function fullName() { return this.firstName + ' ' + this.lastName; }");
+engine.evaluate("somePerson = { firstName: 'John', lastName: 'Doe' }");
+
+QJSValue global = engine.globalObject();
+QJSValue fullName = global.property("fullName");
+QJSValue who = global.property("somePerson");
+qDebug() << fullName.call(who).toString(); // "John Doe"
+
+engine.evaluate("function cube(x) { return x * x * x; }");
+QJSValue cube = global.property("cube");
+QJSValueList args;
+args << 3;
+qDebug() << cube.call(QJSValue(), args).toNumber(); // 27
+//! [1]
diff --git a/doc/src/snippets/code/src_script_qjsvalueiterator.cpp b/doc/src/snippets/code/src_script_qjsvalueiterator.cpp
new file mode 100644
index 0000000000..f72e9180e1
--- /dev/null
+++ b/doc/src/snippets/code/src_script_qjsvalueiterator.cpp
@@ -0,0 +1,72 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+QScriptValue object;
+...
+QScriptValueIterator it(object);
+while (it.hasNext()) {
+    it.next();
+    qDebug() << it.name() << ": " << it.value().toString();
+}
+//! [0]
+
+
+//! [1]
+QScriptValue obj = ...; // the object to iterate over
+while (obj.isObject()) {
+    QScriptValueIterator it(obj);
+    while (it.hasNext()) {
+        it.next();
+        qDebug() << it.name();
+    }
+    obj = obj.prototype();
+}
+//! [1]
+
+
+//! [2]
+while (it.hasNext()) {
+    it.next();
+    if (it.flags() & QScriptValue::SkipInEnumeration)
+        continue;
+    qDebug() << "found enumerated property:" << it.name();
+}
+//! [2]
diff --git a/doc/src/snippets/qtjavascript/evaluation/main.cpp b/doc/src/snippets/qtjavascript/evaluation/main.cpp
new file mode 100644
index 0000000000..77825669a8
--- /dev/null
+++ b/doc/src/snippets/qtjavascript/evaluation/main.cpp
@@ -0,0 +1,51 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QtDeclarative>
+
+int main(int argc, char *argv[])
+{
+    QCoreApplication app(argc, argv);
+    //! [0]
+    QJSEngine engine;
+    qDebug() << "the magic number is:" << engine.evaluate("1 + 2").toNumber();
+    //! [0]
+    return 0;
+}
diff --git a/doc/src/snippets/qtjavascript/registeringobjects/main.cpp b/doc/src/snippets/qtjavascript/registeringobjects/main.cpp
new file mode 100644
index 0000000000..25c0f148e7
--- /dev/null
+++ b/doc/src/snippets/qtjavascript/registeringobjects/main.cpp
@@ -0,0 +1,57 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QObject>
+#include <QtDeclarative>
+#include "myobject.h"
+
+int main(int argc, char *argv[])
+{
+    QCoreApplication app(argc, argv);
+    //! [0]
+    QJSEngine engine;
+    QObject *someObject = new MyObject;
+    QJSValue objectValue = engine.newQObject(someObject);
+    engine.globalObject().setProperty("myObject", objectValue);
+    //! [0]
+    qDebug() << "myObject's calculate() function returns"
+             << engine.evaluate("myObject.calculate(10)").toNumber();
+    return 0;
+}
diff --git a/doc/src/snippets/qtjavascript/registeringvalues/main.cpp b/doc/src/snippets/qtjavascript/registeringvalues/main.cpp
new file mode 100644
index 0000000000..fe32f7065a
--- /dev/null
+++ b/doc/src/snippets/qtjavascript/registeringvalues/main.cpp
@@ -0,0 +1,53 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QtDeclarative>
+
+int main(int argc, char *argv[])
+{
+    QCoreApplication app(argc, argv);
+    QJSEngine engine;
+    //! [0]
+    engine.globalObject().setProperty("foo", 123);
+    qDebug() << "foo times two is:" << engine.evaluate("foo * 2").toNumber();
+    //! [0]
+    return 0;
+}
+