Clarify use of Q_INIT_RESOURCE

The Q_INIT_RESOURCE macro is needed if a library itself uses resources, in
which case the Q_INIT_RESOURCE can and should happen in the library (like
we do for eg. widget styles), or if a library exposes resources that are
supposed to be used by the library clients, in which case the macro needs
to be put in the application code.

The distinction between the two, and the fact that resources built as part
of the main executable do not need the explicit initialization, were not
all that clear.

This was evident by the lack of Q_INIT_RESOURCE in our own Qt libraries,
and the various Q_INIT_RESOURCE calls in our examples where they are not
needed.

Change-Id: I40258458e9fdf9ee5502c212971fb3d90b4fc388
Reviewed-by: Simon Hausmann <simon.hausmann@digia.com>

3 files changed, 43 insertions, 10 deletions

diff --git a/src/corelib/doc/snippets/code/doc_src_resources.cpp b/src/corelib/doc/snippets/code/doc_src_resources.cpp
index 482c25a222..8ac7b0e970 100644
--- a/src/corelib/doc/snippets/code/doc_src_resources.cpp
+++ b/src/corelib/doc/snippets/code/doc_src_resources.cpp
@@ -44,11 +44,24 @@ QResource::registerResource("/path/to/myresource.rcc");
 
 
 //! [5]
+MyClass::MyClass() : BaseClass()
+{
+    Q_INIT_RESOURCE(resources);
+
+    QFile file("qrc:/myfile.dat");
+    ...
+}
+//! [5]
+
+
+//! [6]
 int main(int argc, char *argv[])
 {
     QApplication app(argc, argv);
     Q_INIT_RESOURCE(graphlib);
+
+    QFile file("qrc:/graph.png");
     ...
     return app.exec();
 }
-//! [5]
+//! [6]
diff --git a/src/corelib/doc/src/resource-system.qdoc b/src/corelib/doc/src/resource-system.qdoc
index 5ef6bb285c..4c24320851 100644
--- a/src/corelib/doc/src/resource-system.qdoc
+++ b/src/corelib/doc/src/resource-system.qdoc
@@ -184,15 +184,35 @@
     path list is empty at startup; call QDir::addSearchPath() to
     add paths to it.
 
-    If you have resources in a static library, you might need to
-    force initialization of your resources by calling \l
-    Q_INIT_RESOURCE() with the base name of the \c .qrc file. For
-    example:
+    \section1 Using Resources in a Library
+
+    If you have resources in a library, you need to force initialization
+    of your resources by calling \l Q_INIT_RESOURCE() with the base name
+    of the \c .qrc file. For example:
 
     \snippet code/doc_src_resources.cpp 5
 
+    This ensures that the resources are linked into the final application
+    binary in the case of static linking. You should put the initialization
+    code close to where the resources are used in your library, so that
+    clients of your library will only link in the resources if they use
+    the feature of the library that depends on them.
+
+    If the library includes resources that are not used internally, but
+    instead exposed to clients of the library, the initialization needs
+    to happen in the application code. For example:
+
+    \snippet code/doc_src_resources.cpp 6
+
+    As before, this ensures that the resources are linked into the final
+    application binary in the case of static linking, but also triggers
+    loading of the library in the case of dynamic linking, such as plugins.
+
     Similarly, if you must unload a set of resources explicitly
     (because a plugin is being unloaded or the resources are not valid
     any longer), you can force removal of your resources by calling
-    Q_CLEANUP_RESOURCE() with the same base name as above.
+    \l Q_CLEANUP_RESOURCE() with the same base name as above.
+
+    Note: The use of \l Q_INIT_RESOURCE() and \l Q_CLEANUP_RESOURCE() is
+    not necessary when the resource is built as part of the application.
 */
diff --git a/src/corelib/io/qdir.cpp b/src/corelib/io/qdir.cpp
index 148ae5b202..0c65817557 100644
--- a/src/corelib/io/qdir.cpp
+++ b/src/corelib/io/qdir.cpp
@@ -2205,10 +2205,10 @@ QStringList QDir::nameFiltersFromString(const QString &nameFilter)
     \relates QDir
 
     Initializes the resources specified by the \c .qrc file with the
-    specified base \a name. Normally, Qt resources are loaded
-    automatically at startup. The Q_INIT_RESOURCE() macro is
-    necessary on some platforms for resources stored in a static
-    library.
+    specified base \a name. Normally, when resources are built as part
+    of the application, the resources are loaded automatically at
+    startup. The Q_INIT_RESOURCE() macro is necessary on some platforms
+    for resources stored in a static library.
 
     For example, if your application's resources are listed in a file
     called \c myapp.qrc, you can ensure that the resources are