lib: array - explain implications of ARRAY_TYPE() in comment

If you use ARRAY_TYPE() to pass an array around, then you must also
use ARRAY_TYPE() to define the array itself, ARRAY() will no longer do.

Reported-by: Arnt Gulbrandsen <arnt@gulbrandsen.priv.no>
Signed-off-by: Phil Carmody <phil@dovecot.fi>

diff --git a/src/lib/array.h b/src/lib/array.h
index 84b6726762722a1d54dd8f916e86bd69d1c0a577..865567bf487998dbdf12ec1cd238cca2267d8ce1 100644 (file)
--- a/src/lib/array.h
+++ b/src/lib/array.h
@@ -20,14 +20,22 @@
 
    If you want to pass an array as a parameter to a function, you'll need to
    create a type for the array using ARRAY_DEFINE_TYPE() and use the type in
-   the parameter using ARRAY_TYPE().
+   the parameter using ARRAY_TYPE(). Any arrays that you want to be passing
+   around, such as structure members as in the above example, must also be
+   defined using ARRAY_TYPE() too, rather than ARRAY().
 
    Example:
 
    ARRAY_DEFINE_TYPE(foo, struct foo);
-   void do_foo(ARRAY_TYPE(foo) *bars) {
-       struct foo *foo = array_idx(bars, 0);
+   void do_foo(ARRAY_TYPE(foo) *foos) {
+       struct foo *foo = array_idx(foos, 0);
    }
+   struct foo_manager {
+        ARRAY_TYPE(foo) foos; // pedantically, ARRAY(struct foo) is a different type
+   };
+   // ...
+        do_foo(&my_foo_manager->foos); // No compiler warning about mismatched types
+
 */
 #include "array-decl.h"
 #include "buffer.h"