1 files changed, 25 insertions, 5 deletions
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.
 */