Sprinkle docs about context properties with warnings and notes

We don't want people to use context properties. Warn about their effects
and offer singletons and object properties as alternatives.

Also, suggest object properties instead of context properties in the
page about exposing C++ attributes.

Fixes: QTBUG-113785
Change-Id: Id3fb6c7f26383838baeef2e696f8b1848b4e6fc6
Reviewed-by: Sami Shalayel <sami.shalayel@qt.io>
Reviewed-by: Semih Yavuz <semih.yavuz@qt.io>
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
(cherry picked from commit 2050db81ca59d5e7461f05200c4e76b68ef3d518)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
(cherry picked from commit fdf9c258af31c92324e069d47912abaa0d8c5467)

2 files changed, 43 insertions, 11 deletions

diff --git a/src/qml/doc/src/cppintegration/contextproperties.qdoc b/src/qml/doc/src/cppintegration/contextproperties.qdoc
index af9f4719e8..07022fd506 100644
--- a/src/qml/doc/src/cppintegration/contextproperties.qdoc
+++ b/src/qml/doc/src/cppintegration/contextproperties.qdoc
@@ -5,6 +5,22 @@
 \title Embedding C++ Objects into QML with Context Properties
 \brief Description of how to embed C++ data into QML using context properties
 
+\warning By using context properties in your QML code, you create a dependency from your QML code
+         to the specific context you have in mind when writing it. This limits re-usability of your
+         code since the context may be different in other places where it might be used.
+         Furthermore, the dependency is not declared. You never \c import the context or otherwise
+         state what you expect. Therefore, anyone trying to re-use your code will have difficulties
+         finding out whether the place of re-use has a context sufficient for your code.
+
+\warning Context properties are invisible to any tooling that processes QML code ahead of time,
+         before you load it into the QML engine. The \l{Qt Quick Compiler}, \l{qmllint}, and the
+         \l{QML Language Server} do not know anything about your context properties and will
+         consider any access to context properties as an \e{unqualified access}.
+
+\note Context properties can generally be replaced either by regular properties on the root object
+      of a component, or by singletons defined either in C++ using \l{QML_SINGLETON}{QML_SINGLETON}
+      or in QML using \l{qtqml-documents-definetypes.html#singleton}{pragma Singleton}.
+
 When loading a QML object into a C++ application, it can be useful to directly embed some C++ data
 that can be used from within the QML code. This makes it possible, for example, to invoke a C++
 method on the embedded object, or use a C++ object instance as a data model for a QML view.
diff --git a/src/qml/doc/src/cppintegration/exposecppattributes.qdoc b/src/qml/doc/src/cppintegration/exposecppattributes.qdoc
index 4f669eb124..6031d0eebb 100644
--- a/src/qml/doc/src/cppintegration/exposecppattributes.qdoc
+++ b/src/qml/doc/src/cppintegration/exposecppattributes.qdoc
@@ -91,7 +91,8 @@ Instead of:
 \badcode
 using FooEnum = Foo::Enum;
 
-class Bar : public QObject {
+class Bar : public QObject
+{
     Q_OBJECT
     Q_PROPERTY(FooEnum enum READ enum WRITE setEnum NOTIFY enumChanged)
 };
@@ -100,37 +101,46 @@ class Bar : public QObject {
 Refer to the type directly:
 
 \code
-class Bar : public QObject {
+class Bar : public QObject
+{
     Q_OBJECT
     Q_PROPERTY(Foo::Enum enum READ enum WRITE setEnum NOTIFY enumChanged)
 };
 \endcode
 
+In order to make \c Message available you need to use \l{QML_ELEMENT} in C++
+and \l{qt_add_qml_module} in CMake.
+
 \code
 class Message : public QObject
 {
     Q_OBJECT
+    QML_ELEMENT
     Q_PROPERTY(QString author READ author WRITE setAuthor NOTIFY authorChanged)
 public:
-    void setAuthor(const QString &a) {
+    void setAuthor(const QString &a)
+    {
         if (a != m_author) {
             m_author = a;
             emit authorChanged();
         }
     }
-    QString author() const {
+
+    QString author() const
+    {
         return m_author;
     }
+
 signals:
     void authorChanged();
+
 private:
     QString m_author;
 };
 \endcode
 
-If an instance of this class was \l{Embedding C++ Objects into QML with Context
-Properties}{set as a context property} when loading a file named \c MyItem.qml
-from C++:
+An instance of \c Message can be passed as required property to a file called
+\c MyItem.qml to make it available:
 
 \code
  int main(int argc, char *argv[]) {
@@ -138,7 +148,7 @@ from C++:
 
      QQuickView view;
      Message msg;
-     view.engine()->rootContext()->setContextProperty("msg", &msg);
+     view.setInitialProperties({{"msg", &msg}});
      view.setSource(QUrl::fromLocalFile("MyItem.qml"));
      view.show();
 
@@ -150,9 +160,11 @@ Then, the \c author property could be read from \c MyItem.qml:
 
 \qml
 // MyItem.qml
-import QtQuick 2.0
+import QtQuick
 
 Text {
+    required property Message msg
+
     width: 100; height: 100
     text: msg.author    // invokes Message::author() to get this value
 
@@ -389,6 +401,8 @@ that is a public slot:
  class MessageBoard : public QObject
  {
      Q_OBJECT
+     QML_ELEMENT
+
  public:
      Q_INVOKABLE bool postMessage(const QString &msg) {
          qDebug() << "Called the C++ method with" << msg;
@@ -402,7 +416,7 @@ that is a public slot:
  };
 \endcode
 
-If an instance of \c MessageBoard was set as the context data for a file \c
+If an instance of \c MessageBoard was set as the required property for a file \c
 MyItem.qml, then \c MyItem.qml could invoke the two methods as shown in the
 examples below:
 
@@ -416,7 +430,7 @@ examples below:
 
      MessageBoard msgBoard;
      QQuickView view;
-     view.engine()->rootContext()->setContextProperty("msgBoard", &msgBoard);
+     view.setInitialProperties({{"msgBoard", &msgBoard}});
      view.setSource(QUrl::fromLocalFile("MyItem.qml"));
      view.show();
 
@@ -431,6 +445,8 @@ examples below:
 import QtQuick 2.0
 
 Item {
+    required property MessageBoard msgBoard
+
     width: 100; height: 100
 
     MouseArea {