@b4n commented on this pull request.

Minor nitpicks, but looks pretty good now I'd say 👍

In doc/plugins.dox:

> +   Geany built-in functionality.
+
+When the plugin returns @c TRUE from the function assigned to the @c _provided
+member of @c PluginExtension, it indicates
+it wants to take control of the particular feature and disable Geany's
+implementation. However, returning @c TRUE does not automatically guarantee that
+the plugin's implementation is executed - if there are multiple plugins competing
+for implementing a feature, the extension with the highest priority
+passed into the @c plugin_extension_register() function gets executed.
+
+A plugin can perform a check if it gets executed for the
+particular feature; e.g. for autocompletion the plugin can use
+@c plugin_extension_autocomplete_provided() which returns @c TRUE if the
+passed extension is executed, taking into account all registered extension
+priorities and the return values of all functions assigned to
+@c autocomplete_provided members of the registered extensions.

Maybe give a short example on when this is useful, just like in plugin_extension_autocomplete_provided()'s documentation?

"This can be used if the plugin needs to perform auxiliary actions outside the _perform() function, to verify it is actually active for this feature."

In plugins/demopluginext.c:

> + * cd plugins
+ * make demopluginext.so

Just maybe, just makes it a single command which could make it easier to use

- * cd plugins
- * make demopluginext.so
+ * make -C plugins demopluginext.so

This said, it has to run in the build directory anyway… but people using OOT builds probably know how to deal with that.

In plugins/demopluginext.c:

> + *
+ * Then copy or symlink the plugins/demopluginext.so file to ~/.config/geany/plugins
+ * - it will be loaded at next startup.
+ */
+
+#include <geanyplugin.h>
+
+static gboolean autocomplete_provided(GeanyDocument *doc, gpointer data)
+{
+    return doc->file_type->id == GEANY_FILETYPES_PYTHON;
+}
+
+
+static void autocomplete_perform(GeanyDocument *doc, gboolean force, gpointer data)
+{
+    const gchar *kwd_str = "False None True and as assert async await break case class continue def del elif else except finally for from global if import in is lambda match nonlocal not or pass raise return try while with yield";

It really doesn't matter, but why not having an array directly?

In src/pluginextension.c:

> +static gint sort_extension_entries(gconstpointer a, gconstpointer b)
+{
+	const PluginExtensionEntry *entry_a = a;
+	const PluginExtensionEntry *entry_b = b;
+
+	return entry_b->priority - entry_a->priority;
+}
+
+
+/**
+ * Registers the provided extension in Geany. There can be multiple extensions
+ * registered in Geany - these are sorted by the priority
+ * parameter. When executing functions assigned to the @c PluginExtension
+ * members ending with @c _perform, Geany goes
+ * through the registered extensions and executes the @c _perform() function of
+ * the first extension for whih the function assigned to the corresponding

- * the first extension for whih the function assigned to the corresponding
+ * the first extension for which the function assigned to the corresponding

In src/pluginextension.c:

> +	const PluginExtensionEntry *entry_b = b;
+
+	return entry_b->priority - entry_a->priority;
+}
+
+
+/**
+ * Registers the provided extension in Geany. There can be multiple extensions
+ * registered in Geany - these are sorted by the priority
+ * parameter. When executing functions assigned to the @c PluginExtension
+ * members ending with @c _perform, Geany goes
+ * through the registered extensions and executes the @c _perform() function of
+ * the first extension for whih the function assigned to the corresponding
+ * @c _provided member returns @c TRUE.
+ * 
+ * This function is typically called in the plugin @c init() function.

- * This function is typically called in the plugin @c init() function.
+ * This function is typically called in the plugin's @c init() function.

In src/pluginextension.c:

> +	PluginExtensionEntry *entry;
+
+	g_return_if_fail(ext_name != NULL);
+
+	entry = g_malloc(sizeof *entry);
+	entry->extension = extension;
+	entry->data = data;
+	entry->priority = priority;
+
+	all_extensions = g_list_insert_sorted(all_extensions, entry, sort_extension_entries);
+}
+
+
+/**
+ * Plugins are responsible for calling this function when they no longer
+ * provide the extension, at the latest in the plugin @c cleanup() function.

- * provide the extension, at the latest in the plugin @c cleanup() function.
+ * provide the extension, at the latest in the plugin's @c cleanup() function.

In src/pluginextension.h:

> + * functions can be left to contain the NULL pointer.
+ * 
+ * Typically, functions from this interface come in pairs. Functins ending with
+ * @c _provided() inform Geany whether the plugin implements the given feature
+ * for the passed document. Functions ending with @c _perform() are called by
+ * Geany at appropriate moments to inform the plugin when to perform the given
+ * feature.
+ * 
+ * Instances of the @c PluginExtension structures are registered in Geany using
+ * the @c plugin_extension_register() function.
+ * 
+ * @warning The API provided by this file is subject to change and should not be
+ * considered stable at this point. That said, it is highly probable that if
+ * a change of this API is required in the future, it will not be of a major
+ * nature and should not require major modifications of the affected plugins
+ * (e.g. added/modified parameter of a function and similar changes).

@elextr I expect it would eventually, but it would be nice to see if it fits more real use cases first.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.Message ID: <geany/geany/pull/3849/review/2148297946@github.com>