From ebf1c7a9a529ca09b55e55fe603cebf2c2aaa8a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Fri, 4 Aug 2023 10:36:40 +0200 Subject: [PATCH] Trade: doc++ --- src/Magnum/Trade/AbstractImageConverter.h | 24 ++++++++++++------- src/Magnum/Trade/AbstractImporter.h | 15 ++++++------ src/Magnum/Trade/AbstractSceneConverter.h | 29 ++++++++++++++++------- 3 files changed, 44 insertions(+), 24 deletions(-) diff --git a/src/Magnum/Trade/AbstractImageConverter.h b/src/Magnum/Trade/AbstractImageConverter.h index c2c84d352..378ea4984 100644 --- a/src/Magnum/Trade/AbstractImageConverter.h +++ b/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 converter instance and neither on the dynamic plugin module. In other -words, you don't need to keep the converter instance (or the plugin manager -instance) around in order to have the `*Data` instances valid. Moreover, all -returned @relativeref{Corrade,Containers::Array} instances and -@relativeref{Corrade,Containers::Array} instances returned through -@ref ImageData are only allowed to have default deleters --- this is to avoid -potential dangling function pointer calls when destructing such instances after -the plugin module has been unloaded. +The @ref ImageData instances returned from various functions *by design* have +no dependency on the converter instance and neither on the dynamic plugin +module. In other words, you don't need to keep the converter instance (or the +plugin manager instance) around in order to have the @ref ImageData instances +valid. Moreover, all returned @relativeref{Corrade,Containers::Array} instances +returned either directly or through @ref ImageData are only allowed to have +default deleters --- this is to avoid potential dangling function pointer calls +when destructing such instances after 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 diff --git a/src/Magnum/Trade/AbstractImporter.h b/src/Magnum/Trade/AbstractImporter.h index 9654a742e..68026c58d 100644 --- a/src/Magnum/Trade/AbstractImporter.h +++ b/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 - called only if there is any file opened. + are called after the previous file was closed, @ref doClose() is called + 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 - * result in freed memory. This call is also done automatically when - * the importer gets destructed or when another file is opened. If no - * file is opened, does nothing. After this function is called, - * @ref isOpened() is guaranteed to return @cpp false @ce. + * On certain implementations an explicit call to this function when + * the file is no longer needed but the importer is going to be reused + * further may result in freed memory. This call is also done + * automatically when the importer gets destructed or when another file + * 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(); diff --git a/src/Magnum/Trade/AbstractSceneConverter.h b/src/Magnum/Trade/AbstractSceneConverter.h index 25b68b823..8ce895295 100644 --- a/src/Magnum/Trade/AbstractSceneConverter.h +++ b/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 converter instance and neither on the dynamic plugin module. In other -words, you don't need to keep the converter instance (or the plugin manager -instance) around in order to have the `*Data` instances valid. Moreover, all -@ref Corrade::Containers::Array instances returned through @ref MeshData and -others are only allowed to have default deleters --- this is to avoid potential -dangling function pointer calls when destructing such instances after the -plugin module has been unloaded. +The @ref MeshData instances returned from various functions *by design* have no +dependency on the converter instance and neither on the dynamic plugin module. +In other words, you don't need to keep the converter instance (or the plugin +manager instance) around in order to have the @ref MeshData instances valid. +Moreover, all @relativeref{Corrade,Containers::Array} instances returned either +directly or through @ref MeshData are only allowed to have default deleters --- +this is to avoid potential dangling function pointer calls when destructing +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