Start documenting coding conventions

Task-number: QT-2845

9 files changed, 308 insertions, 40 deletions

diff --git a/doc/src/declarative/codingconventions.qdoc b/doc/src/declarative/codingconventions.qdoc
new file mode 100644
index 0000000..ad2480f
--- /dev/null
+++ b/doc/src/declarative/codingconventions.qdoc
@@ -0,0 +1,131 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 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:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page codingconventions.html
+\title QML Coding Conventions
+
+This document contains the QML coding conventions that we follow in our documentation and examples and recommend that others follow.
+
+This page assumes that you are already familiar with the QML language.
+If you need an introduction to the language, please read \l {Introduction to the QML language}{the QML introduction} first.
+
+
+\section1 QML objects
+
+Through our documentation and examples, QML objects are always structured in the following order:
+
+\list
+\o id
+\o property declarations
+\o signal declarations
+\o javascript functions
+\o object properties
+\o child objects
+\o states
+\o transitions
+\endlist
+
+For better lisibility, we separate these different parts with an empty line.
+
+
+For example, a hypothetical \e photo QML object would look like this:
+
+\snippet doc/src/snippets/declarative/codingconventions/photo.qml 0
+
+
+\section1 Grouped properties
+
+If using multiple properties from a group of properties,
+we use the \e {group notation} rather than the \e {dot notation} to improve lisibility.
+
+For example, this:
+
+\snippet doc/src/snippets/declarative/codingconventions/dotproperties.qml 0
+
+can be written like this:
+
+\snippet doc/src/snippets/declarative/codingconventions/dotproperties.qml 1
+
+
+\section1 Lists
+
+If a list contains only one element, we generally omit the square brackets.
+
+For example, it is very common for a component to only have one state.
+
+In this case, instead of:
+
+\snippet doc/src/snippets/declarative/codingconventions/lists.qml 0
+
+we will write this:
+
+\snippet doc/src/snippets/declarative/codingconventions/lists.qml 1
+
+
+\section1 Javascript
+
+If the script is a single expression, we recommend writing it inline:
+
+\snippet doc/src/snippets/declarative/codingconventions/javascript.qml 0
+
+If the script is only a couple of lines long, we generally use a block:
+
+\snippet doc/src/snippets/declarative/codingconventions/javascript.qml 1
+
+If the script is more than a couple of lines long or can be used by different objects, we recommend creating a function and calling it like this:
+
+\snippet doc/src/snippets/declarative/codingconventions/javascript.qml 2
+
+For long scripts, we will put the functions in their own javascript file and import it like this:
+
+\snippet doc/src/snippets/declarative/codingconventions/javascript-imports.qml 0
+
+*/
+
+
+
+
+
+
+
+
+
diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc
index f310484..a4f4bc7 100644
--- a/doc/src/declarative/declarativeui.qdoc
+++ b/doc/src/declarative/declarativeui.qdoc
@@ -47,10 +47,10 @@
 highly dynamic, custom user interfaces.
 
 Qt Declarative UI provides a declarative framework for building highly dynamic, custom
-user interfaces.  Declarative UI helps programmers and designers collaborate to build 
-the animation rich, fluid user interfaces that are becoming common in portable 
-consumer devices, such as mobile phones, media players, set-top boxes and netbooks.  
-The Qt Declarative module provides an engine for interpreting the declarative QML 
+user interfaces.  Declarative UI helps programmers and designers collaborate to build
+the animation rich, fluid user interfaces that are becoming common in portable
+consumer devices, such as mobile phones, media players, set-top boxes and netbooks.
+The Qt Declarative module provides an engine for interpreting the declarative QML
 language, and a rich set of \l {QML Elements}{QML elements} that can be used
 from QML.
 
@@ -106,5 +106,6 @@ completely new applications.  QML is fully \l {Extending QML in C++}{extensible
 \o \l {QML Security}
 \o \l {QtDeclarative Module}
 \o \l {Debugging QML}
+\o \l {QML Coding Conventions}
 \endlist
 */
diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc
index 3544bc9..d2926f7 100644
--- a/doc/src/declarative/javascriptblocks.qdoc
+++ b/doc/src/declarative/javascriptblocks.qdoc
@@ -41,25 +41,25 @@
 
 /*!
 \page qdeclarativejavascript.html
-\title Integrating JavaScript 
+\title Integrating JavaScript
 
-QML encourages building UIs declaratively, using \l {Property Binding} and the 
+QML encourages building UIs declaratively, using \l {Property Binding} and the
 composition of existing \l {QML Elements}.  To allow the implementation of more
 advanced behavior, QML integrates tightly with imperative JavaScript code.
 
 The JavaScript environment provided by QML is stricter than that in a webbrowser.
 In QML you cannot add, or modify, members of the JavaScript global object.  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 
+QML this will throw an exception, so all local variables should be explicitly
 declared.
 
-In addition to the standard JavaScript properties, the \l {QML Global Object} 
+In addition to the standard JavaScript properties, the \l {QML Global Object}
 includes a number of helper methods that simplify building UIs and interacting
 with the QML environment.
 
 \section1 Inline JavaScript
 
-Small JavaScript functions can be written inline with other QML declarations.  
+Small JavaScript functions can be written inline with other QML declarations.
 These inline functions are added as methods to the QML element that contains
 them.
 
@@ -73,21 +73,21 @@ Item {
             return a * factorial(a - 1);
     }
 
-    MouseRegion {
+    MouseArea {
         anchors.fill: parent
         onClicked: print(factorial(10))
     }
 }
 \endcode
 
-As methods, inline functions on the root element in a QML component can be 
+As methods, inline functions on the root element in a QML component can be
 invoked by callers outside the component.  If this is not desired, the method
 can be added to a non-root element or, preferably, written in an external
 JavaScript file.
 
 \section1 Separate JavaScript files
 
-Large blocks of JavaScript should be written in separate files.  Like element 
+Large blocks of JavaScript should be written in separate files.  Like element
 types, external JavaScript files are \c {import}'ed into QML files.
 
 The \c {factorial()} method used in the \l {Inline JavaScript} section could
@@ -96,35 +96,35 @@ be refactored into an external file, and accessed like this.
 \code
 import "factorial.js" as MathFunctions
 Item {
-    MouseRegion {
+    MouseArea {
         anchors.fill: parent
         onClicked: print(MathFunctions.factorial(10))
     }
 }
 \endcode
 
-Both relative and absolute JavaScript URLs can be imported.  In the case of a 
-relative URL, the location is resolved relative to the location of the 
-\l {QML Document} that contains the import.  If the script file is not accessible, 
-an error will occur.  If the JavaScript needs to be fetched from a network 
-resource, the QML document will remain in the 
-\l {QDeclarativeComponent::status()}{waiting state} until the script has been 
+Both relative and absolute JavaScript URLs can be imported.  In the case of a
+relative URL, the location is resolved relative to the location of the
+\l {QML Document} that contains the import.  If the script file is not accessible,
+an error will occur.  If the JavaScript needs to be fetched from a network
+resource, the QML document will remain in the
+\l {QDeclarativeComponent::status()}{waiting state} until the script has been
 downloaded.
 
-Imported JavaScript files are always qualified using the "as" keyword.  The 
+Imported JavaScript files are always qualified using the "as" keyword.  The
 qualifier for JavaScript files must be unique, so there is always a one-to-one
 mapping between qualifiers and JavaScript files.
 
 \section2 Code-Behind Implementation Files
 
-Most JavaScript files imported into a QML file are stateful, logic implementations 
-for the QML file importing them.  In these cases, for QML component instances to 
-behave correctly each instance requires a separate copy of the JavaScript objects 
+Most JavaScript files imported into a QML file are stateful, logic implementations
+for the QML file importing them.  In these cases, for QML component instances to
+behave correctly each instance requires a separate copy of the JavaScript objects
 and state.
 
 The default behavior when importing JavaScript files is to provide a unique, isolated
-copy for each QML component instance.  The code runs in the same scope as the QML 
-component instance and consequently can can access and manipulate the objects and 
+copy for each QML component instance.  The code runs in the same scope as the QML
+component instance and consequently can can access and manipulate the objects and
 properties declared.
 
 \section2 Stateless JavaScript libraries
@@ -133,8 +133,8 @@ Some JavaScript files act more like libraries - they provide a set of stateless
 helper functions that take input and compute output, but never manipulate QML
 component instances directly.
 
-As it would be wasteful for each QML component instance to have a unique copy of 
-these libraries, the JavaScript programmer can indicate a particular file is a 
+As it would be wasteful for each QML component instance to have a unique copy of
+these libraries, the JavaScript programmer can indicate a particular file is a
 stateless library through the use of a pragma, as shown in the following example.
 
 \code
@@ -161,7 +161,7 @@ parameters.
 It is occasionally necessary to run some imperative code at application (or
 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 
+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 {QML JavaScript Restrictions} covers the exact limitations of global script code.
 
@@ -181,25 +181,25 @@ Rectangle {
 }
 \endcode
 
-Any element in a QML file - including nested elements and nested QML component 
-instances - can use this attached property.  If there is more than one onCompleted 
+Any element in a QML file - including nested elements and nested QML component
+instances - can use this attached property.  If there is more than one onCompleted
 handler to execute at startup, they are run sequentially in an undefined order.
 
-\section1 QML JavaScript Restrictions 
+\section1 QML JavaScript Restrictions
 
 QML executes standard JavaScript code, with the following restrictions:
 
 \list
 \o JavaScript code cannot modify the global object.
 
-In QML, the global object is constant - existing properties cannot be modified or 
+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, 
+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 
+Assuming that the \c a variable does not exist in the scope chain, the following code
 is illegal in QML.
 
 \code
@@ -217,18 +217,18 @@ 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, 
+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.
 
 \o 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 
+the global object.  That is, it will not have access to the QML objects and
 properties it \l {QML Scope}{normally would}.
 
-Global code that only accesses script local variable is permitted.  This is an 
+Global code that only accesses script local variable is permitted.  This is an
 example of valid global code.
 
 \code
@@ -242,8 +242,8 @@ Global code that accesses QML objects will not run correctly.
 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 
+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}.
 
 \endlist
diff --git a/doc/src/snippets/declarative/codingconventions/dotproperties.qml b/doc/src/snippets/declarative/codingconventions/dotproperties.qml
new file mode 100644
index 0000000..211cac1
--- /dev/null
+++ b/doc/src/snippets/declarative/codingconventions/dotproperties.qml
@@ -0,0 +1,28 @@
+import Qt 4.6
+
+Item {
+
+//! [0]
+Rectangle {
+    anchors.left: parent.left; anchors.top: parent.top; anchors.right: parent.right; anchors.leftMargin: 20
+}
+
+Text {
+    text: "hello"
+    font.bold: true; font.italic: true; font.pixelSize: 20; font.capitalization: Font.AllUppercase
+}
+
+//! [0]
+
+//! [1]
+Rectangle {
+    anchors { left: parent.left; top: parent.top; right: parent.right; leftMargin: 20 }
+}
+
+Text {
+    text: "hello"
+    font { bold: true; italic: true; pixelSize: 20; capitalization: Font.AllUppercase }
+}
+//! [1]
+
+}
diff --git a/doc/src/snippets/declarative/codingconventions/javascript-imports.qml b/doc/src/snippets/declarative/codingconventions/javascript-imports.qml
new file mode 100644
index 0000000..a216e1c
--- /dev/null
+++ b/doc/src/snippets/declarative/codingconventions/javascript-imports.qml
@@ -0,0 +1,7 @@
+import Qt 4.6
+
+//![0]
+import "myscript.js" as Script
+
+Rectangle { color: "blue"; width: Script.calculateWidth(parent) }
+//![0]
diff --git a/doc/src/snippets/declarative/codingconventions/javascript.qml b/doc/src/snippets/declarative/codingconventions/javascript.qml
new file mode 100644
index 0000000..ccb299b
--- /dev/null
+++ b/doc/src/snippets/declarative/codingconventions/javascript.qml
@@ -0,0 +1,33 @@
+import Qt 4.6
+
+Rectangle {
+
+//![0]
+Rectangle { color: "blue"; width: parent.width / 3 }
+//![0]
+
+//![1]
+Rectangle {
+    color: "blue"
+    width: {
+        var w = parent.width / 3
+        console.debug(w)
+        return w
+    }
+}
+//![1]
+
+//![2]
+function calculateWidth(object)
+{
+    var w = object.width / 3
+    // ...
+    // more javascript code
+    // ...
+    console.debug(w)
+    return w
+}
+
+Rectangle { color: "blue"; width: calculateWidth(parent) }
+//![2]
+}
diff --git a/doc/src/snippets/declarative/codingconventions/lists.qml b/doc/src/snippets/declarative/codingconventions/lists.qml
new file mode 100644
index 0000000..a08b61c
--- /dev/null
+++ b/doc/src/snippets/declarative/codingconventions/lists.qml
@@ -0,0 +1,22 @@
+import Qt 4.6
+
+Item {
+    Item {
+//! [0]
+states: [
+    State {
+        name: "open"
+        PropertyChanges { target: container; width: 200 }
+    }
+]
+//! [0]
+    }
+    Item {
+//! [1]
+ states: State {
+    name: "open"
+    PropertyChanges { target: container; width: 200 }
+}
+//! [1]
+    }
+}
diff --git a/doc/src/snippets/declarative/codingconventions/myscript.js b/doc/src/snippets/declarative/codingconventions/myscript.js
new file mode 100644
index 0000000..cfa6462
--- /dev/null
+++ b/doc/src/snippets/declarative/codingconventions/myscript.js
@@ -0,0 +1,9 @@
+function calculateWidth(parent)
+{
+    var w = parent.width / 3
+    // ...
+    // more javascript code
+    // ...
+    console.debug(w)
+    return w
+}
diff --git a/doc/src/snippets/declarative/codingconventions/photo.qml b/doc/src/snippets/declarative/codingconventions/photo.qml
new file mode 100644
index 0000000..3a59e1f
--- /dev/null
+++ b/doc/src/snippets/declarative/codingconventions/photo.qml
@@ -0,0 +1,37 @@
+import Qt 4.6
+
+//! [0]
+Rectangle {
+    id: photo                                               // id on the first line makes it easy to find an object
+
+    property bool thumbnail: false                          // property declarations
+    property alias image: photoImage.source
+
+    signal clicked                                          // signal declarations
+
+    function doSomething(x) {                               // javascript functions
+        return x + photoImage.width
+    }
+
+    x: 20; y: 20; width: 200; height: 150                   // object properties
+    color: "gray"                                           // try to group related properties together
+
+    Rectangle {                                             // child objects
+        id: border
+        anchors.centerIn: parent; color: "white"
+
+        Image { id: photoImage; anchors.centerIn: parent }
+    }
+
+    states: State {                                         // states
+        name: "selected"
+        PropertyChanges { target: border; color: "red" }
+    }
+
+    transitions: Transition {                               // transitions
+        from: ""; to: "selected"
+        ColorAnimation { target: border; duration: 200 }
+    }
+}
+//! [0]
+