From 87ec6a3a2d114975b203bf85748d7112dd8aca5d Mon Sep 17 00:00:00 2001 From: Nick Treleaven Date: Mon, 26 Oct 2009 15:16:04 +0000 Subject: [PATCH] Add 'Doc-comments' plugin API subsection. git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@4368 ea778897-0a13-0410-b9d1-a72fbfd435f5 --- ChangeLog | 2 ++ HACKING | 16 +++++++++++++--- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/ChangeLog b/ChangeLog index 07d89764..7a064235 100644 --- a/ChangeLog +++ b/ChangeLog @@ -11,6 +11,8 @@ * src/build.c, src/build.h: Move function doc-comments to build.c so they stay in sync. Note: these functions are still not in the API. + * HACKING: + Add 'Doc-comments' plugin API subsection. 2009-10-25 Enrico Tröger diff --git a/HACKING b/HACKING index aa62bd24..203c9876 100644 --- a/HACKING +++ b/HACKING @@ -66,8 +66,8 @@ Avoid adding code to geany.h if it will fit better elsewhere. See the top of each ``src/*.c`` file for a brief description of what it's for. -Keeping the plugin ABI stable ------------------------------ +Plugin API code +--------------- Please be aware that anything with a doc-comment (a comment with an extra asterix: ``/**``) is something in the plugin API. Things like enums and structs can usually still be appended to, ensuring that all @@ -80,13 +80,15 @@ the existing elements stay in place - this will keep the ABI stable. structs by plugins, not just for accessing struct members through a pointer. +Keeping the plugin ABI stable +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Before the 1.0 release series, the ABI can change when necessary, and 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. 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 +used as part of the plugin API, you must 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 for any changes to the plugin API, including appending elements. @@ -102,6 +104,14 @@ You should not make plugins rely on the size of a struct. This means: * Don't add any array fields to structs in case we want to change the array size later. +Doc-comments +^^^^^^^^^^^^ +* The @file tag can go in the source .c file, but use the .h header name so + it appears normally in the generated documentation. See ui_utils.c for an + example. +* Function doc-comments should always go in the source file, not the + header, so they can be updated if/when the implementation changes. + Glade ----- Use the code generation features of Glade instead of editing interface.c