[clang] Document the warn_unused attribute (PR #201881)

[Aaron Ballman via cfe-commits]

================
@@ -388,6 +388,34 @@ pointer, but not any provenance of the allocation:
   }];
 }
 
+def WarnUnusedDocs : Documentation {
+  let Category = DocCatType;
+  let Content = [{
+The ``warn_unused`` attribute can be placed on the declaration of a structure or union type.
+When the ``-Wunused-variable`` diagnostic is enabled, local variables of types which have a non-trivial constructor or destructor are considered "used" by virtue of the constructor or destructor invocations involved.
+Declaring the type with the ``warn_unused`` attribute strengthens the "use" requirements to require a direct access to the variable, such as passing it as an argument to a call, calling a member function on it, taking the address of it, etc.
----------------
AaronBallman wrote:

Is this a bit better?

Btw, I ended up filing https://github.com/llvm/llvm-project/issues/202326 while updating the docs in case you're wondering about "outside of its declaration" and whether the initialization counts or not.

https://github.com/llvm/llvm-project/pull/201881