<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div class="moz-cite-prefix">On 06/09/2013 03:42 AM, Lex Trotman
wrote:<br>
</div>
<blockquote
cite="mid:CAKhWKDM2gycOr2btO-i0XX+kZY2K8NK9sBV21ConvAZR_M8ZrQ@mail.gmail.com"
type="cite">
<div dir="ltr">[...]<br>
<div class="gmail_extra">
<div class="gmail_quote">
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<div bgcolor="#FFFFFF" text="#000000"> From the Geany
plugin website at<br>
<a moz-do-not-send="true"
href="http://www.geany.org/manual/reference/plugindata_8h.html#a68c850fc7108c65909f4340da8c16df9"
target="_blank">http://www.geany.org/manual/reference/plugindata_8h.html#a68c850fc7108c65909f4340da8c16df9</a><br>
<br>
====================================================<br>
<table>
<tbody>
<tr>
<td>#define PLUGIN_VERSION_CHECK</td>
<td>(</td>
<td> </td>
<td>api_required</td>
<td> ) </td>
<td><br>
</td>
</tr>
</tbody>
</table>
<b>Value:</b>
<div>
<pre>gint <a moz-do-not-send="true" href="http://www.geany.org/manual/reference/pluginsymbols_8c.html#a02238186945c26ea04e20410daf5b209" title="Use the PLUGIN_VERSION_CHECK() macro instead." target="_blank">plugin_version_check</a>(gint abi_ver) \
{ \
<span>if</span> (abi_ver != <a moz-do-not-send="true" href="http://www.geany.org/manual/reference/plugindata_8h.html#a81ace29a6d7fb7cce2b59100fe3f6d71" title="The Application Binary Interface (ABI) version, incremented whenever existing fields in the plugin da..." target="_blank">GEANY_ABI_VERSION</a>) \
<span>return</span> -1; \
<span>return</span> (api_required); \
}
</pre>
</div>
<p>Defines a function to check the plugin is safe to
load. </p>
<p>This performs runtime checks that try to ensure:</p>
<ul>
<li>Geany ABI data types are compatible with this
plugin.</li>
<li>Geany sources provide the required API for this
plugin.
<dl>
<dt><b>Parameters:</b></dt>
<dd>
<table border="0" cellpadding="0"
cellspacing="2">
<tbody>
<tr>
<td valign="top"><br>
</td>
<td valign="top"><em>api_required</em> </td>
<td>The minimum API number your plugin
requires. Look at the source for the
value of <code>GEANY_API_VERSION</code>
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. </td>
</tr>
</tbody>
</table>
</dd>
</dl>
</li>
</ul>
======================================================<br>
The above documentation is crap.<br>
</div>
</blockquote>
<div><br>
</div>
<div style="">Which isn't a very helpful comment.</div>
<div><br>
</div>
<div> <br>
</div>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<div bgcolor="#FFFFFF" text="#000000"> <br>
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?</div>
</blockquote>
<div><br>
</div>
<div style="">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.</div>
<div><br>
</div>
<div> </div>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<div bgcolor="#FFFFFF" text="#000000"> <br>
So we can skip the test<br>
if(abi_ver blah blah)<br>
unless somebody can answer the above question.<br>
</div>
</blockquote>
<div><br>
</div>
<div style="">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.</div>
<div><br>
</div>
<div> </div>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<div bgcolor="#FFFFFF" text="#000000"> <br>
So that leads to the last line of code that generates
stuff:<br>
return api_required;<br>
<br>
I eliminated superfluous parens.<br>
</div>
</blockquote>
<div> </div>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<div bgcolor="#FFFFFF" text="#000000">As documented, this
macro returns what it is passed.<br>
</div>
</blockquote>
<div><br>
</div>
<div style="">Only *IF* the abi matches.</div>
<div><br>
</div>
<div> </div>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<div bgcolor="#FFFFFF" text="#000000"> <br>
And you wonder why I'm confused?<br>
<br>
BTW, this one is<br>
<dl>
<dt><b>Since:</b></dt>
<dd>0.19 </dd>
</dl>
<br>
</div>
</blockquote>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<div bgcolor="#FFFFFF" text="#000000"><br>
<br>
</div>
<br>
_______________________________________________<br>
Devel mailing list<br>
<a moz-do-not-send="true"
href="mailto:Devel@lists.geany.org">Devel@lists.geany.org</a><br>
<a moz-do-not-send="true"
href="https://lists.geany.org/cgi-bin/mailman/listinfo/devel"
target="_blank">https://lists.geany.org/cgi-bin/mailman/listinfo/devel</a><br>
<br>
</blockquote>
</div>
<br>
</div>
</div>
<br>
<fieldset class="mimeAttachmentHeader"></fieldset>
<br>
<pre wrap="">_______________________________________________
Devel mailing list
<a class="moz-txt-link-abbreviated" href="mailto:Devel@lists.geany.org">Devel@lists.geany.org</a>
<a class="moz-txt-link-freetext" href="https://lists.geany.org/cgi-bin/mailman/listinfo/devel">https://lists.geany.org/cgi-bin/mailman/listinfo/devel</a>
</pre>
</blockquote>
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.<br>
<br>
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.<br>
<br>
Sorry, I forgot to genuflect.<br>
<br>
<br>
</body>
</html>