Bug 553032 - document MOZ_FORMAT_PRINTF; r=froydnj
authorTom Tromey <tom@tromey.com>
Thu, 13 Oct 2016 13:08:39 -0600
changeset 318953 7ece94001875a0fee5866091a70eb746fb0a4240
parent 318952 ce2b6b8bfa16cbbd398de071bfdfdd40b880999b
child 318954 65a272de7edaa23804374e6a9d390fe82ed20cbc
push id30855
push userryanvm@gmail.com
push dateFri, 21 Oct 2016 21:12:44 +0000
treeherdermozilla-central@5639a9f476d0 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersfroydnj
bugs553032
milestone52.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
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