Trade: doc++

src/Magnum/Trade/AbstractImageConverter.h

@@ -569,15 +569,21 @@ details and a usage example.
 
 @section Trade-AbstractImageConverter-data-dependency Data dependency
 
-The instances returned from various functions *by design* have no dependency on
+The @ref ImageData instances returned from various functions *by design* have
-the converter instance and neither on the dynamic plugin module. In other
+no dependency on the converter instance and neither on the dynamic plugin
-words, you don't need to keep the converter instance (or the plugin manager
+module. In other words, you don't need to keep the converter instance (or the
-instance) around in order to have the `*Data` instances valid. Moreover, all
+plugin manager instance) around in order to have the @ref ImageData instances
-returned @relativeref{Corrade,Containers::Array} instances and
+valid. Moreover, all returned @relativeref{Corrade,Containers::Array} instances
-@relativeref{Corrade,Containers::Array} instances returned through
+returned either directly or through @ref ImageData are only allowed to have
-@ref ImageData are only allowed to have default deleters --- this is to avoid
+default deleters --- this is to avoid potential dangling function pointer calls
-potential dangling function pointer calls when destructing such instances after
+when destructing such instances after the plugin module has been unloaded.
-the plugin module has been unloaded.
+
+Some converter implementations may point @ref ImageData::importerState() to
+some internal state in the converter instance, but in that case the relation is
+* *weak* --- these will be valid only as long as the particular converter
+documents, usually either until the next conversion is performed or until the
+converter is destroyed. After that, the state pointers become dangling, and
+that's fine as long as you don't access them.
 
 @section Trade-AbstractImageConverter-subclassing Subclassing
 

src/Magnum/Trade/AbstractImporter.h

@@ -410,8 +410,8 @@ You don't need to do most of the redundant sanity checks, these things are
 checked by the implementation:
 
 -   The @ref doOpenData(), @ref doOpenFile() and @ref doOpenState() functions
-    are called after the previous file was closed, function @ref doClose() is
+    are called after the previous file was closed, @ref doClose() is called
-    called only if there is any file opened.
+    only if there is any file opened.
 -   The @ref doOpenData() function is called only if
     @ref ImporterFeature::OpenData is supported.
 -   The @ref doOpenState() function is called only if
@@ -725,11 +725,12 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi
         /**
          * @brief Close currently opened file
          *
-         * On particular implementations an explicit call to this function may
+         * On certain implementations an explicit call to this function when
-         * result in freed memory. This call is also done automatically when
+         * the file is no longer needed but the importer is going to be reused
-         * the importer gets destructed or when another file is opened. If no
+         * further may result in freed memory. This call is also done
-         * file is opened, does nothing. After this function is called,
+         * automatically when the importer gets destructed or when another file
-         * @ref isOpened() is guaranteed to return @cpp false @ce.
+         * is opened. If no file is opened, does nothing. After this function
+         * is called, @ref isOpened() is guaranteed to return @cpp false @ce.
          */
         void close();
 

src/Magnum/Trade/AbstractSceneConverter.h

@@ -709,14 +709,27 @@ duplicates from all meshes before saving them to the output:
 
 @section Trade-AbstractSceneConverter-data-dependency Data dependency
 
-The instances returned from various functions *by design* have no dependency on
+The @ref MeshData instances returned from various functions *by design* have no
-the converter instance and neither on the dynamic plugin module. In other
+dependency on the converter instance and neither on the dynamic plugin module.
-words, you don't need to keep the converter instance (or the plugin manager
+In other words, you don't need to keep the converter instance (or the plugin
-instance) around in order to have the `*Data` instances valid. Moreover, all
+manager instance) around in order to have the @ref MeshData instances valid.
-@ref Corrade::Containers::Array instances returned through @ref MeshData and
+Moreover, all @relativeref{Corrade,Containers::Array} instances returned either
-others are only allowed to have default deleters --- this is to avoid potential
+directly or through @ref MeshData are only allowed to have default deleters ---
-dangling function pointer calls when destructing such instances after the
+this is to avoid potential dangling function pointer calls when destructing
-plugin module has been unloaded.
+such instances after the plugin module has been unloaded.
+
+In comparison, the @ref AbstractImporter instances returned from @ref end()
+have a code dependency on the dynamic plugin module --- since their
+implementation is in the plugin module itself, the plugin can't be unloaded
+until the returned instance is destroyed. They don't have a data dependency on
+the converter instance however, so they can outlive it.
+
+Some converter implementations may point @ref MeshData::importerState() to some
+internal state in the converter instance, but in that case the relation is
+* *weak* --- these will be valid only as long as the particular converter
+documents, usually either until the next conversion is performed or until the
+converter is destroyed. After that, the state pointers become dangling, and
+that's fine as long as you don't access them.
 
 @section Trade-AbstractSceneConverter-subclassing Subclassing