Improve GeanyProxyProbeResults a litte (#1213)

* Add GEANY_ prefix to enumerators.
* Use a discrete set of enumerators so the proxy doesn't have to
  worry about flag bitmasks, which isn't required.
* Update documentation.
* Use the new enumerators in Geany.
* Improve debug output for bogus values a bit.

doc/plugins.dox

@@ -768,9 +768,8 @@ done in the GeanyPluginFuncs::init function of the proxy plugin.
  - GeanyProxyFuncs::probe may be implemented to probe if a plugin candidate (that has one of the
    provided file extensions) is actually a plugin. This may depend on the plugin file itself in
    case of ambiguity or availability of runtime dependencies or even configuration.
-   @ref PROXY_IGNORED or @ref PROXY_MATCHED should be returned, possibly in combination
-   with the @ref PROXY_NOLOAD flag. Not implementing GeanyProxyFuncs::probe at all is equivalent to
-   always returning @ref PROXY_MATCHED.
+   @ref GeanyProxyProbeResults constants should be returned. Not implementing GeanyProxyFuncs::probe
+   at all is equivalent to always returning @ref GEANY_PROXY_MATCH.
  - GeanyProxyFuncs::load must be implemented to actually load the plugin. It is called by Geany
    when the user enables the sub-plugin. What "loading" means is entirely up to the proxy plugin and
    probably depends on the interpreter of the dynamic language that shall be supported. After
@@ -807,9 +806,9 @@ Consider the 5 basic cases:
 1) A candidate comes with a suitable file extension but is not a workable plugin file at all. For
 example, your proxy supports plugins written in a shell script (.sh) but the shebang of that script
 points to an incompatible shell (or even lacks a shebang). You should check for this in
-GeanyProxyFuncs::probe() and return @ref PROXY_IGNORED which hides that script from the Plugin
+GeanyProxyFuncs::probe() and return @ref GEANY_PROXY_IGNORE which hides that script from the Plugin
 Manager and allows other enabled proxy plugins to pick it up. GeanyProxyFuncs::probe() returning
-@ref PROXY_IGNORED is an indication that the candidate is meant for another proxy, or the user
+@ref GEANY_PROXY_IGNORE is an indication that the candidate is meant for another proxy, or the user
 placed the file by accident in one of Geany's plugin directories. In other words the candidate
 simply doesn't correspond to your proxy. Thus any noise by debug messages for this case is
 undesirable.
@@ -817,7 +816,7 @@ undesirable.
 2) A proxy plugin provides its own, versioned API to sub-plugin. The API version of the sub-plugin
 is not compatible with the API exposed by the proxy. GeanyProxyFuncs::probe() should never perform
 a version check because its sole purpose is to indicate a proxy's correspondence to a given
-candidate. It should return @ref PROXY_MATCHED instead. Later, Geany will invoke the
+candidate. It should return @ref GEANY_PROXY_MATCH instead. Later, Geany will invoke the
 GeanyProxyFuncs::load(), and this function is the right place for a version check. If it fails then
 you simply do not call GEANY_PLUGIN_REGISTER(), but rather print a debug message. The result is
 that the sub-plugin is not shown in the Plugin Manager at all. This is consistent with the
@@ -967,7 +966,7 @@ static gint demoproxy_probe(GeanyPlugin *proxy, const gchar *filename, gpointer
 			match = utils_str_equal(linebuf, "#!!PROXY_MAGIC!!\n");
 		fclose(f);
 	}
-	return match ? PROXY_MATCHED : PROXY_IGNORED;
+	return match ? GEANY_PROXY_MATCH : GEANY_PROXY_IGNORE;
 }
 @endcode
 

plugins/demoproxy.c

@@ -116,7 +116,7 @@ static gint demoproxy_probe(GeanyPlugin *proxy, const gchar *filename, gpointer
 			match = utils_str_equal(linebuf, "#!!PROXY_MAGIC!!\n");
 		fclose(f);
 	}
-	return match ? PROXY_MATCHED : PROXY_IGNORED;
+	return match ? GEANY_PROXY_MATCH : GEANY_PROXY_IGNORE;
 }
 
 

src/plugindata.h

@@ -59,7 +59,7 @@ G_BEGIN_DECLS
  * @warning You should not test for values below 200 as previously
  * @c GEANY_API_VERSION was defined as an enum value, not a macro.
  */
-#define GEANY_API_VERSION 228
+#define GEANY_API_VERSION 229
 
 /* hack to have a different ABI when built with GTK3 because loading GTK2-linked plugins
  * with GTK3-linked Geany leads to crash */
@@ -340,32 +340,45 @@ void geany_plugin_set_data(GeanyPlugin *plugin, gpointer data, GDestroyNotify fr
 	                           (min_api_version), GEANY_ABI_VERSION, (pdata), (free_func))
 
 /** Return values for GeanyProxyHooks::probe()
- *
- * Only @c PROXY_IGNORED, @c PROXY_MATCHED or @c PROXY_MATCHED|PROXY_NOLOAD
- * are valid return values.
  *
  * @see geany_plugin_register_proxy() for a full description of the proxy plugin mechanisms.
- *
- * @since 1.26 (API 226)
  */
 typedef enum
 {
+	/** @deprecated Use GEANY_PROXY_IGNORE instead.
+	 * @since 1.26 (API 226)
+	 */
+	PROXY_IGNORED,
+	/** @deprecated Use GEANY_PROXY_MATCH instead.
+	 * @since 1.26 (API 226)
+	 */
+	PROXY_MATCHED,
+	/** @deprecated Use GEANY_PROXY_RELATED instead.
+	 * @since 1.26 (API 226)
+	 */
+	PROXY_NOLOAD = 0x100,
 	/** The proxy is not responsible at all, and Geany or other plugins are free
 	 * to probe it.
+	 *
+	 * @since 1.29 (API 229)
 	 **/
-	PROXY_IGNORED,
-	/** The proxy is responsible for this file, and creates a plugin for it */
-	PROXY_MATCHED,
-
-	/** The proxy is does not directly load it, but it's still tied to the proxy
+	GEANY_PROXY_IGNORE = PROXY_IGNORED,
+	/** The proxy is responsible for this file, and creates a plugin for it.
+	 *
+	 * @since 1.29 (API 229)
+	 */
+	GEANY_PROXY_MATCH = PROXY_MATCHED,
+	/** The proxy is does not directly load it, but it's still tied to the proxy.
 	 *
 	 * This is for plugins that come in multiple files where only one of these
 	 * files is relevant for the plugin creation (for the PM dialog). The other
 	 * files should be ignored by Geany and other proxies. Example: libpeas has
 	 * a .plugin and a .so per plugin. Geany should not process the .so file
 	 * if there is a corresponding .plugin.
+	 *
+	 * @since 1.29 (API 229)
 	 */
-	PROXY_NOLOAD = 0x100,
+	GEANY_PROXY_RELATED = PROXY_MATCHED | PROXY_NOLOAD
 }
 GeanyProxyProbeResults;
 
@@ -379,7 +392,7 @@ GeanyProxyProbeResults;
 struct GeanyProxyFuncs
 {
 	/** Called to determine whether the proxy is truly responsible for the requested plugin.
-	 * A NULL pointer assumes the probe() function would always return @ref PROXY_MATCHED */
+	 * A NULL pointer assumes the probe() function would always return @ref GEANY_PROXY_MATCH */
 	gint		(*probe)     (GeanyPlugin *proxy, const gchar *filename, gpointer pdata);
 	/** Called after probe(), to perform the actual job of loading the plugin */
 	gpointer	(*load)      (GeanyPlugin *proxy, GeanyPlugin *subplugin, const gchar *filename, gpointer pdata);

src/plugins.c

@@ -1038,19 +1038,22 @@ static PluginProxy* is_plugin(const gchar *file)
 		if (utils_str_casecmp(ext, proxy->extension) == 0)
 		{
 			Plugin *p = proxy->plugin;
-			gint ret = PROXY_MATCHED;
+			gint ret = GEANY_PROXY_MATCH;
 
 			if (p->proxy_cbs.probe)
 				ret = p->proxy_cbs.probe(&p->public, file, p->cb_data);
 			switch (ret)
 			{
-				case PROXY_MATCHED:
+				case GEANY_PROXY_MATCH:
 					return proxy;
-				case PROXY_MATCHED|PROXY_NOLOAD:
+				case GEANY_PROXY_RELATED:
 					return NULL;
+				case GEANY_PROXY_IGNORE:
+					continue;
 				default:
-					if (ret != PROXY_IGNORED)
-						g_warning("Ignoring bogus return from proxy probe!\n");
+					g_warning("Ignoring bogus return value '%d' from "
+						"proxy plugin '%s' probe() function!", ret,
+						proxy->plugin->info.name);
 					continue;
 			}
 		}