[doc PATCH] using multiple format-arg attributes on a single function (PR 87593)

[Martin Sebor <msebor at gmail dot com>]

Attached is a documentation-only patch to clarify the use case
of multiple distinct format_arg attributes on a single function.
It's far from obvious that the use case makes sense so explicitly
mentioning it should help avoid the mistake of assuming that
accepting it is due to the lack of better checking in the area
(it could also prompt Clang to support the use case -- likely
an omission due to its obscurity).

However, since it makes less sense to declare the same function
multiple times with distinct format_arg attributes, a follow-on
improvement would be to issue a warning on such instances.  I'll
leave the bug open until that's implemented.

Martin

gcc/ChangeLog:

	* doc/extend.texi (attribute format_arg): Discuss using multiple
	attributes on a single function.

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 0d9b99f..6355453 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -2698,13 +2699,15 @@ Target Machines}.
 @item format_arg (@var{string-index})
 @cindex @code{format_arg} function attribute
 @opindex Wformat-nonliteral
-The @code{format_arg} attribute specifies that a function takes a format
-string for a @code{printf}, @code{scanf}, @code{strftime} or
+The @code{format_arg} attribute specifies that a function takes one or
+more format strings for a @code{printf}, @code{scanf}, @code{strftime} or
 @code{strfmon} style function and modifies it (for example, to translate
 it into another language), so the result can be passed to a
 @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
 function (with the remaining arguments to the format function the same
-as they would have been for the unmodified string).  For example, the
+as they would have been for the unmodified string).  Multiple
+@code{format_arg} attributes may be applied to the same function, each
+designating a distinct parameter as a format string.  For example, the
 declaration:
 
 @smallexample
@@ -2724,6 +2727,11 @@ string argument is not constant; this would generate a warning when
 @option{-Wformat-nonliteral} is used, but the calls could not be checked
 without the attribute.
 
+In calls to a function declared with more than one @code{format_arg}
+attribute, each with a distinct argument value, the corresponding
+actual function arguments are checked against all format strings
+designated by the attributes.
+
 The parameter @var{string-index} specifies which argument is the format
 string argument (starting from one).  Since non-static C++ methods have
 an implicit @code{this} argument, the arguments of such methods should