Bug 553032 - document MOZ_FORMAT_PRINTF; r?froydnj draft
authorTom Tromey <tom@tromey.com>
Thu, 13 Oct 2016 13:08:39 -0600
changeset 427634 575190863fdc1289101ecc4701fb6d9d262a45fd
parent 427633 6d4a2f86c9140165899e7bfa35bbcd900fa5ad43
child 427635 39611bab4a6ec51d8e1e4b1fd035cec3b0c2a632
push id33071
push userbmo:ttromey@mozilla.com
push dateThu, 20 Oct 2016 17:13:29 +0000
reviewersfroydnj
bugs553032
milestone52.0a1
Bug 553032 - document MOZ_FORMAT_PRINTF; r?froydnj MozReview-Commit-ID: 4qX1nltLBxf
mfbt/Attributes.h
--- a/mfbt/Attributes.h
+++ b/mfbt/Attributes.h
@@ -565,17 +565,39 @@
 #  if MOZ_GCC_VERSION_AT_LEAST(4, 8, 1)
 #    define MOZ_HAVE_REF_QUALIFIERS
 #  endif
 #endif
 
 #endif /* __cplusplus */
 
 /**
- * Printf style formats
+ * Printf style formats.  MOZ_FORMAT_PRINTF can be used to annotate a
+ * function or method that is "printf-like"; this will let (some)
+ * compilers check that the arguments match the template string.
+ *
+ * This macro takes two arguments.  The first argument is the argument
+ * number of the template string.  The second argument is the argument
+ * number of the '...' argument holding the arguments.
+ *
+ * Argument numbers start at 1.  Note that the implicit "this"
+ * argument of a non-static member function counts as an argument.
+ *
+ * So, for a simple case like:
+ *   void print_something (int whatever, const char *fmt, ...);
+ * The corresponding annotation would be
+ *   MOZ_FORMAT_PRINTF(2, 3)
+ * However, if "print_something" were a non-static member function,
+ * then the annotation would be:
+ *   MOZ_FORMAT_PRINTF(3, 4)
+ *
+ * Note that the checking is limited to standards-conforming
+ * printf-likes, and in particular this should not be used for
+ * PR_snprintf and friends, which are "printf-like" but which assign
+ * different meanings to the various formats.
  */
 #ifdef __GNUC__
 #define MOZ_FORMAT_PRINTF(stringIndex, firstToCheck)  \
     __attribute__ ((format (printf, stringIndex, firstToCheck)))
 #else
 #define MOZ_FORMAT_PRINTF(stringIndex, firstToCheck)
 #endif