Bug 553032 - document MOZ_FORMAT_PRINTF; r=froydnj
☠☠ backed out by 0c9cc278b8f4 ☠ ☠
authorTom Tromey <tom@tromey.com>
Thu, 13 Oct 2016 13:08:39 -0600
changeset 318513 e832fc3b5a03041da9af10c22b3517137c93edbc
parent 318512 16f326945f3831edc2b8f2c7482650863df827b0
child 318514 818fc5631d72200e868ea4cdcd97f3d1f09e4970
push id33319
push userttromey@mozilla.com
push dateWed, 19 Oct 2016 16:16:25 +0000
treeherderautoland@9055ad92499a [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