1 files changed, 166 insertions, 0 deletions
diff --git a/doc/src/qml/debugging.qdoc b/doc/src/qml/debugging.qdoc
new file mode 100644
index 0000000000..520e23abb5
--- /dev/null
+++ b/doc/src/qml/debugging.qdoc
@@ -0,0 +1,166 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+\page qml-debugging.html
+\ingroup qtquick-tools
+\title Debugging QML
+\brief debugging tools in QML
+
+\section1 Console API
+
+\section2 Log
+
+\c console.log, console.debug, console.info, console.warn and console.error can be used to print
+debugging information to the console. For example:
+
+\code
+function f(a, b) {
+  console.log("a is ", a, "b is ", b);
+}
+\endcode
+
+The output is generated using the qDebug, qWarning, qCritical methods in C++
+(see also http://doc.qt.nokia.com/latest/debug.html#warning-and-debugging-messages).
+
+\hint Setting the environment variable QML_CONSOLE_EXTENDED also prints the source
+code location of the call.
+
+\section2 Assert
+
+\c console.assert tests that an expression is true. If not, it will write an optional message
+to the console and print the stack trace.
+
+\qml
+function f() {
+  var x = 12
+  console.assert(x == 12, "This will pass");
+  console.assert(x > 12, "This will fail");
+}
+\endqml
+
+\section2 Timer
+
+\c console.time and console.timeEnd log the time (in milliseconds) that was spent between
+the calls. Both take a string argument that identifies the measurement. For example:
+
+\code
+function f() {
+    console.time("wholeFunction");
+    console.time("firstPart");
+    // first part
+    console.timeEnd("firstPart");
+    // second part
+    console.timeEnd("wholeFunction");
+}
+\endcode
+
+\section2 Trace
+
+\c console.trace prints the stack trace of JavaScript execution at the point where
+it was called. The stack trace info contains function name, file name, line number
+and column number. The stack trace is limited to last 10 stack frames.
+
+\section2 Count
+
+\c console.count prints the current number of times a particular piece of code has been executed,
+along with a message. That is,
+
+\qml
+function f() {
+  console.count("f called");
+}
+\endqml
+
+will print \c{f called: 1}, \c{f called: 2} ... whenever \c{f()} is executed.
+
+\section2 Profile
+
+\c console.profile turns on the QML and JavaScript profilers. Nested calls are not
+supported and a warning will be printed to the console.
+
+\c console.profileEnd turns off the QML and JavaScript profilers. Calling this function
+without a previous call to console.profile will print a warning to the console. A
+profiling client should have been attached before this call to receive and store the
+profiling data. For example:
+
+\code
+function f() {
+    console.profile();
+    //Call some function that needs to be profiled.
+    //Ensure that a client is attached before ending
+    //the profiling session.
+    console.profileEnd();
+}
+\endcode
+
+\section2 Exception
+
+\c console.exception prints an error message together with the stack trace of JavaScript
+execution at the point where it is called.
+
+\section1 Debugging Transitions
+
+When a transition doesn't look quite right, it can be helpful to view it in slow
+motion to see what is happening more clearly. This functionality is supported
+in the \l {QML Viewer} tool: to enable this,
+click on the "Debugging" menu, then "Slow Down Animations".
+
+
+\section1 Debugging module imports
+
+The \c QML_IMPORT_TRACE environment variable can be set to enable debug output
+from QML's import loading mechanisms.
+
+For example, for a simple QML file like this:
+
+\qml
+import QtQuick 2.0
+
+Rectangle { width: 100; height: 100 }
+\endqml
+
+If you set \c {QML_IMPORT_TRACE=1} before running the \l {QML Viewer}
+(or your QML C++ application), you will see output similar to this:
+
+\code
+QDeclarativeImportDatabase::addImportPath "/qt-sdk/imports"
+QDeclarativeImportDatabase::addImportPath "/qt-sdk/bin/QMLViewer.app/Contents/MacOS"
+QDeclarativeImportDatabase::addToImport 0x106237370 "." -1.-1 File as ""
+QDeclarativeImportDatabase::addToImport 0x106237370 "Qt" 4.7 Library as ""
+QDeclarativeImportDatabase::resolveType "Rectangle" = "QDeclarativeRectangle"
+\endcode
+
+
+\section1 Debugging with Qt Creator
+
+\l{http://qt.nokia.com/products/developer-tools}{Qt Creator} provides built-in
+support for QML debugging. QML projects and standalone C++ applications that
+utilize QML can be debugged on desktops as well as on remote devices.
+For more information, see the Qt Creator Manual.
+
+*/