Text,Trade: doc++

src/Magnum/Text/AbstractFont.h

@@ -189,9 +189,10 @@ all glyphs in the font:
 @section Text-AbstractFont-usage-callbacks Loading data from memory, using file callbacks
 
 Besides loading data directly from the filesystem using @ref openFile() like
-shown above, it's possible to use @ref openData() to import data from memory.
+shown above, it's possible to use @ref openData() to load fonts from memory
-Note that the particular importer implementation must support
+(for example from @relativeref{Corrade,Utility::Resource}). Note that the
-@ref FontFeature::OpenData for this method to work.
+particular font implementation has to support @ref FontFeature::OpenData for
+this method to work:
 
 @snippet Text.cpp AbstractFont-usage-data
 
@@ -209,10 +210,10 @@ plugin supporting the callback feature handles that correctly.
 
 @snippet Text.cpp AbstractFont-usage-callbacks
 
-For importers that don't support @ref FontFeature::FileCallback directly, the
+For font plugins that don't support @ref FontFeature::FileCallback directly,
-base @ref openFile() implementation will use the file callback to pass the
+the base @ref openFile() implementation will use the file callback to pass the
-loaded data through to @ref openData(), in case the importer supports at least
+loaded data through to @ref openData(), in case the font supports at least
-@ref FontFeature::OpenData. If the importer supports neither
+@ref FontFeature::OpenData. If the font supports neither
 @ref FontFeature::FileCallback nor @ref FontFeature::OpenData,
 @ref setFileCallback() doesn't allow the callbacks to be set.
 
@@ -229,10 +230,12 @@ instance is destroyed.
 
 @section Text-AbstractFont-subclassing Subclassing
 
-The plugin needs to implement the @ref doFeatures(), @ref doClose(),
+The plugin needs to implement the @ref doFeatures(), @ref doIsOpened(),
-@ref doCreateShaper() functions, either @ref doCreateGlyphCache() or
+@ref doClose(), @ref doProperties(), @ref doGlyphIdsInto(), @ref doGlyphSize(),
-@ref doFillGlyphCache() and one or more of `doOpen*()` functions. See also
+@ref doGlyphAdvance(), @ref doCreateShaper() functions, either
-@ref AbstractShaper for more information.
+@ref doCreateGlyphCache() or @ref doFillGlyphCache() and at least one of the
+@ref doOpenData() or @ref doOpenFile() functions. See also @ref AbstractShaper
+for more information.
 
 In order to support @ref FontFeature::FileCallback, the font needs to properly
 use the callbacks to both load the top-level file in @ref doOpenFile() and also
@@ -359,8 +362,9 @@ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin {
          * It's expected that this function is called *before* a file is
          * opened. It's also expected that the loaded data are kept in scope
          * for as long as the font plugin needs them, based on the value of
-         * @ref InputFileCallbackPolicy. Documentation of particular importers
+         * @ref InputFileCallbackPolicy. Documentation of particular font
-         * provides more information about the expected callback behavior.
+         * plugins provides more information about the expected callback
+         * behavior.
          *
          * Following is an example of setting up a file loading callback for
          * fetching compiled-in resources from @ref Corrade::Utility::Resource.
@@ -840,7 +844,13 @@ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin {
          */
         virtual void doSetFileCallback(Containers::Optional<Containers::ArrayView<const char>>(*callback)(const std::string&, InputFileCallbackPolicy, void*), void* userData);
 
-        /** @brief Implementation for @ref isOpened() */
+        /**
+         * @brief Implementation for @ref isOpened()
+         *
+         * The function should return @cpp true @ce if a @ref doOpenFile()
+         * or @ref doOpenData() was successful and @ref doClose() wasn't called
+         * since, @cpp false @ce otherwise.
+         */
         virtual bool doIsOpened() const = 0;
 
         /**
@@ -884,7 +894,12 @@ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin {
         virtual Properties doOpenData(Containers::ArrayView<const char> data, Float size);
         #endif
 
-        /** @brief Implementation for @ref close() */
+        /**
+         * @brief Implementation for @ref close()
+         *
+         * The @ref doIsOpened() implementation should return @cpp false @ce
+         * after calling this function.
+         */
         virtual void doClose() = 0;
 
         /**

src/Magnum/Trade/AbstractImporter.h

@@ -1794,6 +1794,9 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi
         /**
          * @brief Implementation for @ref openFile()
          *
+         * If the operation was successful, @ref doIsOpened() should return
+         * @cpp true @ce after calling this function, @cpp false @ce otherwise.
+         *
          * If @ref ImporterFeature::OpenData is supported, default
          * implementation opens the file and calls @ref doOpenData() with its
          * contents. It is allowed to call this function from your
@@ -1838,13 +1841,22 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi
          */
         virtual void doSetFileCallback(Containers::Optional<Containers::ArrayView<const char>>(*callback)(const std::string&, InputFileCallbackPolicy, void*), void* userData);
 
-        /** @brief Implementation for @ref isOpened() */
+        /**
+         * @brief Implementation for @ref isOpened()
+         *
+         * The function should return @cpp true @ce if a @ref doOpenFile(),
+         * @ref doOpenData() or @ref doOpenState() was successful and
+         * @ref doClose() wasn't called since, @cpp false @ce otherwise.
+         */
         virtual bool doIsOpened() const = 0;
 
         /**
          * @brief Implementation for @ref openData() and @ref openMemory()
          * @m_since_latest
          *
+         * If the operation was successful, @ref doIsOpened() should return
+         * @cpp true @ce after calling this function, @cpp false @ce otherwise.
+         *
          * The @p data is mutable or owned depending on the value of
          * @p dataFlags. This can be used for example to avoid allocating a
          * local copy in order to preserve its lifetime. The following cases
@@ -1898,7 +1910,12 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi
         /** @brief Implementation for @ref openState() */
         virtual void doOpenState(const void* state, Containers::StringView filePath);
 
-        /** @brief Implementation for @ref close() */
+        /**
+         * @brief Implementation for @ref close()
+         *
+         * The @ref doIsOpened() implementation should return @cpp false @ce
+         * after calling this function.
+         */
         virtual void doClose() = 0;
 
         /**

src/Magnum/Trade/Data.h

@@ -103,7 +103,10 @@ MAGNUM_TRADE_EXPORT Debug& operator<<(Debug& debug, DataFlag value);
 @m_since{2020,06}
 
 @see @ref AnimationData::dataFlags(), @ref ImageData::dataFlags(),
-    @ref MeshData::indexDataFlags(), @ref MeshData::vertexDataFlags()
+    @ref MaterialData::attributeDataFlags(),
+    @ref MaterialData::layerDataFlags(), @ref MeshData::indexDataFlags(),
+    @ref MeshData::vertexDataFlags(), @ref SceneData::dataFlags(),
+    @ref AbstractImporter::doOpenData()
 */
 typedef Containers::EnumSet<DataFlag> DataFlags;