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>

3 files changed, 264 insertions, 60 deletions

diff --git a/src/declarative/qml/v8/qjsengine.cpp b/src/declarative/qml/v8/qjsengine.cpp
index e80fcb4e7e..3db7fc40e0 100644
--- a/src/declarative/qml/v8/qjsengine.cpp
+++ b/src/declarative/qml/v8/qjsengine.cpp
@@ -52,6 +52,97 @@ Q_DECLARE_METATYPE(QJSValue)
 Q_DECLARE_METATYPE(QObjectList)
 Q_DECLARE_METATYPE(QList<int>)
 
+/*!
+  \since 5.0
+  \class QJSEngine
+
+  \brief The QJSEngine class provides an environment for evaluating JavaScript code.
+
+  \ingroup qtjavascript
+  \mainclass
+
+  \section1 Evaluating Scripts
+
+  Use evaluate() to evaluate script code.
+
+  \snippet doc/src/snippets/code/src_script_qjsengine.cpp 0
+
+  evaluate() returns a QJSValue that holds the result of the
+  evaluation. The QJSValue class provides functions for converting
+  the result to various C++ types (e.g. QJSValue::toString()
+  and QJSValue::toNumber()).
+
+  The following code snippet shows how a script function can be
+  defined and then invoked from C++ using QJSValue::call():
+
+  \snippet doc/src/snippets/code/src_script_qjsengine.cpp 1
+
+  As can be seen from the above snippets, a script is provided to the
+  engine in the form of a string. One common way of loading scripts is
+  by reading the contents of a file and passing it to evaluate():
+
+  \snippet doc/src/snippets/code/src_script_qjsengine.cpp 2
+
+  Here we pass the name of the file as the second argument to
+  evaluate().  This does not affect evaluation in any way; the second
+  argument is a general-purpose string that is used to identify the
+  script for debugging purposes (for example, our filename will now
+  show up in any uncaughtExceptionBacktrace() involving the script).
+
+  \section1 Engine Configuration
+
+  The globalObject() function returns the \bold {Global Object}
+  associated with the script engine. Properties of the Global Object
+  are accessible from any script code (i.e. they are global
+  variables). Typically, before evaluating "user" scripts, you will
+  want to configure a script engine by adding one or more properties
+  to the Global Object:
+
+  \snippet doc/src/snippets/code/src_script_qjsengine.cpp 3
+
+  Adding custom properties to the scripting environment is one of the
+  standard means of providing a scripting API that is specific to your
+  application. Usually these custom properties are objects created by
+  the newQObject() or newObject() functions.
+
+  \section1 Script Exceptions
+
+  evaluate() can throw a script exception (e.g. due to a syntax
+  error); in that case, the return value is the value that was thrown
+  (typically an \c{Error} object). You can check whether the
+  evaluation caused an exception by calling hasUncaughtException(). In
+  that case, you can call toString() on the error object to obtain an
+  error message. The current uncaught exception is also available
+  through uncaughtException().
+  Calling clearExceptions() will cause any uncaught exceptions to be
+  cleared.
+
+  \snippet doc/src/snippets/code/src_script_qjsengine.cpp 4
+
+  \section1 Script Object Creation
+
+  Use newObject() to create a JavaScript object; this is the
+  C++ equivalent of the script statement \c{new Object()}. You can use
+  the object-specific functionality in QJSValue to manipulate the
+  script object (e.g. QJSValue::setProperty()). Similarly, use
+  newArray() to create a JavaScript array object. Use newDate() to
+  create a \c{Date} object, and newRegExp() to create a \c{RegExp}
+  object.
+
+  \section1 QObject Integration
+
+  Use newQObject() to wrap a QObject (or subclass)
+  pointer. newQObject() returns a proxy script object; properties,
+  children, and signals and slots of the QObject are available as
+  properties of the proxy object. No binding code is needed because it
+  is done dynamically using the Qt meta object system.
+
+  \snippet doc/src/snippets/code/src_script_qjsengine.cpp 5
+
+  \sa QJSValue, {Making Applications Scriptable}
+
+*/
+
 QT_BEGIN_NAMESPACE
 
 
@@ -102,6 +193,11 @@ QJSEngine::~QJSEngine()
 }
 
 /*!
+    \fn QV8Engine *QJSEngine::handle() const
+    \internal
+*/
+
+/*!
     Returns true if the last script evaluation resulted in an uncaught
     exception; otherwise returns false.
 
@@ -201,6 +297,11 @@ QJSValue QJSEngine::evaluate(const QString& program, const QString& fileName, in
     return QJSValuePrivate::get(d->evaluate(program, fileName, lineNumber));
 }
 
+/*!
+  Returns a QJSValue of the primitive type Null.
+
+  \sa nullValue()
+*/
 QJSValue QJSEngine::nullValue()
 {
     Q_D(QJSEngine);
@@ -209,6 +310,11 @@ QJSValue QJSEngine::nullValue()
     return QJSValuePrivate::get(new QJSValuePrivate(d, v8::Null()));
 }
 
+/*!
+  Returns a QJSValue of the primitive type Undefined.
+
+  \sa nullValue()
+*/
 QJSValue QJSEngine::undefinedValue()
 {
     Q_D(QJSEngine);
@@ -217,6 +323,14 @@ QJSValue QJSEngine::undefinedValue()
     return QJSValuePrivate::get(new QJSValuePrivate(d, v8::Undefined()));
 }
 
+/*!
+  Creates a JavaScript object of class Object.
+
+  The prototype of the created object will be the Object
+  prototype object.
+
+  \sa newArray(), QJSValue::setProperty()
+*/
 QJSValue QJSEngine::newObject()
 {
     Q_D(QJSEngine);
@@ -225,6 +339,11 @@ QJSValue QJSEngine::newObject()
     return QJSValuePrivate::get(new QJSValuePrivate(d, v8::Object::New()));
 }
 
+/*!
+  Creates a JavaScript object of class Array with the given \a length.
+
+  \sa newObject()
+*/
 QJSValue QJSEngine::newArray(uint length)
 {
     Q_D(QJSEngine);
@@ -234,13 +353,12 @@ QJSValue QJSEngine::newArray(uint length)
 }
 
 /*!
-  Creates a QtScript object that wraps the given QObject \a
+  Creates a JavaScript object that wraps the given QObject \a
   object, using the given \a ownership. The given \a options control
   various aspects of the interaction with the resulting script object.
 
   Signals and slots, properties and children of \a object are
-  available as properties of the created QJSValue. For more
-  information, see the \l{QtScript} documentation.
+  available as properties of the created QJSValue.
 
   If \a object is a null pointer, this function returns nullValue().
 
@@ -248,8 +366,8 @@ QJSValue QJSEngine::newArray(uint length)
   (or its superclass, recursively), the prototype of the new script
   object will be set to be that default prototype.
 
-  If the given \a object is deleted outside of QtScript's control, any
-  attempt to access the deleted QObject's members through the QtScript
+  If the given \a object is deleted outside of the engine's control, any
+  attempt to access the deleted QObject's members through the JavaScript
   wrapper object (either by script code or C++) will result in a
   script exception.
 
@@ -264,7 +382,7 @@ QJSValue QJSEngine::newQObject(QObject *object)
 }
 
 /*!
-  Creates a QtScript object holding the given variant \a value.
+  Creates a JavaScript object holding the given variant \a value.
 
   If a default prototype has been registered with the meta type id of
   \a value, then the prototype of the created object will be that
@@ -282,6 +400,16 @@ QJSValue QJSEngine::newVariant(const QVariant &value)
 }
 
 
+/*!
+  Returns this engine's Global Object.
+
+  By default, the Global Object contains the built-in objects that are
+  part of \l{ECMA-262}, such as Math, Date and String. Additionally,
+  you can set properties of the Global Object to make your own
+  extensions available to all script code. Non-local variables in
+  script code will be created as properties of the Global Object, as
+  well as local variables in global code.
+*/
 QJSValue QJSEngine::globalObject() const
 {
     Q_D(const QJSEngine);
@@ -290,6 +418,23 @@ QJSValue QJSEngine::globalObject() const
     return d->scriptValueFromInternal(d->global());
 }
 
+/*!
+  Converts the given \a value to an object, if such a conversion is
+  possible; otherwise returns an invalid QJSValue. The conversion
+  is performed according to the following table:
+
+    \table
+    \header \o Input Type \o Result
+    \row    \o Undefined  \o An invalid QJSValue.
+    \row    \o Null       \o An invalid QJSValue.
+    \row    \o Boolean    \o A new Boolean object whose internal value is set to the value of the boolean.
+    \row    \o Number     \o A new Number object whose internal value is set to the value of the number.
+    \row    \o String     \o A new String object whose internal value is set to the value of the string.
+    \row    \o Object     \o The result is the object itself (no conversion).
+    \endtable
+
+    \sa newObject()
+*/
 QJSValue QJSEngine::toObject(const QJSValue& value)
 {
     Q_D(QJSEngine);
@@ -299,7 +444,7 @@ QJSValue QJSEngine::toObject(const QJSValue& value)
 }
 
 /*!
-  Creates a QtScript object of class Date from the given \a value.
+  Creates a JavaScript object of class Date from the given \a value.
 
   \sa QJSValue::toDateTime()
 */
@@ -312,7 +457,7 @@ QJSValue QJSEngine::newDate(const QDateTime &dt)
 }
 
 /*!
-  Creates a QtScript object of class Date with the given
+  Creates a JavaScript object of class Date with the given
   \a value (the number of milliseconds since 01 January 1970,
   UTC).
 */
@@ -325,7 +470,7 @@ QJSValue QJSEngine::newDate(double date)
 }
 
 /*!
-  Creates a QtScript object of class RegExp with the given
+  Creates a JavaScript object of class RegExp with the given
   \a regexp.
 
   \sa QJSValue::toRegExp()
@@ -339,7 +484,7 @@ QJSValue QJSEngine::newRegExp(const QRegExp &regexp)
 }
 
 /*!
-  Creates a QtScript object of class RegExp with the given
+  Creates a JavaScript object of class RegExp with the given
   \a pattern and \a flags.
 
   The legal flags are 'g' (global), 'i' (ignore case), and 'm'
@@ -425,6 +570,19 @@ bool QJSEngine::convertV2(const QJSValue &value, int type, void *ptr)
     }
 }
 
+/*! \fn QJSValue QJSEngine::toScriptValue(const T &value)
+
+    Creates a QJSValue with the given \a value.
+
+    \sa fromScriptValue()
+*/
+
+/*! \fn T QJSEngine::fromScriptValue(const QJSValue &value)
+
+    Returns the given \a value converted to the template type \c{T}.
+
+    \sa toScriptValue()
+*/
 
 QT_END_NAMESPACE
 
diff --git a/src/declarative/qml/v8/qjsvalue.cpp b/src/declarative/qml/v8/qjsvalue.cpp
index eff7b4321a..bbfae8983c 100644
--- a/src/declarative/qml/v8/qjsvalue.cpp
+++ b/src/declarative/qml/v8/qjsvalue.cpp
@@ -31,23 +31,71 @@
 #include <QtCore/qregexp.h>
 #include <QtCore/qstring.h>
 
-QT_BEGIN_NAMESPACE
-
 /*!
-    Constructs an invalid value.
+  \since 5.0
+  \class QJSValue
+
+  \brief The QJSValue class acts as a container for Qt/JavaScript data types.
+
+  \ingroup qtjavascript
+  \mainclass
+
+  QJSValue supports the types defined in the \l{ECMA-262}
+  standard: The primitive types, which are Undefined, Null, Boolean,
+  Number, and String; and the Object type. Additionally, built-in
+  support is provided for Qt/C++ types such as QVariant and QObject.
+
+  For the object-based types (including Date and RegExp), use the
+  newT() functions in QJSEngine (e.g. QJSEngine::newObject())
+  to create a QJSValue of the desired type. For the primitive types,
+  use one of the QJSValue constructor overloads.
+
+  The methods named isT() (e.g. isBool(), isUndefined()) can be
+  used to test if a value is of a certain type. The methods named
+  toT() (e.g. toBool(), toString()) can be used to convert a
+  QJSValue to another type. You can also use the generic
+  QJSValue_cast() function.
+
+  Object values have zero or more properties which are themselves
+  QJSValues. Use setProperty() to set a property of an object, and
+  call property() to retrieve the value of a property.
+
+  \snippet doc/src/snippets/code/src_script_qjsvalue.cpp 0
+
+  The attributes of a property can be queried by calling the
+  propertyFlags() function.
+
+  If you want to iterate over the properties of a script object, use
+  the QJSValueIterator class.
+
+  Object values have an internal \c{prototype} property, which can be
+  accessed with prototype() and setPrototype().
+
+  Function objects (objects for which isFunction() returns true) can
+  be invoked by calling call(). Constructor functions can be used to
+  construct new objects by calling construct().
+
+  Use equals() or strictlyEquals() to compare a QJSValue to another.
+
+  Note that a QJSValue for which isObject() is true only carries a
+  reference to an actual object; copying the QJSValue will only
+  copy the object reference, not the object itself. If you want to
+  clone an object (i.e. copy an object's properties to another
+  object), you can do so with the help of a \c{for-in} statement in
+  script code, or QJSValueIterator in C++.
+
+  \sa QJSEngine, QJSValueIterator
 */
-QJSValue::QJSValue()
-    : d_ptr(InvalidValue())
-{
-}
 
 /*!
-  Constructs a new QJSValue with a boolean \a value.
+    \enum QJSValue::SpecialValue
+
+    This enum is used to specify a single-valued type.
+
+    \value UndefinedValue An undefined value.
+
+    \value NullValue A null value.
 */
-QJSValue::QJSValue(bool value)
-    : d_ptr(new QJSValuePrivate(value))
-{
-}
 
 /*!
     \enum QJSValue::PropertyFlag
@@ -59,17 +107,25 @@ QJSValue::QJSValue(bool value)
     \value Undeletable Attempts by Qt Script code to \c{delete} the property will be ignored.
 
     \value SkipInEnumeration The property is not to be enumerated by a \c{for-in} enumeration.
+*/
 
-    \value PropertyGetter The property is defined by a function which will be called to get the property value.
-
-    \value PropertySetter The property is defined by a function which will be called to set the property value.
-
-    \omitvalue QObjectMember This flag is used to indicate that an existing property is a QObject member (a property or method).
+QT_BEGIN_NAMESPACE
 
-    \value KeepExistingFlags This value is used to indicate to setProperty() that the property's flags should be left unchanged. If the property doesn't exist, the default flags (0) will be used.
+/*!
+    Constructs an invalid value.
+*/
+QJSValue::QJSValue()
+    : d_ptr(InvalidValue())
+{
+}
 
-    \omitvalue UserRange Flags in this range are not used by Qt Script, and can be used for custom purposes.
+/*!
+  Constructs a new QJSValue with a boolean \a value.
 */
+QJSValue::QJSValue(bool value)
+    : d_ptr(new QJSValuePrivate(value))
+{
+}
 
 /*!
   Constructs a new QJSValue with a number \a value.
@@ -120,8 +176,6 @@ QJSValue::QJSValue(const QLatin1String &value)
 }
 
 /*!
-  \fn QJSValue::QJSValue(const QLatin1String &value)
-
   Constructs a new QJSValue with a string \a value.
 */
 #ifndef QT_NO_CAST_FROM_ASCII
@@ -383,8 +437,6 @@ bool QJSValue::isUndefined() const
 /*!
   Returns true if this QJSValue is an object of the Error class;
   otherwise returns false.
-
-  \sa QScriptContext::throwError()
 */
 bool QJSValue::isError() const
 {
@@ -654,7 +706,7 @@ QVariant QJSValue::toVariant() const
   QJSEngine::hasUncaughtException() to determine if an exception
   occurred.
 
-  \snippet doc/src/snippets/code/src_script_qscriptvalue.cpp 2
+  \snippet doc/src/snippets/code/src_script_qjsvalue.cpp 1
 
   \sa construct()
 */
@@ -773,7 +825,7 @@ QJSValue& QJSValue::operator=(const QJSValue& other)
   toString()) in an attempt to convert the object to a primitive value
   (possibly resulting in an uncaught script exception).
 
-  \sa strictlyEquals(), lessThan()
+  \sa strictlyEquals()
 */
 bool QJSValue::equals(const QJSValue& other) const
 {
@@ -830,9 +882,7 @@ bool QJSValue::instanceOf(const QJSValue &other) const
 }
 
 /*!
-  Returns the value of this QJSValue's property with the given \a name,
-  using the given \a mode to resolve the property.
-
+  Returns the value of this QJSValue's property with the given \a name.
   If no such property exists, an invalid QJSValue is returned.
 
   If the property is implemented using a getter function (i.e. has the
@@ -854,8 +904,7 @@ QJSValue QJSValue::property(const QString& name) const
 /*!
   \overload
 
-  Returns the property at the given \a arrayIndex, using the given \a
-  mode to resolve the property.
+  Returns the property at the given \a arrayIndex.
 
   This function is provided for convenience and performance when
   working with array objects.
@@ -878,8 +927,7 @@ QJSValue QJSValue::property(quint32 arrayIndex) const
   If this QJSValue is not an object, this function does nothing.
 
   If this QJSValue does not already have a property with name \a name,
-  a new property is created; the given \a flags then specify how this
-  property may be accessed by script code.
+  a new property is created.
 
   If \a value is invalid, the property is removed.
 
@@ -922,8 +970,7 @@ void QJSValue::setProperty(quint32 arrayIndex, const QJSValue& value)
 }
 
 /*!
-  Returns the flags of the property with the given \a name, using the
-  given \a mode to resolve the property.
+  Returns the flags of the property with the given \a name.
 
   \sa property()
 */
diff --git a/src/declarative/qml/v8/qjsvalueiterator.cpp b/src/declarative/qml/v8/qjsvalueiterator.cpp
index 42bfd3408c..76a43c9475 100644
--- a/src/declarative/qml/v8/qjsvalueiterator.cpp
+++ b/src/declarative/qml/v8/qjsvalueiterator.cpp
@@ -36,7 +36,7 @@ QT_BEGIN_NAMESPACE
 
     \brief The QJSValueIterator class provides a Java-style iterator for QJSValue.
 
-    \ingroup script
+    \ingroup qtjavascript
 
 
     The QJSValueIterator constructor takes a QJSValue as
@@ -44,28 +44,24 @@ QT_BEGIN_NAMESPACE
     beginning of the sequence of properties. Here's how to iterate over
     all the properties of a QJSValue:
 
-    \snippet doc/src/snippets/code/src_script_QJSValueIterator.cpp 0
+    \snippet doc/src/snippets/code/src_script_qjsvalueiterator.cpp 0
 
-    The next() advances the iterator. The name(), value() and flags()
-    functions return the name, value and flags of the last item that was
+    The next() advances the iterator. The name() and value()
+    functions return the name and value of the last item that was
     jumped over.
 
-    If you want to remove properties as you iterate over the
-    QJSValue, use remove(). If you want to modify the value of a
-    property, use setValue().
-
     Note that QJSValueIterator only iterates over the QJSValue's
     own properties; i.e. it does not follow the prototype chain. You can
     use a loop like this to follow the prototype chain:
 
-    \snippet doc/src/snippets/code/src_script_QJSValueIterator.cpp 1
+    \snippet doc/src/snippets/code/src_script_qjsvalueiterator.cpp 1
 
     Note that QJSValueIterator will not automatically skip over
     properties that have the QJSValue::SkipInEnumeration flag set;
     that flag only affects iteration in script code.  If you want, you
     can skip over such properties with code like the following:
 
-    \snippet doc/src/snippets/code/src_script_QJSValueIterator.cpp 2
+    \snippet doc/src/snippets/code/src_script_qjsvalueiterator.cpp 2
 
     \sa QJSValue::property()
 */
@@ -90,7 +86,7 @@ QJSValueIterator::~QJSValueIterator()
     (i.e. the iterator is \e not at the back of the property sequence);
     otherwise returns false.
 
-    \sa next(), hasPrevious()
+    \sa next()
 */
 bool QJSValueIterator::hasNext() const
 {
@@ -101,11 +97,14 @@ bool QJSValueIterator::hasNext() const
 
 /*!
     Advances the iterator by one position.
+    Returns true if there is at least one item ahead of the iterator
+    (i.e. the iterator is \e not at the back of the property sequence);
+    otherwise returns false.
 
     Calling this function on an iterator located at the back of the
     container leads to undefined results.
 
-    \sa hasNext(), previous(), name()
+    \sa hasNext(), name()
 */
 bool QJSValueIterator::next()
 {
@@ -116,9 +115,9 @@ bool QJSValueIterator::next()
 
 /*!
     Returns the name of the last property that was jumped over using
-    next() or previous().
+    next().
 
-    \sa value(), flags()
+    \sa value()
 */
 QString QJSValueIterator::name() const
 {
@@ -130,9 +129,9 @@ QString QJSValueIterator::name() const
 
 /*!
     Returns the value of the last property that was jumped over using
-    next() or previous().
+    next().
 
-    \sa setValue(), name()
+    \sa name()
 */
 QJSValue QJSValueIterator::value() const
 {