Re: [PATCH] gcc/doc: list what version each attribute was introduced in

[Sandra Loosemore <sandra at codesourcery dot com>]

On 07/06/2017 07:25 AM, Daniel P. Berrange wrote:
> There are several hundred named attribute keys that have been
> introduced over many GCC releases. Applications typically need
> to be compilable with multiple GCC versions, so it is important
> for developers to know when GCC introduced support for each
> attribute.
>
> This augments the texi docs that list attribute keys with
> a note of what version introduced the feature. The version
> information was obtained through archaeology of the GCC source
> repository release tags, back to gcc-4_0_0-release. For
> attributes added in 4.0.0 or later, an explicit version will
> be noted. Any attribute that predates 4.0.0 will simply note
> that it has existed prior to 4.0.0. It is thought there is
> little need to go further back in time than 4.0.0 since few,
> if any, apps will still be using such old compiler versions.
>
> Where a named attribute can be used in many contexts (ie the
> 'visibility' attribute can be used for both functions or
> variables), it was assumed that the attribute was supported
> in all use contexts at the same time.
>
> Future patches that add new attributes to GCC should be
> required to follow this new practice, by documenting the
> version.

I have to reject this documentation patch as-is because the new material 
isn't in complete sentences ending with a period.

I'm also skeptical that it's a good idea overall to add this information 
to the GCC manual, although I'll bow to the wishes of the community on 
this.  The arguments I'd make against adding it are:

(1) The GCC manual is already tied to a specific version of GCC and 
searchable manuals for old versions of GCC are readily available online.

(2) Information about backward compatibility with old versions becomes 
less relevant as time goes on, and I've already removed a bunch of cruft 
describing changes that happened 10-20+ years ago.

(3) We don't have similar historical information for any other GCC 
language extensions, builtins, etc.

(4) The manual is already too long.

If the consensus of the community is that we really need this historical 
information in the current manual, I'll consider a revised patch.

-Sandra