[Geany-Devel] Adding a plugin

[Roger Booth]

On 06/09/2013 03:42 AM, Lex Trotman wrote:
> [...]
>
>     From the Geany plugin website at
>     http://www.geany.org/manual/reference/plugindata_8h.html#a68c850fc7108c65909f4340da8c16df9
>
>     ====================================================
>     #define PLUGIN_VERSION_CHECK 	( 		api_required 	 ) 	
>
>     *Value:*
>
>     gintplugin_version_check  <http://www.geany.org/manual/reference/pluginsymbols_8c.html#a02238186945c26ea04e20410daf5b209>(gint abi_ver) \
>          { \
>              if  (abi_ver !=GEANY_ABI_VERSION  <http://www.geany.org/manual/reference/plugindata_8h.html#a81ace29a6d7fb7cce2b59100fe3f6d71>) \
>                  return  -1; \
>              return  (api_required); \
>          }
>
>     Defines a function to check the plugin is safe to load.
>
>     This performs runtime checks that try to ensure:
>
>       * Geany ABI data types are compatible with this plugin.
>       * Geany sources provide the required API for this plugin.
>
>         *Parameters:*
>
>             	/api_required/ 	The minimum API number your plugin
>             requires. Look at the source for the value of
>             |GEANY_API_VERSION| to use if you want your plugin to
>             require the current Geany version on your machine. You
>             should update this value when using any new API features.
>
>     ======================================================
>     The above documentation is crap.
>
>
> Which isn't a very helpful comment.
>
>
>
>     First, note that the macro definition describes the parameter as 
>     abi_ver. So, according to the documentation, where does the sole
>     parameter - abi_ver - come from?
>
>
> The macro is defining a function, so the parameter comes from the 
> caller of that function, ie Geany, so you don't need to know about it. 
> So it isn't described.
>
>
>     So we can skip the test
>         if(abi_ver blah blah)
>     unless somebody can answer the above question.
>
>
> The macro will generate the test, which *IS* required to prevent 
> plugins with the wrong ABI being used.  A plugin which uses the wrong 
> ABI may cause crashes, so if its wrong it will return -1 and Geany 
> will not run that plugin.  This is all transparent to you, the plugin 
> writer, just provide api_required to the macro.
>
>
>     So that leads to the last line of code that generates stuff:
>         return api_required;
>
>     I eliminated superfluous parens.
>
>     As documented, this macro returns what it is passed.
>
>
> Only *IF* the abi matches.
>
>
>     And you wonder why I'm confused?
>
>     BTW, this one is
>
>     *Since:*
>         0.19 
>
>
>
>
>
>     _______________________________________________
>     Devel mailing list
>     Devel at lists.geany.org <mailto:Devel at lists.geany.org>
>     https://lists.geany.org/cgi-bin/mailman/listinfo/devel
>
>
>
>
> _______________________________________________
> Devel mailing list
> Devel at lists.geany.org
> https://lists.geany.org/cgi-bin/mailman/listinfo/devel
I described exactly what the reader of your documentation would glean 
from reading said documentation. Who cares what is the implementation 
behind the documentation? Oh, I forget. You do. But me? I want to know 
how to use it.

I assume you are surprised by this. How dare the user of our docs not 
study to great lengths the implementations of the shit we (and others 
that have come before us) have produced. Nobody should have the 
effrontery to attempt to interface our code without spending a 
sufficient amount of time appreciating the edifice we have erected.

Sorry, I forgot to genuflect.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.geany.org/pipermail/devel/attachments/20130609/5ccd5a83/attachment-0001.html>