Open jakobandersen opened 2 years ago
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.
Are you planning @jakobandersen finishing this feature any time soon, please?
Are you planning @jakobandersen finishing this feature any time soon, please?
As soon as a I find time :-).
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.
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, likegnu::@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
?