[geany/geany] 765000: plugins: Clarify which API functions may be called within geany_load_module()

[Thomas Martitz]

Branch:      refs/heads/master
Author:      Thomas Martitz <kugel at rockbox.org>
Committer:   Thomas Martitz <kugel at rockbox.org>
Date:        Sun, 23 Aug 2015 18:01:42 UTC
Commit:      765000be92262cb3395de82fa933511b6635c9be
             https://github.com/geany/geany/commit/765000be92262cb3395de82fa933511b6635c9be

Log Message:
-----------
plugins: Clarify which API functions may be called within geany_load_module()

Since geany_load_module() is called for non-enabled plugins you may not
use the plugin API here yet. The only exceptions to this rule are API functions
required for plugin registration.

This rule is hard to enforce (would need to g_return_if_val(PLUGIN_LOADED_OK(p))
for all API functions (well, those taking a plugin pointer anyway), so this
rule is only documented for now.


Modified Paths:
--------------
    doc/plugins.dox
    src/plugindata.h

Modified: doc/plugins.dox
3 lines changed, 3 insertions(+), 0 deletions(-)
===================================================================
@@ -37,6 +37,9 @@ This is the Geany API documentation. It should be considered work in progress.
 We will try to document as many functions and structs as possible.
 
 @warning Do not use any symbol not in the documentation - it may change.
+ at warning Except for exceptions stated in the documentation for geany_load_module(), no API function
+may be called if the plugin is not enabled (between the calls to their GeanyFuncs::init and
+GeanyFuncs::cleanup functions).
 
 @section pluginsupport Plugin Support
 - @link howto Plugin HowTo @endlink - get started


Modified: src/plugindata.h
8 lines changed, 8 insertions(+), 0 deletions(-)
===================================================================
@@ -275,6 +275,14 @@ void plugin_cleanup(void);
  *
  * For all glory details please read @ref howto.
  *
+ * Because the plugin is not yet enabled by the user you may not call plugin API functions inside
+ * this function, except for the API functions below which are required for proper registration.
+ *
+ * API functions which are allowed to be called within this function:
+ *  - main_locale_init()
+ *  - geany_plugin_register() (and GEANY_PLUGIN_REGISTER())
+ *  - geany_plugin_register_full() (and GEANY_PLUGIN_REGISTER_FULL())
+ *
  * @param plugin The unique plugin handle to your plugin. You must set some fields here.
  *
  * @since 1.26 (API 225)



--------------
This E-Mail was brought to you by github_commit_mail.py (Source: https://github.com/geany/infrastructure).