diff options
author | Chris Adams <christopher.adams@nokia.com> | 2012-05-28 17:12:56 +1000 |
---|---|---|
committer | Qt by Nokia <qt-info@nokia.com> | 2012-06-21 09:58:56 +0200 |
commit | 5e33b0f580d2b20f1a2989bf2ee8dde4525a2e39 (patch) | |
tree | 780d25ce7d8955e56ea985a35dd84609df12fbf0 /src/quick/doc/src/appdevguide/codingconventions.qdoc | |
parent | 03342a435a88656d64d1445991a4421d244fcb45 (diff) |
Create new documentation structure
The documentation currently has no clear separation between Qt QML
and Qt Quick. With recent commits like:
6c8378eaf1edbbefe6aaa3672b0127816a004fd7
and
ab1e510121c8a679fdaca12ccd30e0f7ac12a26b
the separation between the language definition and implementation,
provided by Qt QML, and the standard library for the QML language,
provided by Qt Quick, is clear.
This commit creates a new documentation structure that is more
navigable and separates concepts into logical categories, with
clear separation between QtQML and QtQuick. It also provides a more
generic QML Application Developer Resources page which contains links
to information for QML application developers.
Change-Id: Ia807ccfbfd24ffa0e1c7f0a51ed9d2ed3aa6a733
Reviewed-by: Martin Jones <martin.jones@nokia.com>
Diffstat (limited to 'src/quick/doc/src/appdevguide/codingconventions.qdoc')
-rw-r--r-- | src/quick/doc/src/appdevguide/codingconventions.qdoc | 126 |
1 files changed, 126 insertions, 0 deletions
diff --git a/src/quick/doc/src/appdevguide/codingconventions.qdoc b/src/quick/doc/src/appdevguide/codingconventions.qdoc new file mode 100644 index 0000000000..89a1bd8cb3 --- /dev/null +++ b/src/quick/doc/src/appdevguide/codingconventions.qdoc @@ -0,0 +1,126 @@ +/**************************************************************************** +** +** 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-coding-conventions.html +\title QML Coding Conventions +\brief code style convention + +This document contains the QML coding conventions that we follow in our documentation and examples and recommend that others follow. + +\section1 QML Objects + +Through our documentation and examples, QML objects are always structured in the following order: + +\list +\li id +\li property declarations +\li signal declarations +\li JavaScript functions +\li object properties +\li child objects +\li states +\li transitions +\endlist + +For better readability, we separate these different parts with an empty line. + + +For example, a hypothetical \e photo QML object would look like this: + +\snippet qml/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 readability. + +For example, this: + +\snippet qml/codingconventions/dotproperties.qml 0 + +can be written like this: + +\snippet qml/codingconventions/dotproperties.qml 1 + + +\section1 Private Properties + +QML and JavaScript do not enforce private properties like C++. There is a need +to hide these private properties, for example, when the properties are part of +the implementation. As a convention, private properties begin with two +\e underscore characters. For example, \c __area, is a property that is +accessible but is not meant for public use. Note that QML and JavaScript will +grant the user access to these properties. + +\snippet qml/codingconventions/private.qml 0 + + +\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 qml/codingconventions/lists.qml 0 + +we will write this: + +\snippet qml/codingconventions/lists.qml 1 + + +\section1 JavaScript Code + +If the script is a single expression, we recommend writing it inline: + +\snippet qml/codingconventions/javascript.qml 0 + +If the script is only a couple of lines long, we generally use a block: + +\snippet qml/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 qml/codingconventions/javascript.qml 2 + +For long scripts, we will put the functions in their own JavaScript file and import it like this: + +\snippet qml/codingconventions/javascript-imports.qml 0 + +*/ + + + + + + + + + |