Add section 'Plugin API/ABI design'.

git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@4127 ea778897-0a13-0410-b9d1-a72fbfd435f5

ChangeLog

@@ -3,6 +3,8 @@
  * doc/plugins.dox:
    Add warning about not using undocumented features.
    Add reference to HACKING for plugin API development.
+ * HACKING:
+   Add section 'Plugin API/ABI design'.
 
 
 2009-08-25  Enrico Tröger  <enrico(dot)troeger(at)uvena(dot)de>

HACKING

@@ -72,7 +72,7 @@ the existing elements stay in place - this will keep the ABI stable.
 
 .. warning::
 
-	Some structs like GeanyKeyGroup and GeanyCallback cannot be
+	Some structs like GeanyKeyGroupInfo and GeanyCallback cannot be
 	appended to without breaking the ABI because they are used to declare
 	structs by plugins, not just for accessing struct members through
 	a pointer.
@@ -82,7 +82,7 @@ even the API can change. An ABI change just means that all plugins will
 not load and they must be rebuilt. An API change means that some plugins
 might not build correctly.
 
-When reordering or changing existing elements of structs that are
+If you're reordering or changing existing elements of structs that are
 used as part of the plugin API, you should increment GEANY_ABI_VERSION
 in plugindata.h. This is usually not needed if you're just appending
 fields to structs. The GEANY_API_VERSION value should be incremented
@@ -90,6 +90,15 @@ for any changes to the plugin API, including appending elements.
 
 If you're in any doubt when making changes to plugin API code, just ask us.
 
+Plugin API/ABI design
+---------------------
+You should not make plugins rely on the size of a struct. This means:
+
+* Don't let plugins allocate any structs (stack or heap).
+* Don't let plugins index any arrays of structs.
+* Don't add any array fields to structs in case we want to change the
+  array size later.
+
 Glade
 -----
 Use the code generation features of Glade instead of editing interface.c