Doc: Move documentation about enumerations into a separate page

They are not, in fact, value types. Rather they are special properties
of other types and stored as the underlying type. Also, link the
documentation about both, defining enumerations in QML and defining
enumerations in C++ from that page.

Pick-to: 6.9 6.8 6.5
Fixes: QTBUG-89432
Change-Id: Ic73d7cea352a11c1d7699e655100aad078a77950
Reviewed-by: Olivier De Cannière <olivier.decanniere@qt.io>

src/qml/doc/src/cppintegration/data.qdoc

@@ -91,9 +91,6 @@ when passed from C++ to QML and vice-versa:
     \row
         \li QVector2D, QVector3D, QVector4D
         \li \l vector2d, \l vector3d, \l vector4d
-    \row
-        \li Enums declared with Q_ENUM()
-        \li \l enumeration
 \endtable
 
 \note Classes provided by the \l {Qt GUI} module, such as QColor, QFont,

src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc

@@ -142,8 +142,8 @@ Rectangle {
 
 \section4 Valid Types in Custom Property Definitions
 
-Any of the \l {QML Value Types} aside from the \l enumeration type can be used
+Any of the \l {QML Value Types} can be used as custom property types. For
-as custom property types. For example, these are all valid property declarations:
+example, these are all valid property declarations:
 
 \qml
 Item {
@@ -1153,7 +1153,8 @@ Text {
 }
 \endqml
 
-More information on enumeration usage in QML can be found in the \l {QML Value Types} \l enumeration documentation.
+More information on enumeration usage in QML can be found in the documentation on
+\l {Enumerations in QML}.
 
 The ability to declare enumerations in QML was introduced in Qt 5.10.
 

src/qml/doc/src/qmllanguageref/typesystem/enumerations.qdoc

@@ -0,0 +1,74 @@
+// Copyright (C) 2025 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+/*!
+\page qtqml-typesystem-enumerations.html
+\title Enumerations in QML
+\brief Description of QML Enumerations
+
+Enumerations used in QML can be defined either in QML or in C++.
+
+For information on defining enumerations in QML, see
+\l{QML Object Attributes#enumeration-attributes}{Enumeration Attributes}.
+
+When defined in C++, enumerations exposed to QML must be marked with the
+\l{Q_ENUM} or \l{Q_ENUM_NS} macros and be part of a type exposed to QML via the
+\l{QML_NAMED_ELEMENT} or \l{QML_ELEMENT} macros. For more details, see
+\l{Data Type Conversion Between QML and C++#enumeration-types}{Enumeration Types}.
+
+Only named QML types can hold enumerations usable in QML. Each enumeration must
+have a surrounding named type. \l{QML Namespaces} are also QML types and can hold
+enums.
+
+As a result, an enumeration value can be referred to as \c {<Type>.<Value>}. For
+example, the \l Text type has an \c AlignRight enumeration value:
+
+\qml
+Text { horizontalAlignment: Text.AlignRight }
+\endqml
+
+Enumeration values are properties of the type reference produced by the type
+name. You can also retrieve them using JavaScript’s square bracket syntax,
+though this is error-prone and not recommended:
+
+\qml
+// Avoid this if possible
+Text { horizontalAlignment: Text["AlignRight"] }
+\endqml
+
+\section1 Using Enumerations in QML
+
+Enumerations are not separate types in QML but are properties of their
+surrounding types. An enumeration value is represented as the underlying type of
+the enumeration. For most enumerations, it is safe to use JavaScript's
+\e Number type or QML's \e double type to store them. However, this does not
+always work for 64-bit integers, as their range exceeds the safe integer range
+of 64-bit doubles. Therefore, enumerations with values outside the safe integer
+range (-(2^53 - 1) to 2^53 - 1, inclusive) cannot be safely used in QML. For
+enumerations with values that fit into the numeric range of a 32-bit signed
+integer, you can safely use the QML \e int type as storage.
+
+For example:
+
+\qml
+import QtQuick
+
+Item {
+    // refer to Text.AlignRight using an int type
+    property int enumValue: textItem.horizontalAlignment
+
+    signal valueEmitted(int someValue)
+
+    Text {
+        id: textItem
+        horizontalAlignment: Text.AlignRight
+    }
+
+    // emit valueEmitted() signal, which expects an int, with Text.AlignRight
+    Component.onCompleted: valueEmitted(Text.AlignRight)
+}
+\endqml
+
+\sa {QML Value Types}
+\sa {QML Object Attributes#enumeration-attributes}{Enumeration Attributes}
+\sa {Data Type Conversion Between QML and C++#enumeration-types}{Enumeration Types}
+*/

src/qml/doc/src/qmllanguageref/typesystem/topic.qdoc

@@ -53,6 +53,13 @@ See the documentation about
 \l{qtqml-typesystem-sequencetypes.html}{sequence types in the QML type system}
 for in-depth information about sequence types.
 
+\section1 Enumerations
+
+Enumerations are treated as special properties of types in QML.
+
+See the the documentation about \l{QML Enumerations} for in-depth
+information about enumerations.
+
 \section1 QML Namespaces
 
 QML Namespaces can be used to expose enumerations from C++ namespaces.

src/qml/doc/src/qmllanguageref/typesystem/valuetypes.qdoc

@@ -47,7 +47,6 @@ document, with the following exceptions:
 \list
   \li \c void, which marks the absence of a value
   \li \c list must be used in conjunction with an object or value type as element
-  \li \c enumeration cannot be used directly as the enumeration must be defined by a registered QML object type
 \endlist
 
 \section2 Built-in Value Types Provided By The QML Language
@@ -556,60 +555,3 @@ property is only invoked when the property is reassigned to a different object v
 
    \sa {QML Value Types}
 */
-
-/*!
-    \qmlvaluetype enumeration
-    \ingroup qmlvaluetypes
-    \brief a named enumeration value.
-
-    The \c enumeration type refers to a named enumeration value.
-
-    Each named value can be referred to as \c {<Type>.<value>}. For
-    example, the \l Text type has an \c AlignRight enumeration value:
-
-    \qml
-    Text { horizontalAlignment: Text.AlignRight }
-    \endqml
-
-    (For backwards compatibility, the enumeration value may also be
-    specified as a string, e.g. "AlignRight". This form is not
-    recommended for new code.)
-
-    When integrating with C++, note that any \c enum value
-    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
-    converted into an \c enumeration value, and vice-versa.
-
-    This value type is provided by the QML language.  Some enumeration values
-    are provided by the QtQuick import.
-
-    \section1 Using the enumeration Type in QML
-
-    The \c enumeration type is a representation of a C++ \c enum type. It is
-    not possible to refer to the \c enumeration type in QML itself; instead, the
-    \l int or \l var types can be used when referring to \c enumeration values
-    from QML code.
-
-    For example:
-
-    \qml
-    import QtQuick 2.0
-
-    Item {
-        // refer to Text.AlignRight using an int type
-        property int enumValue: textItem.horizontalAlignment
-
-        signal valueEmitted(int someValue)
-
-        Text {
-            id: textItem
-            horizontalAlignment: Text.AlignRight
-        }
-
-        // emit valueEmitted() signal, which expects an int, with Text.AlignRight
-        Component.onCompleted: valueEmitted(Text.AlignRight)
-    }
-    \endqml
-
-    \sa {QML Value Types}
-    \sa {qtqml-syntax-objectattributes.html#enumeration-attributes}{Enumeration Attributes}
-*/

src/qml/doc/src/qtqml-toc.qdoc

@@ -22,6 +22,7 @@
                 \li \l{QML Value Types}
                 \li \l{QML Object Types}
                 \li \l{QML Sequence Types}
+                \li \l{QML Enumerations}
                 \li \l{QML Namespaces}
                 \endlist
             \li \l{QML Modules}

src/quick/doc/src/qmltypereference.qdoc

@@ -205,15 +205,15 @@ available when you import \c QtQuick.
     The following properties are also available:
 
     \list
-    \li \l enumeration \c font.weight
+    \li \l {Enumerations in QML}{enumeration} \c font.weight
     \li \l bool \c font.overline
     \li \l bool \c font.strikeout
-    \li \l enumeration \c font.capitalization
+    \li \l {Enumerations in QML}{enumeration} \c font.capitalization
     \li \l real \c font.letterSpacing
     \li \l real \c font.wordSpacing
     \li \l bool \c font.kerning
     \li \l bool \c font.preferShaping
-    \li \l enumeration \c font.hintingPreference
+    \li \l {Enumerations in QML}{enumeration} \c font.hintingPreference
     \li \c object \l [QML] {QtQuick::Text::}{font.features}
     \li \l string \c font.styleName
     \li \c object \c [QML] {QtQuick::Text::}{font.variableAxes}

src/quick/util/qquickforeignutils.cpp

@@ -40,7 +40,7 @@ QT_BEGIN_NAMESPACE
    \li \l point \c eventPoint.scenePosition: see also \l QEventPoint::scenePosition
    \li \l ulong \c eventPoint.pressTimestamp: see also \l QEventPoint::pressTimestamp
    \li \l point \c eventPoint.scenePressPosition: see also \l QEventPoint::scenePressPosition
-   \li \l enumeration \c eventPoint.state: see also \l QEventPoint::state
+   \li \l {QML Enumerations}{enumeration} \c eventPoint.state: see also \l QEventPoint::state
    \li \l real \c eventPoint.timeHeld: see also \l QEventPoint::timeHeld
    \li \l ulong \c eventPoint.timestamp: see also \l QEventPoint::timestamp
    \li \l pointingDeviceUniqueId \c eventPoint.uniqueId: see also \l QEventPoint::uniqueId