[clang] Document extensions from later standards

[aaron.ballman]

Thank you for working on this! Just a few questions, but in general, this is looking good.

clang/docs/LanguageExtensions.rst

1386

This brings up a few questions for me: how should we handle C? For example, designated initializers also exist in C99 and are backported to C89? And how should we handle C features extended into C++ (or vice versa)?

Should we have multiple tables? Should we try to put both languages into one table with different columns?

(I'm not asking you to sign up to figure out the C extensions, just trying to get an idea for whether we want to change the layout of this table to account for that sort of thing.)

1387

What are your thoughts on extensions enabled by a feature flag? e.g., https://godbolt.org/z/ex9K5dzv6

[H-G-Hristov]

clang/docs/LanguageExtensions.rst

1398

[philnik]

clang/docs/LanguageExtensions.rst

1386

I think it would make sense to put C features that are back-ported into previous standards also into this table (are there FTMs for C?). C into C++ or vice versa should probably live somewhere else, since in these cases it would also be interesting how things interact with other language features. Maybe this is not as much of a problem for C++->C(?), but definitely for C->C++. e.g. __restrict on member functions or VLAs with non-trivial classes. Essentially, there is a lot more to say than "this also exists in previous standards".

1387

I actually had no idea they existed (might be worth documenting :P)! Specifically for this case: Is there any reason this is behind a feature flag? I guess it's a non-conforming extension? If not, I'd say just make it an enabled-by-default extension (it would be a really nice cleanup opportunity for libc++). Anyways, we could add another column "flags required" for these cases. Do you know how many of these kinds of flags there are?

[aaron.ballman]

clang/docs/LanguageExtensions.rst

1386

I think it would make sense to put C features that are back-ported into previous standards also into this table (are there FTMs for C?).

Okay, I think that makes sense to me. Clang has feature test macros for some C functionality (e.g., c_generic_selections, more full list at: https://github.com/llvm/llvm-project/blob/main/clang/include/clang/Basic/Features.def#L241)

C into C++ or vice versa should probably live somewhere else, since in these cases it would also be interesting how things interact with other language features.

Sold!

1387

I actually had no idea they existed (might be worth documenting :P)!

Right? https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-fdouble-square-bracket-attributes exists but is hardly ideal.

Specifically for this case: Is there any reason this is behind a feature flag? I guess it's a non-conforming extension? If not, I'd say just make it an enabled-by-default extension (it would be a really nice cleanup opportunity for libc++).

It's a bit of an odd situation. I added the feature flag because I wanted to expose this functionality in C before WG14 adopted the functionality and it wasn't entirely clear whether I would run into ambiguities with Objective-C's message sending syntax. C++ has this language rule: http://eel.is/c++draft/dcl.dcl#dcl.attr.grammar-7 but Objective-C allows for things like [[foo bar] baz];. We had already solved this for C++, but it wasn't entirely clear whether we'd hit other situations in older language modes or different situations.

These days, it may be possible we could enable this extension by default in all language modes.

Anyways, we could add another column "flags required" for these cases. Do you know how many of these kinds of flags there are?

I can't think of many... Features.def lists the language options required for various features and extensions, and it doesn't look like many have specific flags, though there are some that needs a more general flag like -fms-extensions. We do have things like -fno-rtti disabling RTTI, but I don't think we want to list that sort of thing here.

[philnik]

Address comments

[aaron.ballman]

LGTM, this is awesome -- thank you for the improved docs!

clang/docs/LanguageExtensions.rst

1373

Seems to be the style we're using for this level of heading.

clang/docs/LanguageExtensions.rst

 Modules
 -------
 
 Use ``__has_feature(modules)`` to determine if Modules have been enabled.
 For example, compiling code with ``-fmodules`` enables the use of Modules.
 
 More information could be found `here <https://clang.llvm.org/docs/Modules.html>`_.
 
+Language Extensions Back-ported to Previous Standards
+=====================================================
+
+=================================== ================================ ============= ============= ==================================
+Feature                             Feature Test Macro               Introduced In Backported To Required Flags
+=================================== ================================ ============= ============= ==================================
+variadic templates                  __cpp_variadic_templates         C++11         C++03
+Alias templates                     __cpp_alias_templates            C++11         C++03
+Non-static data member initializers __cpp_nsdmi                      C++11         C++03
+Range-based ``for`` loop            __cpp_range_based_for            C++11         C++03
+RValue references                   __cpp_rvalue_references          C++11         C++03
+Attributes                          __cpp_attributes                 C++11         C++03         -fdouble-square-bracket-attributes
+variable templates                  __cpp_variable_templates         C++14         C++03
+Binary literals                     __cpp_binary_literals            C++14         C++03
+Relaxed constexpr                   __cpp_constexpr                  C++14         C++11
+``if constexpr``                    __cpp_if_constexpr               C++17         C++11
+fold expressions                    __cpp_fold_expressions           C++17         C++03
+Lambda capture of \*this by value   __cpp_capture_star_this          C++17         C++11
+Attributes on enums                 __cpp_enumerator_attributes      C++17         C++11
+Guaranteed copy elision             __cpp_guaranteed_copy_elision    C++17         C++03
+Hexadecimal floating literals       __cpp_hex_float                  C++17         C++03
+``inline`` variables                __cpp_inline_variables           C++17         C++03
+Attributes on namespaces            __cpp_namespace_attributes       C++17         C++11
+Structured bindings                 __cpp_structured_bindings        C++17         C++03
+template template arguments         __cpp_template_template_args     C++17         C++03
+``static operator[]``               __cpp_multidimensional_subscript C++20         C++03
+Designated initializers             __cpp_designated_initializers    C++20         C++03
+Conditional ``explicit``            __cpp_conditional_explicit       C++20         C++03
+``using enum``                      __cpp_using_enum                 C++20         C++03
+``if consteval``                    __cpp_if_consteval               C++23         C++20
+``static operator()``               __cpp_static_call_operator       C++23         C++03
+----------------------------------- -------------------------------- ------------- ------------- ----------------------------------
+Designated initializers                                              C99           C89
+=================================== ================================ ============= ============= ==================================
+
 Type Trait Primitives
 =====================
 
 Type trait primitives are special builtin constant expressions that can be used
 by the standard C++ library to facilitate or simplify the implementation of
 user-facing type traits in the <type_traits> header.
 
 They are not intended to be used directly by user code because they are