Description
Background
As of now the C and C++ domains can parse attributes in declarations in different formats:
- C++11 style, e.g.,
[[fallthrough]] - GNU style, e.g.,
__attribute__((__noreturn__)) - User-defined identifiers given in
c_id_attributes, andcpp_id_attributes.
This helps when users have an object-like macro that expands to an attribute. - User-defined function-like names given in
c_paren_attributesandcpp_paren_attributes.
This helps when users have a function-like macro that expands to an attribute.
All attributes are rendered without any cross-references in the output.
Based on a conversation with @marxin regarding the GCC docs, it would be desirable to be able to document attributes, and even have different versions depending on which target architecture one considers.
Suggestion and Questions
Like macro declarations, the attribute handling really should not exist in only the C or C++ domain, or have two versions, but it should be common. But setting that problem aside and just assuming the cpp domain for now, how about the following mechanism for attributes:
A new directive cpp:attribute which as argument is given a string which starts with a possibly qualified name and optionally continues with a parameter list, where each parameter is just an identifier. Examples:
.. cpp:attribute:: fallthrough
.. cpp:attribute:: gnu::always_inline
.. cpp:attribute:: nodiscard(reason)Perhaps a new attribute namespacing directive cpp:attr-namespace as a parallel to cpp:namesapce which sets the default namespace for attributes. E.g.,
.. cpp:attr-namespace:: gnu
.. cpp:attribute:: always_inline
Declares the attribute ``gnu::always_inline``Note, this attribute namespace is completely orthogonal to C++ namespaces.
A new role cpp:attr for referencing an attribute, e.g., :cpp:attr:`fallthrough` . Its lookup would be affected by the current attr-namespace, e.g., with .. cpp:attr-namespace:: gnu then :cpp:attr:`always_inline` would work as well.
More detailed parsing and output generation of attributes, where each attribute name becomes a pending xref to be resolved:
- The GNU style attributes would automatically get the
gnu::prefix for lookup. - The C++11 style attributes would be resolved directly, though the C++17 "using" should be parsed and taken into account. E.g.,
[[using gnu : always_inline]]would look upalways_inlineasgnu::always_inline.
Then there is the architecture-dependent attributes. @marxin, if I read the standard correctly, then a C++17 attribute can only have 1 level of scoping, i.e., a::b::c is not a valid attribute name. Do you know if GCC and other compilers would reject it as well?
If so, then we can, as you have suggested, use something a second namespace name, like gnu::@x86::cdecl as the formal Sphinx name for an architecture-dependent attribute, which could be declared as
.. cpp:attr-namespace:: gnu::@x86
.. cpp:attribute:: cdeclThe @ is to be sure it is not a valid identifier, should nesting become valid C++, similarly to how the C and C++ domains handles anon entities already.
How should cross-referencing work? References where the architecture is included would work. But is there a need for references where the architecture is implicit? E.g., gnu::cdecl?