Bug 553032 - document MOZ_FORMAT_PRINTF; r=froydnj

MozReview-Commit-ID: 4qX1nltLBxf

--HG--
extra : rebase_source : 5d82dbe8108fc5d9926cc0586a78dc753251f896

mfbt/Attributes.h

@@ -570,7 +570,29 @@
 #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)  \