STYLE: document some rules about variable declarations

[notmuch] / devel / STYLE

diff --git a/devel/STYLE b/devel/STYLE
index 92de42ccc9ba1847234532a88b58840ab5b0151a..b22d8d353e15c11c0827bf7adf38e8eefe8843ba 100644 (file)
--- a/devel/STYLE
+++ b/devel/STYLE
@@ -25,9 +25,7 @@ The following nonsense code demonstrates many aspects of the style:
 static some_type
 function (param_type param, param_type param)
 {
-   int i;
-
-   for (i = 0; i < 10; i++) {
+   for (int i = 0; i < 10; i++) {
        int j;
 
        j = i + 10;
@@ -64,6 +62,9 @@ function (param_type param, param_type param)
 * Code lines should be less than 80 columns and comments should be
   wrapped at 70 columns.
 
+* Variable declarations should be at the top of a block; C99 style
+  control variable declarations in for loops are also OK.
+
 Naming
 ------
 
@@ -93,3 +94,13 @@ libnotmuch conventions
 
 * Code which needs to be accessed from both the CLI and from
   libnotmuch should be factored out into libutil (under util/).
+
+* Deprecated functions should be marked with the NOTMUCH_DEPRECATED
+  macro which generates run time warnings with gcc and clang. In order
+  not to confuse doxygen this should go at the beginning of the
+  declaration like:
+
+  NOTMUCH_DEPRECATED(major,minor) notmuch_status_t notmuch_dwim(void *arg);
+
+  The @deprecated doxygen command can be used to generate markup in
+  the API docs.