Improve QML basic types documentation

Basic types are provided either by the language (int, string, bool,
real, double, date, url, var, variant) or by modules (value types).
In 5.1 we would like modules to be able to provide more basic types,
and thus a cleaner separation of the documentation makes sense.

This patch also improves linking of the term QtQml so that a clear
distinction is made between the QtQml QML module and the QtQml C++
Qt Module (the QtQml QML module links now point to the QtQml type
reference page).

Change-Id: Ibe3ad33e4616c5f29ea38dadc27e13938aedb9d7
Reviewed-by: Bea Lam <bea.lam@nokia.com>

1 files changed, 22 insertions, 416 deletions

diff --git a/src/qml/doc/src/typesystem/basictypes.qdoc b/src/qml/doc/src/typesystem/basictypes.qdoc
index 176a56a3cf..0f66112b3c 100644
--- a/src/qml/doc/src/typesystem/basictypes.qdoc
+++ b/src/qml/doc/src/typesystem/basictypes.qdoc
@@ -49,14 +49,31 @@ Basic types can be used to refer to:
 
 \section1 Supported Basic Types
 
-Most basic types are supported by the engine by default and do not require an
-\l {Import Statements}{Import Statement} to be used, unlike QML object types.
-Some basic types which contain multiple property-value pairs (also known as \c{value types})
-do require an import, as they are provided by the QtQuick module.
-The basic types supported in QML are listed below:
+Some basic types are supported by the engine by default and do not require an
+\l {Import Statements}{import statement} to be used, while others do require
+the client to import the module which provides them.
+All of the basic types listed below may be used as a \c property type in a QML
+document, with the following exceptions:
+\list
+  \li \c list must be used in conjunction with a QML object type
+  \li \c enumeration cannot be used directly as the enumeration must be defined by a registered QML object type
+\endlist
 
+\section2 Basic Types Provided By The QML Language
+
+The basic types supported natively in the QML language are listed below:
 \annotatedlist qmlbasictypes
 
+\section2 Basic Types Provided By QML Modules
+
+QML modules may extend the QML language with more basic types.
+For example, the basic types provided by the QtQuick module are listed below:
+\annotatedlist qtquickbasictypes
+
+Currently only QML modules which are provided by Qt may provide their
+own basic types, however this may change in future releases of Qt QML.
+In order to use types provided by a particular QML module, clients
+must import that module in their QML documents.
 
 \section1 Property Change Behavior for Basic Types
 
@@ -289,311 +306,6 @@ property is only invoked when the property is reassigned to a different object v
     \sa {QML Basic Types}
 */
 
-/*!
-    \qmlbasictype color
-    \ingroup qmlbasictypes
-    \brief an ARGB color value.
-    \target qmlbasictypecolor
-
-    The \c color type refers to an ARGB color value. It can be specified in a number of ways:
-
-    \list
-    \li By a \l{http://www.w3.org/TR/SVG/types.html#ColorKeywords}{SVG color name}, such as
-        "red", "green" or "lightsteelblue".
-    \li By a hexadecimal triplet or quad in the form \c "#RRGGBB" and \c "#AARRGGBB"
-        respectively. For example, the color red corresponds to a triplet of \c "#FF0000"
-        and a slightly transparent blue to a quad of \c "#800000FF".
-    \li Using the \l{QML:Qt::rgba()}{Qt.rgba()}, \l{QML:Qt::hsla()}{Qt.hsla()},
-        \l{QML:Qt::darker()}{Qt.darker()}, \l{QML:Qt::lighter()}{Qt.lighter()} or
-        \l{QML:Qt::tint()}{Qt.tint()} functions.
-    \endlist
-
-    Example:
-
-    \div{float-right}
-    \inlineimage declarative-colors.png
-    \enddiv
-    \snippet qml/colors.qml colors
-
-    Additionally, a color type has \c r, \c g, \c b and \c a properties that refer to the
-    red, green, blue and alpha values of the color, respectively:
-
-    \qml
-    Text {
-        color: "red"
-
-        // prints "1 0 0 1"
-        Component.onCompleted: console.log(color.r, color.g, color.b, color.a)
-    }
-    \endqml
-
-    To test color values for equality, use the \l{QML:Qt::colorEqual()}{Qt.colorEqual()}
-    function.  This allows colors to be accurately compared whether they are in property
-    form or in any of the acceptable string specification forms.
-
-    When integrating with C++, note that any QColor value
-    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
-    converted into a \c color value, and vice-versa.
-
-    This basic type is provided by the QtQuick import.
-
-    \sa {QML Basic Types}
-*/
-
-/*!
-    \qmlbasictype point
-    \ingroup qmlbasictypes
-    \brief a value with x and y attributes.
-
-    The \c point type refers to a value with \c x and \c y attributes.
-
-    To create a \c point value, specify it as a "x,y" string:
-
-    \qml
-    CustomObject { myPointProperty: "0,20" }
-    \endqml
-
-    Or use the \l{QML:Qt::point()}{Qt.point()} function:
-
-    \qml
-    CustomObject { myPointProperty: Qt.point(0, 20) }
-    \endqml
-
-    When integrating with C++, note that any QPoint or QPointF value
-    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
-    converted into a \c point value. When a \c point value is passed to C++, it
-    is automatically converted into a QPointF value.
-
-    This basic type is provided by the QML language.
-
-    \sa {QML Basic Types}
-*/
-
-/*!
-    \qmlbasictype size
-    \ingroup qmlbasictypes
-    \brief a value with width and height attributes
-
-    The \c size type refers to a value with has \c width and \c height attributes.
-
-    For example, to read the \c width and \c height values of the
-    \l {Image::sourceSize} size-type property:
-
-    \qml
-    Column {
-        Image { id: image; source: "logo.png" }
-        Text { text: image.sourceSize.width + "," + image.sourceSize.height }
-    }
-    \endqml
-
-    To create a \c size value, specify it as a "width x height" string:
-
-    \qml
-    Image { sourceSize: "150x50" }
-    \endqml
-
-    Or use the \l{QML:Qt::size()}{Qt.size()} function:
-
-    \qml
-    Image { sourceSize: Qt.size(150, 50) }
-    \endqml
-
-    When integrating with C++, note that any QSize or QSizeF value
-    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
-    converted into a \c size value, and vice-versa. When a \c size value is passed to C++, it
-    is automatically converted into a QSizeF value.
-
-    This basic type is provided by the QML language.
-
-    \sa {QML Basic Types}
-*/
-
-/*!
-    \qmlbasictype rect
-    \ingroup qmlbasictypes
-    \brief a value with x, y, width and height attributes.
-
-    The \c rect type refers to a value with \c x, \c y, \c width and \c height attributes.
-
-    For example, to read the \c width and \c height values of the \l Item
-    \l {Item::}{childrenRect} rect-type type property:
-
-    \qml
-    Rectangle {
-        width: childrenRect.width
-        height: childrenRect.height
-
-        Rectangle { width: 100; height: 100 }
-    }
-    \endqml
-
-    To create a \c rect value, specify it as a "x, y, width x height" string:
-
-    \qml
-    CustomObject { myRectProperty: "50,50,100x100" }
-    \endqml
-
-    Or use the \l{QML:Qt::rect()}{Qt.rect()} function:
-
-    \qml
-    CustomObject { myRectProperty: Qt.rect(50, 50, 100, 100) }
-    \endqml
-
-    When integrating with C++, note that any QRect or QRectF value
-    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
-    converted into a \c rect value, and vice-versa. When a \c rect value is passed to C++, it
-    is automatically converted into a QRectF value.
-
-    This basic type is provided by the QML language.
-
-    \sa {QML Basic Types}
-*/
-
-/*!
-    \qmlbasictype date
-    \ingroup qmlbasictypes
-    \brief a date value.
-
-    The \c date type refers to a date value.
-
-    To create a \c date value, specify it as a "YYYY-MM-DD" string:
-
-    \qml
-    MyDatePicker { minDate: "2000-01-01"; maxDate: "2020-12-31" }
-    \endqml
-
-    To read a date value returned from a C++ extension class, use
-    \l{QML:Qt::formatDate()}{Qt.formatDate()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}.
-
-    When integrating with C++, note that any QDate value
-    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
-    converted into a \c date value, and vice-versa.
-
-    Note that the date type has comparison semantics which match
-    those of the JavaScript Date object.  To compare the value
-    of two date properties, you should compare their "toString()"
-    values.
-
-    This basic type is provided by the QML language.
-
-    \sa {QML Basic Types}
-*/
-
-/*!
-    \qmlbasictype time
-    \ingroup qmlbasictypes
-    \brief a time value.
-
-    The \c time type refers to a time value.
-
-    To create a \c time value, specified as "hh:mm:ss":
-
-    \qml
-    MyTimePicker { time: "14:22:15" }
-    \endqml
-
-    To read a time value returned from a C++ extension class, use
-    \l{QML:Qt::formatTime()}{Qt.formatTime()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}.
-
-    Note that when converting historical times to and from javascript that QDateTime and the JS Date object
-    have different methods of calculating historical daylight savings time application. This can lead to variations of one hour
-    when converting to historical local time.
-
-    When integrating with C++, note that any QTime value
-    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
-    converted into a \c time value, and vice-versa.
-
-    This basic type is provided by the QML language.
-
-    \sa {QML Basic Types}
- */
-
-/*!
-    \qmlbasictype font
-    \ingroup qmlbasictypes
-    \brief a font value with the properties of QFont.
-    \target fontbasictypedocs
-
-    The \c font type refers to a font value with the properties of QFont.
-
-    The most commonly used properties are:
-
-    \list
-    \li \l string \c font.family
-    \li \l bool \c font.bold
-    \li \l bool \c font.italic
-    \li \l bool \c font.underline
-    \li \l real \c font.pointSize
-    \li \l int \c font.pixelSize
-    \endlist
-
-    If both \c pointSize and a \c pixelSize are specified, \c pixelSize will be used.
-
-    The following properties are also available:
-
-    \list
-    \li \l enumeration \c font.weight
-    \li \l bool \c font.overline
-    \li \l bool \c font.strikeout
-    \li \l enumeration \c font.capitalization
-    \li \l real \c font.letterSpacing
-    \li \l real \c font.wordSpacing
-    \endlist
-
-    Example:
-    \qml
-    Text { font.family: "Helvetica"; font.pointSize: 13; font.bold: true }
-    \endqml
-
-    When integrating with C++, note that any QFont value
-    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
-    converted into a \c font value, and vice-versa.
-
-    This basic type is provided by the QtQuick import.
-
-    Font weighting is classified on a scale from 0 to 99, where a weight of 0 is ultralight,
-    and 99 is extremely black. The following values are supported:
-
-    \table
-    \row
-        \li \c Font.Light
-        \li 25
-    \row
-        \li \c Font.Normal
-        \li 50
-    \row
-        \li \c Font.DemiBold
-        \li 63
-    \row
-        \li \c Font.Bold
-        \li 75
-    \row
-        \li \c Font.Black
-        \li 87
-    \endtable
-
-    Capitalization supports the following values:
-
-    \table
-    \row
-        \li \c Font.MixedCase
-        \li No capitalization change is applied.
-    \row
-        \li \c Font.AllUppercase
-        \li Alters the text to be rendered in all uppercase type.
-    \row
-        \li \c Font.AllLowercase
-        \li Alters the text to be rendered in all lowercase type.
-    \row
-        \li \c Font.SmallCaps
-        \li Alters the text to be rendered in small-caps type.
-    \row
-        \li \c Font.Capitalize
-        \li Alters the text to be rendered with the first character of each word as an uppercase character.
-    \endtable
-
-    \sa {QML Basic Types}
-*/
 
 /*!
     \qmlbasictype list
@@ -906,112 +618,6 @@ property is only invoked when the property is reassigned to a different object v
 */
 
 /*!
-    \qmlbasictype vector2d
-    \ingroup qmlbasictypes
-
-    \brief A vector2d type has x and y attributes.
-
-    A \c vector2d type has \c x and \c y attributes, otherwise
-    it is similar to the \c vector3d type.  Please see the
-    documentation about the \c vector3d type for more information.
-
-    To create a \c vector2d value, specify it as a "x,y" string,
-    or define the components individually, or compose it with
-    the Qt.vector2d() function.
-
-    This basic type is provided by the QtQuick import.
-
-    \sa {QML Basic Types}
-*/
-
-/*!
-    \qmlbasictype vector3d
-    \ingroup qmlbasictypes
-    \brief a value with x, y, and z attributes.
-
-    The \c vector3d type refers to a value with \c x, \c y, and \c z attributes.
-
-    To create a \c vector3d value, specify it as a "x,y,z" string:
-
-    \qml
-    Rotation { angle: 60; axis: "0,1,0" }
-    \endqml
-
-    or with the \l{QML:Qt::vector3d()}{Qt.vector3d()} function:
-
-    \qml
-    Rotation { angle: 60; axis: Qt.vector3d(0, 1, 0) }
-    \endqml
-
-    or as separate \c x, \c y, and \c z components:
-
-    \qml
-    Rotation { angle: 60; axis.x: 0; axis.y: 1; axis.z: 0 }
-    \endqml
-
-    When integrating with C++, note that any QVector3D value
-    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
-    converted into a \c vector3d value, and vice-versa.
-
-    This basic type is provided by the QtQuick import.
-
-    \sa {QML Basic Types}
-*/
-
-/*!
-    \qmlbasictype vector4d
-    \ingroup qmlbasictypes
-
-    \brief A vector4d type has x, y, z and w attributes.
-
-    A \c vector4d type has \c x, \c y, \c z and \c w attributes,
-    otherwise it is similar to the \c vector3d type.  Please see the
-    documentation about the \c vector3d type for more information.
-
-    To create a \c vector4d value, specify it as a "x,y,z,w" string,
-    or define the components individually, or compose it with
-    the Qt.vector4d() function.
-
-    This basic type is provided by the QtQuick import.
-
-    \sa {QML Basic Types}
-*/
-
-/*!
-    \qmlbasictype quaternion
-    \ingroup qmlbasictypes
-
-    \brief A quaternion type has scalar, x, y, and z attributes.
-
-    A \c quaternion type has \c scalar, \c x, \c y and \c z attributes,
-    otherwise it is similar to the \c vector3d type.  Please see the
-    documentation about the \c vector3d type for more information.
-
-    To create a \c quaternion value, specify it as a "scalar,x,y,z" string,
-    or define the components individually, or compose it with
-    the Qt.quaternion() function.
-
-    This basic type is provided by the QtQuick import.
-
-    \sa {QML Basic Types}
-*/
-
-/*!
-    \qmlbasictype matrix4x4
-    \ingroup qmlbasictypes
-
-    \brief A matrix4x4 type is a 4-row and 4-column matrix
-
-    A \c matrix4x4 type has sixteen values, but these values are
-    largely opaque to QML.  Values of this type can be composed with
-    the Qt.matrix4x4() function.
-
-    This basic type is provided by the QtQuick import.
-
-    \sa {QML Basic Types}
-*/
-
-/*!
     \qmlbasictype enumeration
     \ingroup qmlbasictypes
     \brief a named enumeration value.