[Bug web/88860] Clarify gcc online manual 6.38 Attribute Syntax

[Bug web/88860] Clarify gcc online manual 6.38 Attribute Syntax

[jg at jguk dot org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=88860

--- Comment #1 from Jonny Grant <jg at jguk dot org> ---
2022-12-26  Jonathan Grant <jg@jguk.org>
        * gcc/doc/extend.texi: Bugzilla 88860 - Add attribute format printf
example



From 1668dc58206428ee92ff142bafb5f545dba029ae Mon Sep 17 00:00:00 2001
From: Jonathan Grant <jg@jguk.org>
Date: Mon, 26 Dec 2022 21:02:35 +0000
Subject: [PATCH] Bugzilla 88860 - Clarify gcc online manual attribute format
 printf example

Signed-off-by: Jonathan Grant <jg@jguk.org>
---
 gcc/doc/extend.texi | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 88fc625050b..9b200c6f3a0 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -9353,6 +9353,13 @@ __attribute__((noreturn)) void d0 (void),
 the @code{noreturn} attribute applies to all the functions
 declared; the @code{format} attribute only applies to @code{d1}.

+@noindent
+The following __attribute__ causes gcc to check run printf argument checks on
argument '3' which is 'const char * string format' (when visible at compile
time), against argument '4' the '...' variadic ellipsis.  In the example below,
arguments '1' and '2' are not checked.
+
+@smallexample
+void string_format(const char * prefix, size_t line, const char * const
format, ...) __attribute__ ((format (printf,3,4)));
+@end smallexample
+
 An attribute specifier list may appear immediately before the comma,
 @code{=} or semicolon terminating the declaration of an identifier other
 than a function definition.  Such attribute specifiers apply
-- 
2.37.2

[Bug web/88860] Clarify gcc online manual 6.38 Attribute Syntax

[jg at jguk dot org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=88860

--- Comment #2 from Jonny Grant <jg at jguk dot org> ---

2022-12-26  Jonathan Grant <jg@jguk.org>
        * gcc/doc/extend.texi: Bugzilla 88860 - Clarify online manual
infelicities


>From 8b142ad8973dc67289e197e30966490a944e4819 Mon Sep 17 00:00:00 2001
From: Jonathan Grant <jg@jguk.org>
Date: Mon, 26 Dec 2022 20:58:29 +0000
Subject: [PATCH] Bugzilla 88860 - Clarify gcc online manual infelicities

Signed-off-by: Jonathan Grant <jg@jguk.org>
---
 gcc/doc/extend.texi | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index adba057c190..88fc625050b 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -9190,7 +9190,7 @@ have to optimize it to just @code{return 42 + 42;}.
 This section describes the syntax with which @code{__attribute__} may be
 used, and the constructs to which attribute specifiers bind, for the C
 language.  Some details may vary for C++ and Objective-C@.  Because of
-infelicities in the grammar for attributes, some forms described here
+limitations in the grammar for attributes, some forms described here
 may not be successfully parsed in all cases.

 There are some problems with the semantics of attributes in C++.  For
-- 
2.37.2

[Bug web/88860] Clarify gcc online manual 6.38 Attribute Syntax

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=88860

--- Comment #3 from Jonathan Wakely <redi at gcc dot gnu.org> ---
Please send patches to the mailing list instead of attaching them here where
they will not get reviewed.

https://gcc.gnu.org/contribute.html#patches

[Bug web/88860] Clarify gcc online manual 6.38 Attribute Syntax

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=88860

--- Comment #4 from Jonathan Wakely <redi at gcc dot gnu.org> ---
(In reply to Jonny Grant from comment #1)
> --- a/gcc/doc/extend.texi
> +++ b/gcc/doc/extend.texi
> @@ -9353,6 +9353,13 @@ __attribute__((noreturn)) void d0 (void),
>  the @code{noreturn} attribute applies to all the functions
>  declared; the @code{format} attribute only applies to @code{d1}.
>  
> +@noindent
> +The following __attribute__ causes gcc to check run printf argument checks

"check run printf argument checks"


> on argument '3' which is 'const char * string format' (when visible at
> compile time), against argument '4' the '...' variadic ellipsis.  In the
> example below, arguments '1' and '2' are not checked.
> +
> +@smallexample
> +void string_format(const char * prefix, size_t line, const char * const
> format, ...) __attribute__ ((format (printf,3,4)));
> +@end smallexample


This argument seems to be documenting the effects of the printf attribute, not
attribute syntax. Why would it belong on this page?

[Bug web/88860] Clarify gcc online manual 6.38 Attribute Syntax

[jg at jguk dot org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=88860

--- Comment #5 from Jonny Grant <jg at jguk dot org> ---
(In reply to Jonathan Wakely from comment #4)
> (In reply to Jonny Grant from comment #1)
> > --- a/gcc/doc/extend.texi
> > +++ b/gcc/doc/extend.texi
> > @@ -9353,6 +9353,13 @@ __attribute__((noreturn)) void d0 (void),
> >  the @code{noreturn} attribute applies to all the functions
> >  declared; the @code{format} attribute only applies to @code{d1}.
> >  
> > +@noindent
> > +The following __attribute__ causes gcc to check run printf argument checks
> 
> "check run printf argument checks"
> 
> 
> > on argument '3' which is 'const char * string format' (when visible at
> > compile time), against argument '4' the '...' variadic ellipsis.  In the
> > example below, arguments '1' and '2' are not checked.
> > +
> > +@smallexample
> > +void string_format(const char * prefix, size_t line, const char * const
> > format, ...) __attribute__ ((format (printf,3,4)));
> > +@end smallexample
> 
> 
> This argument seems to be documenting the effects of the printf attribute,
> not attribute syntax. Why would it belong on this page?

You're right, I found this page with an example that is fine

https://gcc.gnu.org/onlinedocs/gcc-12.2.0/gcc/Common-Function-Attributes.html#Common-Function-Attributes

Re the patches, I recall I did email them, but pasted here too as another
developer was doing that. I'll have a good read of that contribution guide.

What did you think of the "infelicities" patch?
Thanks

[Bug web/88860] Clarify gcc online manual 6.38 Attribute Syntax

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=88860

--- Comment #6 from Jonathan Wakely <redi at gcc dot gnu.org> ---
(In reply to Jonny Grant from comment #5)
> Re the patches, I recall I did email them, but pasted here too as another
> developer was doing that. I'll have a good read of that contribution guide.

If you've emailed them to the list then it's better to link to the mails in the
list archive, not duplicate them here.

> What did you think of the "infelicities" patch?

It loses a little of the nuance, i.e. that the limitations are unfortunate. But
I think it's an improvement.

[Bug web/88860] Clarify gcc online manual 6.38 Attribute Syntax

[jg at jguk dot org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=88860

--- Comment #7 from Jonny Grant <jg at jguk dot org> ---
(In reply to Jonathan Wakely from comment #6)
> (In reply to Jonny Grant from comment #5)
> > Re the patches, I recall I did email them, but pasted here too as another
> > developer was doing that. I'll have a good read of that contribution guide.
> 
> If you've emailed them to the list then it's better to link to the mails in
> the list archive, not duplicate them here.
>  
> > What did you think of the "infelicities" patch?
> 
> It loses a little of the nuance, i.e. that the limitations are unfortunate.
> But I think it's an improvement.

Ok thank you. May I ask if you could commit the patch please?

[Bug web/88860] Clarify gcc online manual 6.38 Attribute Syntax

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=88860

--- Comment #8 from Jonathan Wakely <redi at gcc dot gnu.org> ---
Has it been reviewed and approved? I can't do that for patches outside the
libstdc++-v3 dir.

[Bug web/88860] Clarify gcc online manual 6.38 Attribute Syntax

[jg at jguk dot org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=88860

--- Comment #9 from Jonny Grant <jg at jguk dot org> ---
(In reply to Jonathan Wakely from comment #8)
> Has it been reviewed and approved? I can't do that for patches outside the
> libstdc++-v3 dir.

I've not yet received a reply to it on gcc-patches list.

https://gcc.gnu.org/pipermail/gcc-patches/2022-December/609132.html

[Bug web/88860] Clarify gcc online manual 6.38 Attribute Syntax

[cvs-commit at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=88860

--- Comment #10 from CVS Commits <cvs-commit at gcc dot gnu.org> ---
The master branch has been updated by Jeff Law <law@gcc.gnu.org>:

https://gcc.gnu.org/g:d9922e4bb5d8014ff3e4057442bbd6d2ed58cc36

commit r13-6607-gd9922e4bb5d8014ff3e4057442bbd6d2ed58cc36
Author: Jeff Law <jlaw@ventanamicro>
Date:   Sat Mar 11 09:34:19 2023 -0700

    Fwd: [PATCHJ]: Bugzilla 88860 - Clarify online manual infelicities

    gcc/
            PR web/88860
            * doc/extend.texi: Clarify Attribute Syntax a bit.