Hi all,
I'm thinking about adding an extra information to "since" tag of the plugin API documentation. It currently only gives the Geany version the symbol appeared on, but generally the developer also need to know the plugin API version in which it was introduced, e.g. in order to get the API requirement right.
So, I'm suggesting to add this information whenever we add a new plugin API function (and why not update the current doc when we can), e.g.:
@since 0.21 (API 206)
or whatever format we prefer.
Why I am starting this discussion is to know what the core developers think of it (Nick, Enrico?), and whether the plugin developers thinks it's useful for them or not. So all, what do you think?
Cheers, Colomban
P.S.: Actually I already did this once (but forgot to start this thread), in r5650 [1].
[1] http://git.geany.org/geany/commit/?id=15ace45ae1e853ffa728e02114629179b95b52...
On Thu, 14 Apr 2011 00:19:24 +0200, Colomban wrote:
Hi all,
I'm thinking about adding an extra information to "since" tag of the plugin API documentation. It currently only gives the Geany version the symbol appeared on, but generally the developer also need to know the plugin API version in which it was introduced, e.g. in order to get the API requirement right.
So, I'm suggesting to add this information whenever we add a new plugin API function (and why not update the current doc when we can), e.g.:
@since 0.21 (API 206)
or whatever format we prefer.
I'd say why not. It doesn't hurt. I don't find it totally necessary as plugin developers always should depend on the latest available API version of the current development version of Geany if they use any new features. Still, it's only a bit more information and so why not.
About the format: I'd say:
* @since 0.21 (GEANY_API_VERSION 209)
I used this for now in SVN r5727. But I'm totally open about this.
Regards, Enrico
Le 17/04/2011 16:01, Enrico Tröger a écrit :
On Thu, 14 Apr 2011 00:19:24 +0200, Colomban wrote:
Hi all,
I'm thinking about adding an extra information to "since" tag of the plugin API documentation. It currently only gives the Geany version the symbol appeared on, but generally the developer also need to know the plugin API version in which it was introduced, e.g. in order to get the API requirement right.
So, I'm suggesting to add this information whenever we add a new plugin API function (and why not update the current doc when we can), e.g.:
@since 0.21 (API 206)
or whatever format we prefer.
I'd say why not. It doesn't hurt. I don't find it totally necessary as plugin developers always should depend on the latest available API version of the current development version of Geany if they use any new features. Still, it's only a bit more information and so why not.
My thought was that some plugin authors may want their plugin to work with the oldest Geany version that provides the API they actually use. And to do this, they need to *know* what API version they actually use, so in which one a function or another was introduced.
About the format: I'd say:
- @since 0.21 (GEANY_API_VERSION 209)
I used this for now in SVN r5727.
Why not, it at least is very clear :)
Cheers, Colomban
On Thu, 14 Apr 2011 00:19:24 +0200 Colomban Wendling lists.ban@herbesfolles.org wrote:
It currently only gives the Geany version the symbol appeared on, but generally the developer also need to know the plugin API version in which it was introduced, e.g. in order to get the API requirement right.
So, I'm suggesting to add this information whenever we add a new plugin API function (and why not update the current doc when we can), e.g.:
@since 0.21 (API 206)
or whatever format we prefer.
Why I am starting this discussion is to know what the core developers think of it (Nick, Enrico?), and whether the plugin developers thinks it's useful for them or not. So all, what do you think?
I think it duplicates information too much. There could be a lookup table for Geany version -> API number instead.
Regards, Nick
Le 21/04/2011 15:14, Nick Treleaven a écrit :
On Thu, 14 Apr 2011 00:19:24 +0200 Colomban Wendling lists.ban@herbesfolles.org wrote:
It currently only gives the Geany version the symbol appeared on, but generally the developer also need to know the plugin API version in which it was introduced, e.g. in order to get the API requirement right.
So, I'm suggesting to add this information whenever we add a new plugin API function (and why not update the current doc when we can), e.g.:
@since 0.21 (API 206)
or whatever format we prefer.
Why I am starting this discussion is to know what the core developers think of it (Nick, Enrico?), and whether the plugin developers thinks it's useful for them or not. So all, what do you think?
I think it duplicates information too much.
Well, IMHO the Geany version (0.21 here) is useful for the end user and for the developer to tell her users "you need at least Geany vX.Y to run this plugin", and the plugin API version is useful for the developer to fill PLUGIN_VERSIO_CHECK().
There could be a lookup table for Geany version -> API number instead.
Why not, sounds reasonably useful and easy to do :) However I'd prefer have the reverse match to let developer depend on the real API they need rather than "the release that provides this API". But maybe it's not important, it's development versions anyway.
Cheers, Colomban