C and C++ attributes, declaration and cross-referencing

[jakobandersen]

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, and cpp_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_attributes and cpp_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 up always_inline as gnu::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:: cdecl

The @ 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?

[marxin]

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.

It's likely not a valid name, but I'm not an expert in the area.

[marxin]

Generally speaking, I like the suggested concept. Note it can behave similarly to how :program: and :option: work. So cpp:attr-namespace would define a namespace (cpp:attr-namespace:: gnu::@x86 ) and then all attribute refs (like cdecl) would lead to to gnu::@x86:cdecl.

I think adding cpp:attribute is a good idea on its own.

[marxin]

Are you planning @jakobandersen finishing this feature any time soon, please?

[jakobandersen]

Are you planning @jakobandersen finishing this feature any time soon, please?

As soon as a I find time :-).

[2bndy5]

Would this also mean we can document a namespace declaration or is that a separate issue? I think breathe uses a modified type declaration for that.