Clang attributes documentation website

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

Clang attributes documentation website

Oleg Smolsky via cfe-dev
Hi Aaron (also CC-ing the list),

I have noticed that if multiple attributes share the same documentation,
the documentation gets duplicated: e.g. retain count attributes at https://clang.llvm.org/docs/AttributeReference.html

Wouldn’t it make more sense to group the attributes and show the documentation below to avoid duplication?

Thanks,
George

_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|

Re: Clang attributes documentation website

Oleg Smolsky via cfe-dev
On Wed, Dec 5, 2018 at 6:34 PM George Karpenkov <[hidden email]> wrote:
>
> Hi Aaron (also CC-ing the list),
>
> I have noticed that if multiple attributes share the same documentation,
> the documentation gets duplicated: e.g. retain count attributes at https://clang.llvm.org/docs/AttributeReference.html.
>
> Wouldn’t it make more sense to group the attributes and show the documentation below to avoid duplication?

This happens automatically when the attributes are logically grouped
by semantic attribute in Attr.td. e.g.,

  let Spellings = [Clang<"acquire_capability", 0>,
                   Clang<"acquire_shared_capability", 0>,
                   GNU<"exclusive_lock_function">,
                   GNU<"shared_lock_function">];

results in

https://clang.llvm.org/docs/AttributeReference.html#acquire-capability-acquire-shared-capability

This is useful for cases where you have the same (or roughly the same)
semantics under multiple different logical spellings. We also have the
ability to create custom categories to group related attributes
together (see `DocCatCallingConvs` in AttrDocs.td as an example).

I think the docs shouldn't be shared between multiple attributes for
the case you point out. Instead, the attributes should be put into the
same documentation category with common documentation put there, and
individual *(distinct) documentation attached to the attributes.

~Aaron
_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev