You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
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
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?
The text was updated successfully, but these errors were encountered:
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.
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.
Background
As of now the C and C++ domains can parse attributes in declarations in different formats:
[[fallthrough]]
__attribute__((__noreturn__))
c_id_attributes
, andcpp_id_attributes
.This helps when users have an object-like macro that expands to an attribute.
c_paren_attributes
andcpp_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:Perhaps a new attribute namespacing directive
cpp:attr-namespace
as a parallel tocpp:namesapce
which sets the default namespace for attributes. E.g.,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 currentattr-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:
gnu::
prefix for lookup.[[using gnu : always_inline]]
would look upalways_inline
asgnu::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 asThe
@
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
?The text was updated successfully, but these errors were encountered: