[Geany-Devel] Plugin API design question/change proposal

[Matthew Brush]

Hi,

Does anyone know why the plugin API was designed to use a bunch of 
structures containing function pointers, hidden behind macros in 
geanyfunctions.h? I found the commit where this stuff was added 
initially (ie. plugin ABI 2-3) but it doesn't mention why it was done 
like this and I tried to search the mailing list archives but Gmane 
won't let me search and the other mailing list archive doesn't go back 
that far.

Somebody mentioned it might be because Windows doesn't export symbols by 
default, but it still doesn't explain why this way chosen over 
explicitly exporting the symbols using 
__declspec(dllexport)/G_MODULE_EXPORT which, IIUC, does just this.

As mentioned in the "Proxy Plugins" thread I'm looking into making the 
headers scanned by GObject-introspection to automate binding the plugin 
API to non-C plugins, but with all of the private stuff and public stuff 
mixed together in public headers, it will be hard to do this.

Assuming there isn't actually much of a reason for the chosen existing 
function pointer/structure/macro mechanism, is anybody opposed to just 
making the API available in the normal C way where the public functions 
goes in one header that plugins (and core) can use, and one header where 
the private stuff goes, that doesn't get installed?

Just to see the work involved, I tried to do this with the build, 
document and editor functions. It makes the public/private more 
explicit, removes lots of extra code, makes only one place to update 
when adding new functions to the API, doesn't force plugins to import a 
bunch of private stuff indirectly by #including <geanyplugin.h>, still 
makes the symbols available/exported on Windows, and does it without 
breaking the official (ie. doxygen-commented) parts of the API (but it 
would need an ABI bump). The experimental changes to build, document, 
and editor functions are here in my header-cleanup-private branch, based 
ontop of my "header-cleanup" branch that I have an open PR for:

build.h/buildprivate.h
https://github.com/codebrainz/geany/commit/0b1221ce85905a066adfaae62fc73470b34af4d5

document.h/documentprivate.h
https://github.com/codebrainz/geany/commit/f5e03bbee2c4edc8fe66c8e0762ef86e1f130857

editor.h/editorprivate.h
https://github.com/codebrainz/geany/commit/1534f196d626494b57d408f780dfde022f18dd07

What we could do for commonly used existing private stuff:
https://github.com/codebrainz/geany/commit/ac02d5330af2bd2cfcff45609f0e5b02a8b9d72a

(Sorry, I just linked the relevant commits instead of the branch so 
people don't have to figure out which specific ones I'm talking about 
amidst all the other unrelated ones. It's mostly just to give an idea of 
what I'm talking about.)

I think this would be a fairly big improvement overall and it would 
finally allow us to sort out what's really private and what's really 
public, which will make bindings generated by scanning the headers much 
easier.

Some common stuff that wasn't public before (ie. doxygen-commented) but 
that is still used in plugins could be added as "deprecated" to the 
public header or if useful could be properly added with a doxygen 
comment. This will avoid excessive breakage where plugins were using 
private stuff.

Any opinions, suggestions, reasons about the original design welcome.

Cheers,
Matthew Brush