SF.net SVN: geany:[4579] branches/geany-0.18.1

[ntrel at users.sourceforge.net]

Revision: 4579
          http://geany.svn.sourceforge.net/geany/?rev=4579&view=rev
Author:   ntrel
Date:     2010-01-28 16:47:32 +0000 (Thu, 28 Jan 2010)

Log Message:
-----------
Backport:
Add 'Doc-comments' plugin API subsection.

Modified Paths:
--------------
    branches/geany-0.18.1/ChangeLog
    branches/geany-0.18.1/HACKING

Modified: branches/geany-0.18.1/ChangeLog
===================================================================
--- branches/geany-0.18.1/ChangeLog	2010-01-28 16:42:38 UTC (rev 4578)
+++ branches/geany-0.18.1/ChangeLog	2010-01-28 16:47:32 UTC (rev 4579)
@@ -1,3 +1,9 @@
+2009-10-26  Nick Treleaven  <nick(dot)treleaven(at)btinternet(dot)com>
+
+ * HACKING:
+   Add 'Doc-comments' plugin API subsection.
+
+
 2009-09-27  Nick Treleaven  <nick(dot)treleaven(at)btinternet(dot)com>
 
  * configure.in:

Modified: branches/geany-0.18.1/HACKING
===================================================================
--- branches/geany-0.18.1/HACKING	2010-01-28 16:42:38 UTC (rev 4578)
+++ branches/geany-0.18.1/HACKING	2010-01-28 16:47:32 UTC (rev 4579)
@@ -66,8 +66,8 @@
 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 @@
 	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 @@
 * 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


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.