PluginManager: doc++

doc/plugin-management.dox

@@ -48,20 +48,22 @@ compiled and managed.
 Plugin interface is a class with virtual methods, defining the way how to work
 with a particular plugin.
 
-Every plugin interface must be derived from @ref PluginManager::AbstractPlugin
-and must reimplement the
+Every plugin interface has to be derived from @ref PluginManager::AbstractPlugin
+and reimplement the
 @ref PluginManager::AbstractPlugin::AbstractPlugin(PluginManager::AbstractManager&, const std::string&)
 constructor. This is needed for instance use checks, as described above. Plugin
-classes derived from that interface must reimplement the constructor too, of
+classes derived from that interface need to reimplement the constructor too, of
 course.
 
-Additionaly, an interface string must be provided by a @cpp pluginInterface() @ce
-function to make sure loaded plugins depend on the same interface in the same
-version. The macro takes a string which uniquely names that particular
-interface. A good practice is to use "Java package name"-style syntax because
-this makes the name as unique as possible. The interface name should also
-contain version identifier to make sure the plugin will not be loaded with
-incompatible interface version.
+Additionaly, an interface string should be provided by overriding the
+@ref PluginManager::AbstractPlugin::pluginInterface() function in order to have
+an additional safety check for interface compatibility. The macro takes a
+string which uniquely names that particular interface. A good practice is to
+use "Java package name"-style syntax because this makes the name as unique as
+possible. The interface name should also contain a version identifier to make
+sure the plugin will not be loaded with incompatible interface version. If this
+function is not overriden, the default implementation returns @cpp "" @ce and
+effectively makes the interface compatibility check a no-op.
 
 To make lives of the users easier, we can define a list of paths where the
 plugins will be searched for using
@@ -80,9 +82,9 @@ would need to pass a plugin search path to the plugin manager constructor.
 @section plugin-management-plugin Plugin definition
 
 Every plugin is represented by a class derived from a particular plugin
-interface. The plugin class in then registered as a static or dynamic plugin.
-Every plugin must also have its metadata file, which contains information
-about plugin dependencies and optionally also plugin-specific data. Full
+interface. The plugin class is then registered as a static or a dynamic plugin.
+Every plugin also needs to have an associated metadata file, which contains
+information about plugin dependencies and optionally also plugin-specific data. Full
 specification of plugin metadata file syntax can be found in the
 @ref PluginManager::PluginMetadata class documentation.
 

src/Corrade/PluginManager/AbstractManager.h

@@ -494,28 +494,28 @@ of application exection. It's also safe to call this macro more than once.
 #define CORRADE_PLUGIN_VERSION 6
 
 /** @hideinitializer
-@brief Register static or dynamic lugin
-@param name          Name of static plugin (equivalent of dynamic plugin
+@brief Register a static or dynamic plugin
+@param name          Name of the static plugin (equivalent of dynamic plugin
      filename)
 @param className     Plugin class name
 @param interface     Interface name (the same as is defined by the
     @ref Corrade::PluginManager::AbstractPlugin::pluginInterface() "pluginInterface()"
     member of given plugin class)
 
-If the plugin is built as **static** (using CMake command
-@ref corrade-cmake-add-static-plugin "corrade_add_static_plugin()"), registers
-it, so it will be loaded automatically when PluginManager instance with
-corresponding interface is created. When building as static plugin,
+If the plugin is built as **static** (using the CMake
+@ref corrade-cmake-add-static-plugin "corrade_add_static_plugin()" command),
+registers it, so it will be loaded automatically when PluginManager instance
+with corresponding interface is created. When building as static plugin,
 `CORRADE_STATIC_PLUGIN` preprocessor directive is defined.
 
-If the plugin is built as **dynamic** (using CMake command
-@ref corrade-cmake-add-plugin "corrade_add_plugin()"), registers it, so it can
-be dynamically loaded via @ref Corrade::PluginManager::Manager by supplying a
-name of the plugin. When building as dynamic plugin, `CORRADE_DYNAMIC_PLUGIN`
-preprocessor directive is defined.
+If the plugin is built as **dynamic** (using the CMake
+@ref corrade-cmake-add-plugin "corrade_add_plugin()" command), registers it, so
+it can be dynamically loaded via @ref Corrade::PluginManager::Manager by
+supplying a name of the plugin. When building as dynamic plugin,
+`CORRADE_DYNAMIC_PLUGIN` preprocessor directive is defined.
 
 If the plugin is built as dynamic or static **library or executable** (not as
-plugin, using e.g. CMake command @cmake add_library() @ce /
+a plugin, using e.g. CMake command @cmake add_library() @ce /
 @cmake add_executable() @ce), this macro won't do anything to prevent linker
 issues when linking more plugins together. No plugin-related preprocessor
 directive is defined.