HybridDog/geany
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add 'Doc-comments' plugin API subsection.

Browse Source 
git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@4368 ea778897-0a13-0410-b9d1-a72fbfd435f5
This commit is contained in:
Nick Treleaven 2009-10-26 15:16:04 +00:00
parent 29b8a57133
commit 87ec6a3a2d
2 changed files with 15 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
ChangeLog
View File

@ -11,6 +11,8 @@
* src/build.c, src/build.h: * src/build.c, src/build.h:
Move function doc-comments to build.c so they stay in sync. Note: Move function doc-comments to build.c so they stay in sync. Note:
these functions are still not in the API. these functions are still not in the API.
* HACKING:
Add 'Doc-comments' plugin API subsection.
2009-10-25 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de> 2009-10-25 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>

16
HACKING
View File

@ -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 See the top of each ``src/*.c`` file for a brief description of what
it's for. it's for.
Keeping the plugin ABI stable Plugin API code
----------------------------- ---------------
Please be aware that anything with a doc-comment (a comment with an Please be aware that anything with a doc-comment (a comment with an
extra asterix: ``/**``) is something in the plugin API. Things like extra asterix: ``/**``) is something in the plugin API. Things like
enums and structs can usually still be appended to, ensuring that all 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 structs by plugins, not just for accessing struct members through
a pointer. a pointer.
Keeping the plugin ABI stable
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Before the 1.0 release series, the ABI can change when necessary, and 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 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 not load and they must be rebuilt. An API change means that some plugins
might not build correctly. might not build correctly.
If you're 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 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 in plugindata.h. This is usually not needed if you're just appending
fields to structs. The GEANY_API_VERSION value should be incremented fields to structs. The GEANY_API_VERSION value should be incremented
for any changes to the plugin API, including appending elements. 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 * Don't add any array fields to structs in case we want to change the
array size later. 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 Glade
----- -----
Use the code generation features of Glade instead of editing interface.c Use the code generation features of Glade instead of editing interface.c