[PATCH] D130018: [HLSL] Add HLSLResource attribute

Wed Jul 27 09:15:51 PDT 2022

aaron.ballman added inline comments.

================
Comment at: clang/include/clang/Basic/AttrDocs.td:6473-6475
+The HLSL ``resource`` attribute is not valid to manually specify in
+HLSL. It is applied by the compiler to HLSL resource type objects enabling them
+to be handled appropriately in CodeGen.
----------------
beanz wrote:
> aaron.ballman wrote:
> > Because the attribute cannot be written by the user, it seems like we shouldn't bother documenting this attribute at all. WDYT? If you agree, you can mark the attribute as `Undocumented` in Attr.td.
> Yea... I am kinda split mind on this myself, and I think the tl;dr is that this is the wrong place to document this.
> 
> The existing HLSL compiler and HLSL language are woefully short on documentation, so I'm trying to at least make a best-effort at documenting things as I implement them in clang. Since the AttrDocs are really intended to be user-facing documentation this is probably the wrong place to document it.
> 
> I'll pull this out and maybe separately create a folder under clang's docs directory for HLSL-related documentation so that it lives with the more project-centric docs. Does that make sense?
> I'll pull this out and maybe separately create a folder under clang's docs directory for HLSL-related documentation so that it lives with the more project-centric docs. Does that make sense?

I'm fine with that approach. FWIW, I've struggled with this a bit as well. We want all new attributes to be documented, and it's a sometimes super fuzzy line between "this is an implementation detail" and "users can use this with wild abandon". However, in this case, because the attribute has no spelling, it's pretty clearly an implementation detail. So putting that into the "using clang as a library" or other internal documentation.

Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D130018/new/

https://reviews.llvm.org/D130018