[cfe-dev] Clang attributes documentation website

[Aaron Ballman via cfe-dev]

On Wed, Dec 5, 2018 at 6:34 PM George Karpenkov <ekarpenkov at apple.com> 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